Azure Monitor OpenTelemetry 导出器 Java 版

azure-monitor-opentelemetry-exporter-java

分类通用

作者Agentic Awesome Skills 社区

许可MIT

评分4.90/5

使用16.2K

Azure Monitor OpenTelemetry Exporter for Java

> ⚠️ 弃用通知：此包已弃用。请迁移至 azure-monitor-opentelemetry-autoconfigure。
>
> 详细指令请参阅迁移指南。

将 OpenTelemetry 遥测数据导出到 Azure Monitor / Application Insights。

安装（已弃用）

xml

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-opentelemetry-exporter</artifactId>
    <version>1.0.0-beta.x</version>
</dependency>

推荐：改用 Autoconfigure

xml

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-opentelemetry-autoconfigure</artifactId>
    <version>LATEST</version>
</dependency>

环境变量

bash

APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=xxx;IngestionEndpoint=https://xxx.in.applicationinsights.azure.com/

使用 Autoconfigure 的基础设置（推荐）

使用环境变量

java

import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdkBuilder;
import io.opentelemetry.api.OpenTelemetry;
import com.azure.monitor.opentelemetry.exporter.AzureMonitorExporter;
// 连接字符串来自 APPLICATIONINSIGHTS_CONNECTION_STRING 环境变量
AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
AzureMonitorExporter.customize(sdkBuilder);
OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();

使用显式连接字符串

java

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

创建 Span

java

import io.opentelemetry.api.trace.Tracer;
import io.opentelemetry.api.trace.Span;
import io.opentelemetry.context.Scope;
// 获取 tracer
Tracer tracer = openTelemetry.getTracer("com.example.myapp");
// 创建 span
Span span = tracer.spanBuilder("myOperation").startSpan();
try (Scope scope = span.makeCurrent()) {
    // 应用程序逻辑
    doWork();
} catch (Throwable t) {
    span.recordException(t);
    throw t;
} finally {
    span.end();
}

添加 Span 属性

java

import io.opentelemetry.api.common.AttributeKey;
import io.opentelemetry.api.common.Attributes;
Span span = tracer.spanBuilder("processOrder")
    .setAttribute("order.id", "12345")
    .setAttribute("customer.tier", "premium")
    .startSpan();
try (Scope scope = span.makeCurrent()) {
    // 在执行过程中添加属性
    span.setAttribute("items.count", 3);
    span.setAttribute("total.amount", 99.99);
    
    processOrder();
} finally {
    span.end();
}

自定义 Span 处理器

java

import io.opentelemetry.sdk.trace.SpanProcessor;
import io.opentelemetry.sdk.trace.ReadWriteSpan;
import io.opentelemetry.sdk.trace.ReadableSpan;
import io.opentelemetry.context.Context;
private static final AttributeKey<String> CUSTOM_ATTR = AttributeKey.stringKey("custom.attribute");

java

SpanProcessor customProcessor = new SpanProcessor() {
    @Override
    public void onStart(Context context, ReadWriteSpan span) {
        // 为每个 span 添加自定义属性
        span.setAttribute(CUSTOM_ATTR, "customValue");
    }
@Override
    public boolean isStartRequired() {
        return true;
    }
@Override
    public void onEnd(ReadableSpan span) {
        // 如有需要，在此进行后处理
    }
@Override
    public boolean isEndRequired() {
        return false;
    }
};
// 注册处理器
AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
AzureMonitorExporter.customize(sdkBuilder);
sdkBuilder.addTracerProviderCustomizer(
    (sdkTracerProviderBuilder, configProperties) -> 
        sdkTracerProviderBuilder.addSpanProcessor(customProcessor)
);
OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();

嵌套 Span

java

public void parentOperation() {
    Span parentSpan = tracer.spanBuilder("parentOperation").startSpan();
    try (Scope scope = parentSpan.makeCurrent()) {
        childOperation();
    } finally {
        parentSpan.end();
    }
}
public void childOperation() {
    // 通过 Context 自动链接到父级
    Span childSpan = tracer.spanBuilder("childOperation").startSpan();
    try (Scope scope = childSpan.makeCurrent()) {
        // 子操作工作内容
    } finally {
        childSpan.end();
    }
}

记录异常

java

