azure-monitor-opentelemetry-exporter-java

用途

Azure Monitor OpenTelemetry Exporter for Java 用于将 OpenTelemetry 的遥测数据（追踪、指标、日志）导出到 Azure Monitor / Application Insights。

⚠️ 弃用提示：该包已被弃用（deprecated），官方建议迁移到 azure-monitor-opentelemetry-autoconfigure，并提供了迁移指南。

主要能力

将 OpenTelemetry 遥测数据导出到 Azure Monitor / Application Insights。
通过连接字符串（Connection String）配置，连接字符串包含 InstrumentationKey 与 IngestionEndpoint。
支持创建 Span、为 Span 添加属性、嵌套 Span、记录异常并设置状态。
支持自定义 SpanProcessor，在 Span 生命周期中拦截并添加自定义属性。
支持通过 OpenTelemetry API 采集指标，包括 Counter 与 Histogram。

使用方式

依赖（已弃用）：

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

推荐改用 Autoconfigure：

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

环境变量：

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

使用 Autoconfigure 的基础初始化（推荐），可通过环境变量或显式连接字符串：

import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;
import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdkBuilder;
import io.opentelemetry.api.OpenTelemetry;
import com.azure.monitor.opentelemetry.exporter.AzureMonitorExporter;

// Connection string from APPLICATIONINSIGHTS_CONNECTION_STRING env var
AutoConfiguredOpenTelemetrySdkBuilder sdkBuilder = AutoConfiguredOpenTelemetrySdk.builder();
AzureMonitorExporter.customize(sdkBuilder);
OpenTelemetry openTelemetry = sdkBuilder.build().getOpenTelemetrySdk();

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

创建 Span、添加属性、嵌套 Span、记录异常、采集指标等示例代码详见原始资料，涵盖 Tracer、Span、Scope、AttributeKey、SpanProcessor、Meter、LongCounter、LongHistogram 等 API 用法。

关键概念

Connection String：Application Insights 连接字符串，包含 instrumentation key。
Tracer：为分布式追踪创建 Span。
Span：表示一个带时间与属性的工作单元。
SpanProcessor：拦截 Span 生命周期以进行自定义。
Exporter：将遥测数据发送到 Azure Monitor。

迁移到 Autoconfigure

azure-monitor-opentelemetry-autoconfigure 提供：常见库的自动埋点、简化配置、与 OpenTelemetry SDK 更好的集成。

迁移步骤：替换依赖（移除 azure-monitor-opentelemetry-exporter，添加 azure-monitor-opentelemetry-autoconfigure），并按迁移指南更新初始化代码。

最佳实践

使用 autoconfigure，迁移到 azure-monitor-opentelemetry-autoconfigure。
设置有意义的 Span 名称，使用描述性操作名。
添加相关属性，包含用于调试的上下文数据。
处理异常，始终在 Span 上记录异常。
使用语义约定，遵循 OpenTelemetry 语义约定。
在 finally 中结束 Span，确保 Span 始终被结束。
使用 try-with-resources 管理 Scope。

适用场景

适用于需要将 Java 应用的 OpenTelemetry 追踪、指标、日志导出到 Azure Monitor / Application Insights 的场景。

限制

该包已弃用，应迁移到 azure-monitor-opentelemetry-autoconfigure。
仅在任务明确匹配上述范围时使用。
不应将输出视为环境特定验证、测试或专家评审的替代。
若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。

参考链接

Maven Package: 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
Migration Guide: https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-opentelemetry-exporter/MIGRATION.md
Autoconfigure Package: 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