You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
104 lines
3.4 KiB
104 lines
3.4 KiB
Getting started |
|
--------------- |
|
|
|
Tracing |
|
~~~~~~~ |
|
|
|
When instrumenting libraries and applications, the most simple approach |
|
requires three steps. |
|
|
|
Obtain a tracer |
|
^^^^^^^^^^^^^^^ |
|
|
|
.. code:: cpp |
|
|
|
auto provider = opentelemetry::trace::Provider::GetTracerProvider(); |
|
auto tracer = provider->GetTracer("foo_library", "1.0.0"); |
|
|
|
The ``TracerProvider`` acquired in the first step is a singleton object |
|
that is usually provided by the OpenTelemetry C++ SDK. It is used to |
|
provide specific implementations for API interfaces. In case no SDK is |
|
used, the API provides a default no-op implementation of a |
|
``TracerProvider``. |
|
|
|
The ``Tracer`` acquired in the second step is needed to create and start |
|
``Span``\ s. |
|
|
|
Start a span |
|
^^^^^^^^^^^^ |
|
|
|
.. code:: cpp |
|
|
|
auto span = tracer->StartSpan("HandleRequest"); |
|
|
|
This creates a span, sets its name to ``"HandleRequest"``, and sets its |
|
start time to the current time. Refer to the API documentation for other |
|
operations that are available to enrich spans with additional data. |
|
|
|
Mark a span as active |
|
^^^^^^^^^^^^^^^^^^^^^ |
|
|
|
.. code:: cpp |
|
|
|
auto scope = tracer->WithActiveSpan(span); |
|
|
|
This marks a span as active and returns a ``Scope`` object. The scope object |
|
controls how long a span is active. The span remains active for the lifetime |
|
of the scope object. |
|
|
|
The concept of an active span is important, as any span that is created |
|
without explicitly specifying a parent is parented to the currently |
|
active span. A span without a parent is called root span. |
|
|
|
Create nested Spans |
|
^^^^^^^^^^^^^^^^^^^ |
|
|
|
.. code:: cpp |
|
|
|
auto outer_span = tracer->StartSpan("Outer operation"); |
|
auto outer_scope = tracer->WithActiveSpan(outer_span); |
|
{ |
|
auto inner_span = tracer->StartSpan("Inner operation"); |
|
auto inner_scope = tracer->WithActiveSpan(inner_span); |
|
// ... perform inner operation |
|
inner_span->End(); |
|
} |
|
// ... perform outer operation |
|
outer_span->End(); |
|
|
|
|
|
Spans can be nested, and have a parent-child relationship with other spans. |
|
When a given span is active, the newly created span inherits the active span's |
|
trace ID, and other context attributes. |
|
|
|
Context Propagation |
|
^^^^^^^^^^^^^^^^^^ |
|
|
|
.. code:: cpp |
|
|
|
// set global propagator |
|
opentelemetry::context::propagation::GlobalTextMapPropagator::SetGlobalPropagator( |
|
nostd::shared_ptr<opentelemetry::context::propagation::TextMapPropagator>( |
|
new opentelemetry::trace::propagation::HttpTraceContext())); |
|
|
|
// get global propagator |
|
HttpTextMapCarrier<opentelemetry::ext::http::client::Headers> carrier; |
|
auto propagator = |
|
opentelemetry::context::propagation::GlobalTextMapPropagator::GetGlobalPropagator(); |
|
|
|
//inject context to headers |
|
auto current_ctx = opentelemetry::context::RuntimeContext::GetCurrent(); |
|
propagator->Inject(carrier, current_ctx); |
|
|
|
//Extract headers to context |
|
auto current_ctx = opentelemetry::context::RuntimeContext::GetCurrent(); |
|
auto new_context = propagator->Extract(carrier, current_ctx); |
|
auto remote_span = opentelemetry::trace::propagation::GetSpan(new_context); |
|
|
|
|
|
|
|
``Context`` contains the meta-data of the currently active Span including Span Id, |
|
Trace Id, and flags. Context Propagation is an important mechanism in distributed |
|
tracing to transfer this Context across service boundary often through HTTP headers. |
|
OpenTelemetry provides a text-based approach to propagate context to remote services |
|
using the W3C Trace Context HTTP headers.
|
|
|