Azure SDK Core Tracing Library for C++

Azure::Core::Tracing::OpenTelemetry (azure-core-tracing-opentelemetry) provides an implementation to enable customers to implement tracing in the Azure SDK for C++ libraries.

Include the package

The easiest way to acquire the OpenTelemetry library is leveraging vcpkg package manager. See the corresponding Azure SDK for C++ readme section.

To install Azure Core OpenTelemetry package via vcpkg:

> vcpkg install azure-core-tracing-opentelemetry-cpp

Then, use in your CMake file:

find_package(azure-core-tracing-opentelemetry-cpp CONFIG REQUIRED)

target_link_libraries(<your project name> PRIVATE Azure::azure-core-tracing-opentelemetry)

The azure-core-tracing-opentelemetry package supports enabling tracing for Azure SDK packages, using an OpenTelemetry Tracer.

By default, all libraries log with a NoOpTracer that takes no action. To enable tracing, you will need to set a global tracer provider following the instructions in the OpenTelemetry getting started guide or the Enabling Tracing using OpenTelemetry example below.

Span Propagation

Core Tracing supports both automatic and manual span propagation. Automatic propagation is handled using OpenTelemetry's API and will work well in most scenarios.

For customers who require manual propagation, all client library operations accept an optional field in the options parameter where a tracingContext can be passed in and used as the currently active context. Please see the Manual Span Propagation example below for more details.

OpenTelemetry Compatibility

Most Azure SDKs use OpenTelemetry to support tracing. Specifically, we depend on the opentelemetry-cpp VCPKG package.

Enabling tracing using OpenTelemetry

std::shared_ptr<Azure::Core::Tracing::TracerProvider> tracerProvider = Azure::Core::OpenTelemetry::TracerProvider::Create();

ApplicationContext().SetTracerProvider(tracerProvider);

After this, the SDK API implementations will be able to retrieve the tracer provider and produce tracing events automatically.

Enabling tracing using a non-default TracerProvider

auto exporter = std::make_unique<opentelemetry::exporter::memory::InMemorySpanExporter>();

m_spanData = exporter->GetData();

auto simple_processor = std::unique_ptr<opentelemetry::sdk::trace::SpanProcessor>(

new opentelemetry::sdk::trace::SimpleSpanProcessor(std::move(exporter)));

auto always_on_sampler = std::unique_ptr<opentelemetry::sdk::trace::AlwaysOnSampler>(

new opentelemetry::sdk::trace::AlwaysOnSampler);

auto resource_attributes = opentelemetry::sdk::resource::ResourceAttributes{

{"service.name", "telemetryTest"}, {"service.instance.id", "instance-1"}};

auto resource = opentelemetry::sdk::resource::Resource::Create(resource_attributes);

new opentelemetry::sdk::trace::TracerProvider(

std::move(simple_processor), resource, std::move(always_on_sampler)));

std::shared_ptr<Azure::Core::Tracing::TracerProvider> tracerProvider =

Azure::Core::OpenTelemetry::TracerProvider::Create(openTelemetryProvider);

ApplicationContext().SetTracerProvider(tracerProvider);

Manual Span Propagation using OpenTelemetry

In Azure Service methods, the Azure::Context value passed into the tracer optionally has an associated Span.

If there is a span associated with the Azure::Context, then calling DiagnosticTracingFactory::CreateSpanFromContext will cause a new span to be created using the span in the provided Azure::Context object as the parent span.

auto contextAndSpan

= Azure::Core::Tracing::_internal::DiagnosticTracingFactory::CreateSpanFromContext(

"HTTP GET#2", context);

You can build and run the tests locally by executing azure-core-tracing-opentelemetry-test. Explore the test folder to see advanced usage and behavior of the public classes.

If you run into issues while using this library, please feel free to file an issue.

OpenTelemetry Compatibility Errors

Ideally you'd want to use OpenTelemetry 1.3.0 or higher.

Reporting security issues and security bugs

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) secur.nosp@m.e@mi.nosp@m.croso.nosp@m.ft.c.nosp@m.om. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.