Azure Monitor OpenTelemetry Exporter client library for Java - version 1.0.0-beta.30

This client library provides support for exporting OpenTelemetry data to Azure Monitor. This package assumes your application is already instrumented with the OpenTelemetry SDK following the OpenTelemetry Specification.

Source code | Package (Maven) | API reference documentation | Product Documentation | Samples

Getting started

Prerequisites

• Java Development Kit (JDK) with version 8 or above
• Azure Subscription
• Application Insights resource

For more information, please read introduction to Application Insights.

Include the dependency

Add the Azure Monitor OpenTelemetry Exporter dependency.

Authentication

Get the connection string from the portal

In order to export telemetry data to Azure Monitor, you will need the instrumentation key to your Application Insights resource. To get your instrumentation key, go to Azure Portal, search for your resource. On the overview page of your resource, you will find the instrumentation key in the top right corner.

Setup the OpenTelemetry SDK to work with Azure Monitor exporter

If you have set the Application Insights connection string with the APPLICATIONINSIGHTS_CONNECTION_STRING environment variable, you can configure OpenTelemetry SDK auto-configuration for Azure in the following way:

AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
AzureMonitorExporter.customize(sdkBuilder);
OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();

You can also set the connection string in the code:

AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
AzureMonitorExporter.customize(sdkBuilder, "{connection-string}");
OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();

Examples

The following sections provide code samples using the OpenTelemetry Azure Monitor Exporter client library and OpenTelemetry SDK.

The following example shows how create a span:

AutoConfiguredOpenTelemetrySdkBuilder otelSdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();

AzureMonitorExporter.customize(otelSdkBuilder, "{connection-string}");

OpenTelemetry openTelemetry = otelSdkBuilder.build().getOpenTelemetrySdk();
Tracer tracer = openTelemetry.getTracer("Sample");

Span span = tracer.spanBuilder("spanName").startSpan();

// Make the span the current span
try (Scope scope = span.makeCurrent()) {
    // Your application logic here
    applicationLogic();
} catch (Throwable t) {
    span.recordException(t);
    throw t;
} finally {
    span.end();
}

The following example demonstrates how to add a span processor to the OpenTelemetry SDK autoconfiguration.

private static final AttributeKey<String> ATTRIBUTE_KEY = AttributeKey.stringKey("attributeKey");

public void spanProcessor() {
    AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();

    AzureMonitorExporter.customize(sdkBuilder);

    SpanProcessor spanProcessor = new SpanProcessor() {

        @Override
        public void onStart(Context context, ReadWriteSpan span) {
            span.setAttribute(ATTRIBUTE_KEY, "attributeValue");
        }

        @Override
        public boolean isStartRequired() {
            return true;
        }

        @Override
        public void onEnd(ReadableSpan readableSpan) {
        }

        @Override
        public boolean isEndRequired() {
            return false;
        }
    };

    sdkBuilder.addTracerProviderCustomizer(
        (sdkTracerProviderBuilder, configProperties) -> sdkTracerProviderBuilder
            .addSpanProcessor(spanProcessor));
}

More advanced examples with OpenTelemetry APIs:

• Advanced examples - 1
• Advanced examples - 2
• Event Hubs example

Key concepts

Some key concepts for the Azure Monitor exporter include:

• OpenTelemetry: OpenTelemetry is a set of libraries used to collect and export telemetry data (metrics, logs, and traces) for analysis in order to understand your software's performance and behavior.

• Instrumentation: The ability to call the OpenTelemetry API directly by any application is facilitated by instrumentation. A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.

• Trace: Trace refers to distributed tracing. It can be thought of as a directed acyclic graph (DAG) of Spans, where the edges between Spans are defined as parent/child relationship.

• Tracer Provider: Provides a Tracer for use by the given instrumentation library.

• Span Processor: A span processor allows hooks for SDK's Span start and end method invocations. Follow the link for more information.

• Sampling: Sampling is a mechanism to control the noise and overhead introduced by OpenTelemetry by reducing the number of samples of traces collected and sent to the backend.

For more information on the OpenTelemetry project, please review the OpenTelemetry Specifications.

Troubleshooting

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

Learn more about Open Telemetry

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.

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.