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.

Getting started

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)

Key concepts

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.

Examples

Enabling tracing using OpenTelemetry

// Start by creating an OpenTelemetry Provider using the
// default OpenTelemetry tracer provider.
std::shared_ptr<Azure::Core::Tracing::TracerProvider> tracerProvider = Azure::Core::OpenTelemetry::TracerProvider::Create();
 
// Connect the tracerProvider to the current application context.
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

// Start by creating an OpenTelemetry Provider.
auto exporter = std::make_unique<MySpanExporter>();
 
// simple processor
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);
auto openTelemetryProvider = opentelemetry::nostd::shared_ptr<opentelemetry::trace::TracerProvider>(
        new opentelemetry::sdk::trace::TracerProvider(
            std::move(simple_processor), resource, std::move(always_on_sampler)));
 
// Use the default OpenTelemetry tracer provider.
std::shared_ptr<Azure::Core::Tracing::TracerProvider> tracerProvider = 
    Azure::Core::OpenTelemetry::TracerProvider::Create(openTelemetryProvider);
 
// Connect the tracerProvider to the current application context.
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);

Next steps

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.

Troubleshooting

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.

License

Azure SDK for C++ is licensed under the MIT license.