ceph/src/jaegertracing/opentelemetry-cpp/docs/public/sdk/GettingStarted.rst

   1 Getting started
   2 ^^^^^^^^^^^^^^^
   3
   4 OpenTelemetry C++ SDK provides the reference implementation of OpenTelemetry C++ API,
   5 and also provides implementation for Processor, Sampler, and core Exporters as per the
   6 specification.
   7
   8
   9 Exporter
  10 ^^^^^^^^
  11
  12 An exporter is responsible for sending the telemetry data to a particular backend.
  13 OpenTelemetry offers six tracing exporters out of the box:
  14
  15 - In-Memory Exporter: keeps the data in memory, useful for debugging.
  16 - Jaeger Exporter: prepares and sends the collected telemetry data to a Jaeger backend via UDP and HTTP.
  17 - Zipkin Exporter: prepares and sends the collected telemetry data to a Zipkin backend via the Zipkin APIs.
  18 - Logging Exporter: saves the telemetry data into log streams.
  19 - OpenTelemetry(otlp) Exporter: sends the data to the OpenTelemetry Collector using protobuf/gRPC or protobuf/HTTP.
  20 - ETW Exporter: sends the telemetry data to Event Tracing for Windows (ETW).
  21
  22 .. code:: cpp
  23
  24     //namespace alias used in sample code here.
  25     namespace sdktrace   = opentelemetry::sdk::trace;
  26
  27     // logging exporter
  28     auto ostream_exporter =
  29         std::unique_ptr<sdktrace::SpanExporter>(new opentelemetry::exporter::trace::OStreamSpanExporter);
  30
  31     // memory exporter
  32     auto memory_exporter =
  33         std::unique_ptr<sdktrace::SpanExporter>(new opentelemetry::exporter::memory::InMemorySpanExporter);
  34
  35     // zipkin exporter
  36     opentelemetry::exporter::zipkin::ZipkinExporterOptions opts;
  37     opts.endpoint = "http://localhost:9411/api/v2/spans" ; // or export OTEL_EXPORTER_ZIPKIN_ENDPOINT="..."
  38     opts.service_name = "default_service" ;
  39     auto zipkin_exporter =
  40         std::unique_ptr<sdktrace::SpanExporter>(new opentelemetry::exporter::zipkin::ZipkinExporter(opts));
  41
  42     // Jaeger UDP exporter
  43     opentelemetry::exporter::jaeger::JaegerExporterOptions opts;
  44     opts.endpoint = "localhost";
  45     opts.server_port =  6831;
  46     auto jaeger_udp_exporter =
  47         std::unique_ptr<sdktrace::SpanExporter>(new opentelemetry::exporter::jaeger::JaegerExporter(opts));
  48
  49     // Jaeger HTTP exporter
  50     opentelemetry::exporter::jaeger::JaegerExporterOptions opts;
  51     opts.transport_format  = opentelemetry::exporter::jaeger::TransportFormat::kThriftHttp;
  52     opts.endpoint = "localhost";
  53     opts.server_port = 14268;
  54     opts.headers = {{}}; // optional headers
  55     auto jaeger_http_exporter =
  56         std::unique_ptr<sdktrace::SpanExporter>(new opentelemetry::exporter::jaeger::JaegerExporter(opts));
  57
  58
  59     // otlp grpc exporter
  60     opentelemetry::exporter::otlp::OtlpGrpcExporterOptions opts;
  61     opts.endpoint = "localhost::4317";
  62     opts.use_ssl_credentials = true;
  63     opts.ssl_credentials_cacert_as_string = "ssl-certificate";
  64     auto otlp_grpc_exporter =
  65         std::unique_ptr<sdktrace::SpanExporter>(new opentelemetry::exporter::otlp::OtlpGrpcExporter(opts));
  66
  67     // otlp http exporter
  68     opentelemetry::exporter::otlp::OtlpHttpExporterOptions opts;
  69     opts.url = "http://localhost:4318/v1/traces";
  70     auto otlp_http_exporter =
  71         std::unique_ptr<sdktrace::SpanExporter>(new opentelemetry::exporter::otlp::OtlpHttpExporter(opts));
  72
  73
  74 Span Processor
  75 ^^^^^^^^^^^^^^
  76
  77 Span Processor is initialised with an Exporter. Different Span Processors are offered by OpenTelemetry C++ SDK:
  78
  79 - SimpleSpanProcessor: immediately forwards ended spans to the exporter.
  80 - BatchSpanProcessor: batches the ended spans and send them to exporter in bulk.
  81 - MultiSpanProcessor: Allows multiple span processors to be active and configured at the same time.
  82
  83 .. code:: cpp
  84
  85     // simple processor
  86     auto simple_processor = std::unique_ptr<sdktrace::SpanProcessor>(
  87         new sdktrace::SimpleSpanProcessor(std::move(ostream_exporter)));
  88
  89     // batch processor
  90     sdktrace::BatchSpanProcessorOptions options{};
  91     auto batch_processor = std::unique_ptr<sdktrace::SpanProcessor>(
  92         new sdktrace::BatchSpanProcessor(std::move(memory_exporter), options));
  93
  94     // multi-processor
  95     std::vector<std::unique_ptr<SpanProcessor>>
  96         processors{std::move(simple_processor), std::move(batch_processor)};
  97     auto multi_processor = std::unique_ptr<sdktrace::SpanProcessor>(
  98         new sdktrace::MultiSpanProcessor(std::move(processors));
  99
 100 Resource
 101 ^^^^^^^^
 102
 103 A Resource is an immutable representation of the entity producing telemetry as key-value pair.
 104 The OpenTelemetry C++ SDK allow for creation of Resources and for associating them with telemetry.
 105
 106 .. code:: cpp
 107
 108     auto resource_attributes = opentelemetry::sdk::resource::ResourceAttributes
 109         {
 110             {"service.name", "shoppingcart"},
 111             {"service.instance.id", "instance-12"}
 112         };
 113     auto resource = opentelemetry::sdk::resource::Resource::Create(resource_attributes);
 114     auto received_attributes = resource.GetAttributes();
 115     // received_attributes contains
 116     //      - service.name = shoppingcart
 117     //      - service.instance.id = instance-12
 118     //      - telemetry.sdk.name = opentelemetry
 119     //      - telemetry.sdk.language = cpp
 120     //      - telemetry.sdk.version = <current sdk version>
 121
 122 It is possible to define the custom resource detectors by inhering from
 123 `opentelemetry::sdk::Resource::ResourceDetector` class.
 124
 125 Sampler
 126 ^^^^^^^
 127
 128 Sampling is mechanism to control/reducing the number of samples of traces collected and sent to the backend.
 129 OpenTelemetry C++ SDK  offers four samplers out of the box:
 130
 131 - AlwaysOnSampler which samples every trace regardless of upstream sampling decisions.
 132 - AlwaysOffSampler which doesn’t sample any trace, regardless of upstream sampling decisions.
 133 - ParentBased which uses the parent span to make sampling decisions, if present.
 134 - TraceIdRatioBased which samples a configurable percentage of traces.
 135
 136 .. code:: cpp
 137
 138     //AlwaysOnSampler
 139     auto always_on_sampler = std::unique_ptr<sdktrace::AlwaysOnSampler>
 140         (new sdktrace::AlwaysOnSampler);
 141
 142     //AlwaysOffSampler
 143     auto always_off_sampler = std::unique_ptr<sdktrace::AlwaysOffSampler>
 144         (new sdktrace::AlwaysOffSampler);
 145
 146     //ParentBasedSampler
 147     auto parent_based_sampler = std::unique_ptr<sdktrace::ParentBasedSampler>
 148         (new sdktrace::ParentBasedSampler);
 149
 150     //TraceIdRatioBasedSampler - Sample 50% generated spans
 151     double ratio       = 0.5;
 152     auto always_off_sampler = std::unique_ptr<sdktrace::TraceIdRatioBasedSampler>
 153         (new sdktrace::TraceIdRatioBasedSampler(ratio));
 154
 155 TracerContext
 156 ^^^^^^^^^^^^^
 157
 158 SDK configuration are shared between `TracerProvider` and all it's `Tracer` instances through `TracerContext`.
 159
 160 .. code:: cpp
 161
 162     auto tracer_context = std::make_shared<sdktrace::TracerContext>
 163         (std::move(multi_processor), resource, std::move(always_on_sampler));
 164
 165 TracerProvider
 166 ^^^^^^^^^^^^^^
 167
 168 `TracerProvider` instance holds the SDK configurations ( Span Processors, Samplers, Resource). There is single
 169 global TracerProvider instance for an application, and it is created at the start of application.
 170 There are two different mechanisms to create TraceProvider instance
 171
 172 - Using constructor which takes already created TracerContext shared object as parameter.
 173 - Using consructor which takes SDK configurations as parameter.
 174
 175 .. code:: cpp
 176
 177     // Created using `TracerContext` instance
 178     auto tracer_provider = nostd::shared_ptr<sdktrace::TracerProvider>
 179         (new sdktrace::TracerProvider(tracer_context));
 180
 181     // Create using SDK configurations as parameter
 182     auto tracer_provider = nostd::shared_ptr<sdktrace::TracerProvider>
 183         (std::move(simple_processor), resource, std::move(always_on_sampler));
 184
 185     // set the global tracer TraceProvider
 186     opentelemetry::trace::Provider::SetTracerProvider(tracer_provider);
 187
 188
 189 Logging and Error Handling
 190 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 191
 192 OpenTelemetry C++ SDK provides mechanism for application owner to add customer log and error handler.
 193 The default log handler is redirected to standard output ( using std::cout ).
 194
 195 The logging macro supports logging using C++ stream format, and key-value pair.
 196 The log handler is meant to capture errors and warnings arising from SDK, not supposed to be used for the application errors.
 197 The different log levels are supported - Error, Warn, Info and Debug. The default log level is Warn ( to dump both Error and Warn)
 198 and it can be changed at compile time.
 199
 200 .. code:: cpp
 201
 202     OTEL_INTERNAL_LOG_ERROR(" Connection failed. Error string " << error_str << " Error Num: " << errorno);
 203     opentelemetry::sdk::common::AttributeMap error_attributes = {
 204       {"url", url}, {"content-length", len}, {"content-type", type}};
 205     OTEL_INTERNAL_LOG_ERROR(" Connection failed." , error_attributes);
 206     opentelemetry::sdk::common::AttributeMap http_attributes = {
 207       {"url", url}, {"content-length", len}, {"content-type", type}};
 208     OTEL_INTERNAL_LOG_DEBUG(" Connection Established Successfully. Headers:", http_attributes);
 209
 210 The custom log handler can be defined by inheriting from `opentelemetry::sdk::common::internal_log::LogHandler` class.
 211
 212 .. code:: cpp
 213
 214     class CustomLogHandler : public opentelemetry::sdk::common::internal_log::LogHandler
 215     {
 216         void Handle(opentelemetry::sdk::common::internal_log::LogLevel level,
 217                     const char \*file,
 218                     int line,
 219                     const char \*msg,
 220                     const opentelemetry::sdk::common::AttributeMap &attributes) noexcept override
 221
 222         {
 223             // add implementation here
 224         }
 225     };
 226     opentelemetry::sdk::common::internal_log::GlobalLogHandler::SetLogHandler(CustomLogHandler());
 227     opentelemetry::sdk::common::internal_log::GlobalLogHandler::SetLogLevel(opentelemetry::sdk::common::internal_log::LogLevel::Debug);