Azure Monitor Opentelemetry Exporter Java

1---
2name: azure-monitor-opentelemetry-exporter-java
3description: |
4  Azure Monitor OpenTelemetry Exporter for Java. Export OpenTelemetry traces, metrics, and logs to Azure Monitor/Application Insights.
5  Triggers: "AzureMonitorExporter java", "opentelemetry azure java", "application insights java otel", "azure monitor tracing java".
6  Note: This package is DEPRECATED. Migrate to azure-monitor-opentelemetry-autoconfigure.
7package: com.azure:azure-monitor-opentelemetry-exporter
8---
9 
10# Azure Monitor OpenTelemetry Exporter for Java
11 
12> **⚠️ DEPRECATION NOTICE**: This package is deprecated. Migrate to `azure-monitor-opentelemetry-autoconfigure`.
13>
14> See [Migration Guide](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-opentelemetry-exporter/MIGRATION.md) for detailed instructions.
15 
16Export OpenTelemetry telemetry data to Azure Monitor / Application Insights.
17 
18## Installation (Deprecated)
19 
20```xml
21<dependency>
22    <groupId>com.azure</groupId>
23    <artifactId>azure-monitor-opentelemetry-exporter</artifactId>
24    <version>1.0.0-beta.x</version>
25</dependency>
26```
27 
28## Recommended: Use Autoconfigure Instead
29 
30```xml
31<dependency>
32    <groupId>com.azure</groupId>
33    <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
34    <version>LATEST</version>
35</dependency>
36```
37 
38## Environment Variables
39 
40```bash
41APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.com/
42```
43 
44## Basic Setup with Autoconfigure (Recommended)
45 
46### Using Environment Variable
47 
48```java
49import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
50import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdkBuilder;
51import io.opentelemetry.api.OpenTelemetry;
52import com.azure.monitor.opentelemetry.exporter.AzureMonitorExporter;
53 
54// Connection string from APPLICATIONINSIGHTS_CONNECTION_STRING env var
55AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
56AzureMonitorExporter.customize(sdkBuilder);
57OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();
58```
59 
60### With Explicit Connection String
61 
62```java
63AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
64AzureMonitorExporter.customize(sdkBuilder, "{connection-string}");
65OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();
66```
67 
68## Creating Spans
69 
70```java
71import io.opentelemetry.api.trace.Tracer;
72import io.opentelemetry.api.trace.Span;
73import io.opentelemetry.context.Scope;
74 
75// Get tracer
76Tracer tracer = openTelemetry.getTracer("com.example.myapp");
77 
78// Create span
79Span span = tracer.spanBuilder("myOperation").startSpan();
80 
81try (Scope scope = span.makeCurrent()) {
82    // Your application logic
83    doWork();
84} catch (Throwable t) {
85    span.recordException(t);
86    throw t;
87} finally {
88    span.end();
89}
90```
91 
92## Adding Span Attributes
93 
94```java
95import io.opentelemetry.api.common.AttributeKey;
96import io.opentelemetry.api.common.Attributes;
97 
98Span span = tracer.spanBuilder("processOrder")
99    .setAttribute("order.id", "12345")
100    .setAttribute("customer.tier", "premium")
101    .startSpan();
102 
103try (Scope scope = span.makeCurrent()) {
104    // Add attributes during execution
105    span.setAttribute("items.count", 3);
106    span.setAttribute("total.amount", 99.99);
107    
108    processOrder();
109} finally {
110    span.end();
111}
112```
113 
114## Custom Span Processor
115 
116```java
117import io.opentelemetry.sdk.trace.SpanProcessor;
118import io.opentelemetry.sdk.trace.ReadWriteSpan;
119import io.opentelemetry.sdk.trace.ReadableSpan;
120import io.opentelemetry.context.Context;
121 
122private static final AttributeKey<String> CUSTOM_ATTR = AttributeKey.stringKey("custom.attribute");
123 
124SpanProcessor customProcessor = new SpanProcessor() {
125    @Override
126    public void onStart(Context context, ReadWriteSpan span) {
127        // Add custom attribute to every span
128        span.setAttribute(CUSTOM_ATTR, "customValue");
129    }
130 
131    @Override
132    public boolean isStartRequired() {
133        return true;
134    }
135 
136    @Override
137    public void onEnd(ReadableSpan span) {
138        // Post-processing if needed
139    }
140 
141    @Override
142    public boolean isEndRequired() {
143        return false;
144    }
145};
146 
147// Register processor
148AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
149AzureMonitorExporter.customize(sdkBuilder);
150 
151sdkBuilder.addTracerProviderCustomizer(
152    (sdkTracerProviderBuilder, configProperties) -> 
153        sdkTracerProviderBuilder.addSpanProcessor(customProcessor)
154);
155 
156OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();
157```
158 
159## Nested Spans
160 
161```java
162public void parentOperation() {
163    Span parentSpan = tracer.spanBuilder("parentOperation").startSpan();
164    try (Scope scope = parentSpan.makeCurrent()) {
165        childOperation();
166    } finally {
167        parentSpan.end();
168    }
169}
170 
171public void childOperation() {
172    // Automatically links to parent via Context
173    Span childSpan = tracer.spanBuilder("childOperation").startSpan();
174    try (Scope scope = childSpan.makeCurrent()) {
175        // Child work
176    } finally {
177        childSpan.end();
178    }
179}
180```
181 
182## Recording Exceptions
183 
184```java
185Span span = tracer.spanBuilder("riskyOperation").startSpan();
186try (Scope scope = span.makeCurrent()) {
187    performRiskyWork();
188} catch (Exception e) {
189    span.recordException(e);
190    span.setStatus(StatusCode.ERROR, e.getMessage());
191    throw e;
192} finally {
193    span.end();
194}
195```
196 
197## Metrics (via OpenTelemetry)
198 
199```java
200import io.opentelemetry.api.metrics.Meter;
201import io.opentelemetry.api.metrics.LongCounter;
202import io.opentelemetry.api.metrics.LongHistogram;
203 
204Meter meter = openTelemetry.getMeter("com.example.myapp");
205 
206// Counter
207LongCounter requestCounter = meter.counterBuilder("http.requests")
208    .setDescription("Total HTTP requests")
209    .setUnit("requests")
210    .build();
211 
212requestCounter.add(1, Attributes.of(
213    AttributeKey.stringKey("http.method"), "GET",
214    AttributeKey.longKey("http.status_code"), 200L
215));
216 
217// Histogram
218LongHistogram latencyHistogram = meter.histogramBuilder("http.latency")
219    .setDescription("Request latency")
220    .setUnit("ms")
221    .ofLongs()
222    .build();
223 
224latencyHistogram.record(150, Attributes.of(
225    AttributeKey.stringKey("http.route"), "/api/users"
226));
227```
228 
229## Key Concepts
230 
231| Concept | Description |
232|---------|-------------|
233| Connection String | Application Insights connection string with instrumentation key |
234| Tracer | Creates spans for distributed tracing |
235| Span | Represents a unit of work with timing and attributes |
236| SpanProcessor | Intercepts span lifecycle for customization |
237| Exporter | Sends telemetry to Azure Monitor |
238 
239## Migration to Autoconfigure
240 
241The `azure-monitor-opentelemetry-autoconfigure` package provides:
242- Automatic instrumentation of common libraries
243- Simplified configuration
244- Better integration with OpenTelemetry SDK
245 
246### Migration Steps
247 
2481. Replace dependency:
249   ```xml
250   <!-- Remove -->
251   <dependency>
252       <groupId>com.azure</groupId>
253       <artifactId>azure-monitor-opentelemetry-exporter</artifactId>
254   </dependency>
255   
256   <!-- Add -->
257   <dependency>
258       <groupId>com.azure</groupId>
259       <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
260   </dependency>
261   ```
262 
2632. Update initialization code per [Migration Guide](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-opentelemetry-exporter/MIGRATION.md)
264 
265## Best Practices
266 
2671. **Use autoconfigure** — Migrate to `azure-monitor-opentelemetry-autoconfigure`
2682. **Set meaningful span names** — Use descriptive operation names
2693. **Add relevant attributes** — Include contextual data for debugging
2704. **Handle exceptions** — Always record exceptions on spans
2715. **Use semantic conventions** — Follow OpenTelemetry semantic conventions
2726. **End spans in finally** — Ensure spans are always ended
2737. **Use try-with-resources** — Scope management with try-with-resources pattern
274 
275## Reference Links
276 
277| Resource | URL |
278|----------|-----|
279| Maven Package | https://central.sonatype.com/artifact/com.azure/azure-monitor-opentelemetry-exporter |
280| GitHub | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/monitor/azure-monitor-opentelemetry-exporter |
281| Migration Guide | https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-opentelemetry-exporter/MIGRATION.md |
282| Autoconfigure Package | https://central.sonatype.com/artifact/com.azure/azure-monitor-opentelemetry-autoconfigure |
283| OpenTelemetry Java | https://opentelemetry.io/docs/languages/java/ |
284| Application Insights | https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview |
285