Skip to content

Commit f4ff74c

Browse files
lalitblalitb
authored
Add Getting started documentation for otel-cpp sdk (#942)
1 parent 555f4e8 commit f4ff74c

1 file changed

Lines changed: 219 additions & 2 deletions

File tree

‎docs/public/sdk/GettingStarted.rst‎

Lines changed: 219 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,221 @@
11
Getting started
2-
---------------
2+
^^^^^^^^^^^^^^^
33

4-
TBD
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 = 6831;
54+
opts.headers = {{}}; // optional headers
55+
auto jaeger_udp_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:4317/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+
opentelemetry::sdk::trace::AlwaysOnSampler always_on_sampler;
140+
141+
//AlwaysOffSampler
142+
opentelemetry::sdk::trace::AlwaysOffSampler always_off_sampler;
143+
144+
//ParentBasedSampler
145+
opentelemetry::sdk::trace::ParentBasedSampler sampler_off(std::make_shared<AlwaysOffSampler>());
146+
147+
//TraceIdRatioBasedSampler - Sample 50% generated spans
148+
double ratio = 0.5;
149+
opentelemetry::sdk::trace::TraceIdRatioBasedSampler s(ratio);
150+
151+
152+
TracerContext
153+
^^^^^^^^^^^^^
154+
155+
SDK configuration are shared between `TracerProvider` and all it's `Tracer` instances through `TracerContext`.
156+
157+
.. code:: cpp
158+
159+
auto tracer_context = std::make_shared<sdktrace::TracerContext>
160+
(std::move(multi_processor), resource, std::move(always_on_sampler));
161+
162+
TracerProvider
163+
^^^^^^^^^^^^^^
164+
165+
`TracerProvider` instance holds the SDK configurations ( Span Processors, Samplers, Resource). There is single
166+
global TracerProvider instance for an application, and it is created at the start of application.
167+
There are two different mechanisms to create TraceProvider instance
168+
169+
- Using constructor which takes already created TracerContext shared object as parameter.
170+
- Using consructor which takes SDK configurations as parameter.
171+
172+
.. code:: cpp
173+
174+
// Created using `TracerContext` instance
175+
auto tracer_provider = sdktrace::TracerProvider(tracer_context);
176+
177+
// Create using SDK configurations as parameter
178+
auto tracer_provider =
179+
sdktrace::TracerProvider(std::move(simple_processor), resource, std::move(always_on_sampler));
180+
181+
// set the global tracer TraceProvider
182+
opentelemetry::trace::Provider::SetTracerProvider(provider);
183+
184+
185+
Logging and Error Handling
186+
^^^^^^^^^^^^^^^^^^^^^^^^^^
187+
188+
OpenTelemetry C++ SDK provides mechanism for application owner to add customer log and error handler.
189+
The default log handler is redirected to standard output ( using std::cout ).
190+
191+
The logging macro supports logging using C++ stream format, and key-value pair.
192+
The log handler is meant to capture errors and warnings arising from SDK, not supposed to be used for the application errors.
193+
The different log levels are supported - Error, Warn, Info and Debug. The default log level is Warn ( to dump both Error and Warn)
194+
and it can be changed at compile time.
195+
196+
.. code:: cpp
197+
198+
OTEL_INTERNAL_LOG_ERROR
199+
(" Connection failed. Error string " << error_str << " Error Num: " << errorno);
200+
OTEL_INTERNAL_LOG_ERROR
201+
(" Connection failed." , {{"error message: " : error_str},{"error number": errorno}});
202+
OTEL_INTERNAL_LOG_DEBUG
203+
(" Connection Established Successfully. Headers:", {{"url", url},{"content-length", len}, {"content-type", type}});
204+
205+
The custom log handler can be defined by inheriting from `sdk::common::internal_log::LogHandler` class.
206+
207+
.. code:: cpp
208+
209+
class CustomLogHandler : public sdk::common::internal_log::LogHandler
210+
{
211+
void Handle(Loglevel level,
212+
const char \*file,
213+
int line,
214+
const char \*msg,
215+
const sdk::common::AttributeMap &attributes)
216+
217+
{
218+
// add implementation here
219+
}
220+
};
221+
sdk::common::internal_log::GlobalLogHandler::SetLogHandler(CustomLogHandler());

0 commit comments

Comments
 (0)
⚡