ceph/src/jaegertracing/opentelemetry-cpp/docs/library-distribution.md

   1 # Library Distribution
   2
   3 This document describes the considerations and recommendations for using the
   4 OpenTelemetry-cpp library.
   5
   6 ## Definitions
   7
   8 ### Binary vs Source Distribution
   9
  10 The OpenTelemetry-cpp libraries (API and SDK) and any library that depends on
  11 them are expected to be distributed as either "source" or "binary" artifacts.
  12 This document defines these distribution models as:
  13
  14 * **Source** - The source code is shipped as-is and can be built as desired.
  15 * **Binary** - The library and/or its dependants may be distributed as pre-built
  16   binaries which can be built using different toolchains or compilers.
  17
  18 This document will focus on the specific challenges of the "binary" distribution
  19 model.
  20
  21 ### Library Binding Model
  22
  23 The library and its dependants can be distributed and bound (loaded) in multiple
  24 ways which are defined as follows:
  25
  26 * **Static Linkage** - The library is distributed as a compiled artifact (`.a`
  27   extension on Unix-like systems) which is linked and bound at compile-time.
  28 * **Dynamic Linkage with Early Binding** - The library is distributed as a
  29   compiled artifact (`.so` on Unix-like systems), and its binding is defined at
  30   compile-time. It is loaded by the dynamic linker when the application/library
  31   depending on it is started/loaded.
  32 * **Dynamic Linkage with Late Binding** - The library is distributed as a
  33   compiled artifact (`.so` on Unix-like systems), only its interface is known at
  34   compile-time. It is loaded dynamically (using `dlopen` on POSIX).
  35
  36 _NOTE: A library may itself link in other libraries based on any of the above._
  37
  38 ### Components
  39
  40 The following components will be considered for analysing the impact of
  41 different binding models and the recommendations.
  42
  43 * **OpenTelemetry Libraries** - The libraries produced from this project, the
  44   API library will contain a minimal implementation including some compiled
  45   globals/singletons such as `TracerProvider`.
  46 * **OpenTelemetry Instrumented Libraries** - A library that depends on the
  47   OpenTelemetry API library to generate telemetry.
  48 * **OpenTelemetry Implementations or Exporters** - A specific implementation of
  49   the OpenTelemetry API or the `exporters` may be provided externally (e.g.
  50   distributed by a vendor).
  51 * **Binary Executable** - The compiled binary that has `main()`, this also
  52   includes interpreters such as Python which will be considered. This binary may
  53   itself instrument using OpenTelemetry or register a specific implementation.
  54
  55 For more information on language-agnostic library, please see: [OpenTelemetry
  56 Specification Library
  57 Guidelines](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/library-guidelines.md).
  58
  59 ### ABI Compatibility
  60
  61 Some guarantees regarding binary compatibility will be necessary given the
  62 binary distribution model supported by this project. The policies and approach
  63 regarding this will be documented in [ABI Policy](abi-policy.md).
  64
  65 ## Recommendations
  66
  67 ### Link OpenTelemetry plugins for portability
  68
  69 If you're a vendor and you wish to distribute an OpenTelemetry plugin (either a
  70 full implementation of the API or an exporter), you need to take precautions
  71 when linking your plugin to ensure it's portable. Here are some steps you should
  72 follow:
  73
  74 * Ensure you compile to target portable architectures (e.g. x86-64).
  75 * Statically link most dependencies. You should statically both external
  76   dependencies and the standard C++ library. The exceptions are the standard C
  77   library and other low-level system libraries that need to be dynamically
  78   linked.
  79 * Use an export map to avoid unwanted symbol resolution. When statically linking
  80   dependencies in a dynamic library, care should be taken to make sure that
  81   symbol resolution for dependencies doesn't conflict with that of the app or
  82   other dynamic libraries. See this [StackOverflow
  83   post](https://stackoverflow.com/q/47841812/4447365) for more information.
  84 * Re-map symbols from the standard C library to portable versions. If you want
  85   to plugin to work on systems with different versions of the standard C
  86   library, you need to link to portable symbols. See this [StackOverflow
  87   answer](https://stackoverflow.com/a/20065096/4447365) for how to do this.
  88
  89 ## Example Scenarios
  90
  91 ### Statically compiled binary executable
  92
  93 Binary executable can be distributed with static linkage ,for all libraries
  94 known at compile time. In this case the OpenTelemetry API Library can be linked
  95 in statically, guaranteeing that only a single symbol is exported for
  96 singletons.
  97
  98 ### Dynamically linked binary executable
  99
 100 An application can link to the OpenTelemetry API but dynamically load an
 101 implementation at runtime. Under this mode, an application can work with any
 102 vendor's implementation by using it as a plugin.
 103
 104 For example, a C++ database server might add support for the OpenTelemetry API
 105 and exposes configuration options that let a user point to a vendor's plugin and
 106 load it with a JSON config. (With OpenTracing, Ceph explored a deployment
 107 scenario similar to this. See this
 108 [link](https://www.spinics.net/lists/ceph-devel/msg41007.html))
 109
 110 ### Non OpenTelemetry aware application with OpenTelemetry capability library
 111
 112 An application itself may not be OpenTelemetry-aware, but it can support
 113 OpenTelemetry via extensions.
 114
 115 Examples:
 116
 117 * The core NGINX application has no knowledge of tracing. However, through
 118   NGINX's dynamic module capability, tracing can be supported as a plugin. For
 119   instance, the [nginx-opentracing
 120   module](https://github.com/opentracing-contrib/nginx-opentracing) provides
 121   this type of extension and is used by projects such as Kubernete's [ingress
 122   controller](https://kubernetes.github.io/ingress-nginx/user-guide/third-party-addons/opentracing/).
 123 * The CPython binary also has no knowledge of OpenTelemetry, but C++ Python
 124   extension modules can be instrumented for OpenTelemetry.
 125
 126 Additionally, when multiple OpenTelemetry-aware extensions co-exist in the same
 127 application, the extensions should be able to coordinate and share context
 128 through the OpenTelemetry API's singletons.