Span span = tracer.spanBuilder("riskyOperation").startSpan();
try (Scope scope = span.makeCurrent()) {
    performRiskyWork();
} catch (Exception e) {
    span.recordException(e);
    span.setStatus(StatusCode.ERROR, e.getMessage());
    throw e;
} finally {
    span.end();
}

指标 (通过 OpenTelemetry)

java

import io.opentelemetry.api.metrics.Meter;
import io.opentelemetry.api.metrics.LongCounter;
import io.opentelemetry.api.metrics.LongHistogram;
Meter meter = openTelemetry.getMeter("com.example.myapp");
// 计数器 (Counter)
LongCounter requestCounter = meter.counterBuilder("http.requests")
    .setDescription("Total HTTP requests")
    .setUnit("requests")
    .build();
requestCounter.add(1, Attributes.of(
    AttributeKey.stringKey("http.method"), "GET",
    AttributeKey.longKey("http.status_code"), 200L
));
// 直方图 (Histogram)
LongHistogram latencyHistogram = meter.histogramBuilder("http.latency")
    .setDescription("Request latency")
    .setUnit("ms")
    .ofLongs()
    .build();
latencyHistogram.record(150, Attributes.of(
    AttributeKey.stringKey("http.route"), "/api/users"
));

核心概念

| 概念 | 描述 |
|---------|-------------|
| 连接字符串 (Connection String) | 包含检测密钥的 Application Insights 连接字符串 |
| 追踪器 (Tracer) | 用于创建分布式追踪的 span |
| Span | 表示一个带有时间戳和属性的工作单元 |
| SpanProcessor | 拦截 span 生命周期以进行自定义处理 |
| 导出器 (Exporter) | 将遥测数据发送至 Azure Monitor |

迁移至 Autoconfigure

azure-monitor-opentelemetry-autoconfigure 包提供：

常用库的自动检测 (Automatic instrumentation)

简化配置

与 OpenTelemetry SDK 更好的集成

迁移步骤

1. 替换依赖：

xml

<!-- 移除 -->
   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-monitor-opentelemetry-exporter</artifactId>
   </dependency>
   
   <!-- 添加 -->
   <dependency>
       <groupId>com.azure</groupId>
       <artifactId>azure-moni

tor-opentelemetry-autoconfigure</artifactId>
</dependency>
``


2. 根据 迁移指南 更新初始化代码
最佳实践

1. 使用自动配置 — 迁移至 azure-monitor-opentelemetry-autoconfigure`
2. 设置有意义的 Span 名称 — 使用具有描述性的操作名称
3. 添加相关属性 — 包含用于调试的上下文数据
4. 处理异常 — 始终在 Span 中记录异常
5. 使用语义约定 — 遵循 OpenTelemetry 语义约定
6. 在 finally 块中结束 Span — 确保 Span 始终被关闭
7. 使用 try-with-resources — 通过 try-with-resources 模式进行作用域管理

参考链接

| 资源 | URL |
|----------|-----|
| Maven 包 | https://central.sonatype.com/artifact/com.azure/azure-monitor-opentelemetry-exporter |
| GitHub | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/monitor/azure-monitor-opentelemetry-exporter |
| 迁移指南 | https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-opentelemetry-exporter/MIGRATION.md |
| 自动配置包 | https://central.sonatype.com/artifact/com.azure/azure-monitor-opentelemetry-autoconfigure |
| OpenTelemetry Java | https://opentelemetry.io/docs/languages/java/ |
| Application Insights | https://learn.microsoft.com/azure/azure-monitor/app/app-insights-overview |

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

仅在任务与上述范围明确匹配时使用此技能。

不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。

如果缺少必要的输入、权限、安全边界或成功标准，请停止操作并寻求澄清。

Azure Monitor OpenTelemetry 导出器 Java 版

Azure Monitor OpenTelemetry Exporter for Java

安装（已弃用）

推荐：改用 Autoconfigure

环境变量

使用 Autoconfigure 的基础设置（推荐）

使用环境变量

使用显式连接字符串

创建 Span

添加 Span 属性

自定义 Span 处理器

嵌套 Span

记录异常

指标 (通过 OpenTelemetry)

核心概念

迁移至 Autoconfigure

迁移步骤

最佳实践

参考链接

适用场景

局限性

扫码进交流群