Current version is 1.0.0-beta.23, click here for the index

Azure OpenTelemetry Tracing plugin library for Java

This package enables distributed tracing across Azure SDK Java libraries through OpenTelemetry. OpenTelemetry is an open source, vendor-agnostic, single distribution of libraries to provide metrics collection and distributed tracing for services. The Azure core tracing package provides:

Context propagation, used to correlate activities and requests between services with an initial customer action.
Tracing user requests to the system, allowing to pinpoint failures and performance issues.

Source code | API reference documentation | Product documentation | Samples

Getting started

Prerequisites

A Java Development Kit (JDK), version 8 or later.

Include the package

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
  <version>1.0.0-beta.23</version>
</dependency>

Key concepts

Trace

A trace is a tree of spans showing the path of work through a system. A trace on its own is distinguishable by a unique 16 byte sequence called a TraceID.

Span

A span represents a single operation in a trace. A span could be representative of an HTTP request, a remote procedure call (RPC), a database query, or even the path that a code takes.

Examples

The following sections provides examples of using the azure-core-tracing-opentelemetry plugin with a few Azure Java SDK libraries:

Using the plugin package with HTTP client libraries

Synchronously create a secret using azure-security-keyvault-secrets with tracing enabled.

The plugin package creates a logical span representing public API call to encapsulate all the underlying HTTP calls. By default OpenTelemetry Context.current() will be used as a parent context - check out OpenTelemetry documentation for more info. Users can optionally pass the instance of io.opentelemetry.context.Context to the SDKs using key PARENTTRACECONTEXT_KEY on the Context parameter of the calling method to provide explicit parent context. This sample provides an example when no user parent span is passed.

// Get the Tracer Provider
static TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider();
private static final Tracer TRACER = configureOpenTelemetryAndLoggingExporter();

public static void main(String[] args) {
   doClientWork();
}

public static void doClientWork() {
    SecretClient client = new SecretClientBuilder()
      .endpoint("<your-vault-url>")
      .credential(new DefaultAzureCredentialBuilder().build())
      .buildClient();

    Span span = TRACER.spanBuilder("user-span").startSpan();
    try (Scope scope = TRACER.withSpan(span)) {
        // Thread bound (sync) calls will automatically pick up the parent span and you don't need to pass it explicitly.
        secretClient.setSecret(new Secret("secret_name", "secret_value"));
    } finally {
        span.end();
    }

    // alternatively, you can pass context explicitly
    // Span span = TRACER.spanBuilder("user-span").startSpan();
    // Context traceContext = new Context(PARENT_TRACE_CONTEXT_KEY, io.opentelemetry.context.Context.current().with(span));
    // secretClient.setSecretWithResponse(new Secret("secret_name", "secret_value"), traceContext);
    // span.end();
}

Using the plugin package with AMQP client libraries

Send a single event/message using azure-messaging-eventhubs with tracing enabled.

Users can additionally pass the value of the current tracing span to the EventData object with key PARENTTRACECONTEXT_KEY on the Context object:

// Get the Tracer Provider
private static TracerSdkProvider tracerProvider = OpenTelemetrySdk.getTracerProvider();
private static final Tracer TRACER = configureOpenTelemetryAndLoggingExporter();

private static void doClientWork() {
    EventHubProducerClient producer = new EventHubClientBuilder()
        .connectionString(CONNECTION_STRING)
        .buildProducerClient();

    Span span = TRACER.spanBuilder("user-span").startSpan();
    try (Scope scope = TRACER.withSpan(span)) {
        EventData event1 = new EventData("1".getBytes(UTF_8));

        // you may pass context explicitly, if you don't pass any, implicit 
        // Context.current() will be used
        // event1.addContext(PARENT_TRACE_CONTEXT_KEY, Context.current());

        EventDataBatch eventDataBatch = producer.createBatch();

        if (!eventDataBatch.tryAdd(eventData)) {
            producer.send(eventDataBatch);
            eventDataBatch = producer.createBatch();
        }
    } finally {
        span.end();
    }
}

Troubleshooting

General

For more information on OpenTelemetry Java support for tracing, see OpenTelemetry Java.

Enabling Logging

Azure SDKs for Java offer a consistent logging story to help aid in troubleshooting application errors and expedite their resolution. The logs produced will capture the flow of an application before reaching the terminal state to help locate the root issue. View the logging wiki for guidance about enabling logging.

Next steps

Samples

Several Java SDK samples are available to you in the SDKs GitHub repository. These following samples provide example code for additional scenarios commonly encountered while working with Tracing:

Set Configuration Setting - Tracing enabled Sample for setting a configuration setting using azure-data-app-configuration.
List Key Vault Secrets - Tracing enabled sample for creating and listing secrets of a Key Vault using azure-security-keyvault-secrets.
Publish Events - Tracing enabled sample for publishing multiple events using azure-messaging-eventhubs.
Async List Key Vault Secrets - Tracing enabled sample for asynchronously creating and listing secrets of a Key Vault using azure-security-keyvault-secrets.

Additional Documentation

For more extensive documentation on OpenTelemetry, see the API reference documentation.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Packages
Package	Description
com.azure.core.tracing.opentelemetry	An OpenTelemetry implementation of the tracing APIs required by azure-core to enable users to effectively trace their calls and have this information submitted to an OpenTelemetry backend.

Azure SDK for Java Reference Documentation