为 .NET、Java、Node.js 和 Python 应用程序添加和修改 Azure Monitor OpenTelemetry

本指南提供有关在 Azure Monitor Application Insights 中集成和自定义 OpenTelemetry (OTel) 仪表的说明。

若要详细了解 OpenTelemetry 概念,请参阅 OpenTelemetry 概述OpenTelemetry 常见问题解答

备注

有关 Azure Function Apps,请参阅 将 OpenTelemetry 与 Azure Functions 配合使用

自动数据收集

发行版通过捆绑 OpenTelemetry 检测库来自动收集数据。

包含的检测库

Spring Boot 原生应用程序的请求

  • Spring Web
  • Spring Web MVC(模型-View-Controller)
  • Spring WebFlux

Spring Boot 原生应用程序的依赖项

指标

  • Micrometer 指标

Spring Boot 原生应用程序的日志

  • Logback

若要减少或增加 Azure Monitor 收集的日志数,请先在应用程序的日志记录库中设置所需的日志记录级别(例如 WARNINGERROR)。

有关 Quartz 原生应用程序,请参阅 Quarkus 文档

脚注

  • ¹:支持未经处理的/未捕获的异常的自动报告
  • ²:支持 OpenTelemetry 指标

备注

Azure Monitor OpenTelemetry 发行版包括自定义映射和逻辑,用于自动发出 Application Insights 标准指标

提示

所有 OpenTelemetry 指标,无论是从检测库自动收集的还是从自动编码中收集收集的,现在都被认为是用于计费目的的 Application Insights“自定义指标”。 了解详细信息

添加社区检测库

从 OpenTelemetry 社区包含检测库时,可以自动收集更多数据。

注意

我们不支持也不保证社区检测库的质量。 要为我们的分发版推荐一个检测库,请在反馈社区中发帖或投票。 请注意,某些检测库基于实验性 OpenTelemetry 规范,可能会在将来引入中断性变更。

不能将社区检测库与 GraalVM Java 原生应用程序一起使用。

收集自定义遥测数据

本部分介绍如何从应用程序收集自定义遥测数据。

根据语言和信号类型,可以通过不同的方式收集自定义遥测数据,包括:

  • 开放遥测 API
  • 特定于语言的日志记录/指标库
  • Application Insights 经典 API

下表显示了目前支持的自定义遥测类型:

语言 自定义事件 自定义指标 依赖项 异常 页面视图 请求 跟踪
ASP.NET Core
   开放遥测 API
    ILogger 应用程序接口
   AI 经典 API
爪哇岛
   开放遥测 API
   Logback,Log4j,JUL
   Micrometer 指标
   AI 经典 API
Node.js
   开放遥测 API
Python
   开放遥测 API
   Python 日志记录模块
   事件扩展

备注

Application Insights Java 3.x 和 Application Insights Node.js 3.x 从 Application Insights 经典 API 收集遥测数据。 此行为简化了升级,并暂时支持自定义遥测,直到 OpenTelemetry API 包含所有自定义遥测类型。

添加自定义指标

在此上下文中,自定义指标术语是指手动检测代码以收集超出 OpenTelemetry Instrumentation 库自动收集的额外指标。

OpenTelemetry API 提供六种指标“检测”来涵盖各种指标方案,在指标资源管理器中可视化指标时,需要选取正确的“聚合类型”。 使用 OpenTelemetry 指标 API 发送指标和使用检测库时,此要求是正确的。

下表显示了每个 OpenTelemetry 指标检测的建议聚合类型

OpenTelemetry 检测 Azure Monitor 聚合类型
计数器 总和
异步计数器 总和
直方图 Min、Max、Average、Sum 和 Count
异步仪表 平均值
UpDownCounter 总和
异步 UpDownCounter 总和

注意

在大多数情况下,其他聚合类型没有意义。

OpenTelemetry 规范介绍了这些检测,并提供了何时可以使用每种检测的示例。

提示

直方图是最通用的,也与 Application Insights GetMetric Classic API 最接近。 Azure Monitor 目前将直方图检测合并到五种受支持的聚合类型中,并且正在研发对百分位数的支持。 虽然通用性较低,但其他 OpenTelemetry 仪器对应用程序性能的影响较小。

直方图示例

  1. 注入 OpenTelemetry

    • 春天

      import io.opentelemetry.api.OpenTelemetry;
      
      @Autowired
      OpenTelemetry openTelemetry;
      
    • Quarkus

      import io.opentelemetry.api.OpenTelemetry; 
      
      @Inject
      OpenTelemetry openTelemetry;
      
  2. 创建直方图:

    import io.opentelemetry.api.metrics.DoubleHistogram;
    import io.opentelemetry.api.metrics.Meter;
    
    Meter meter = openTelemetry.getMeter("OTEL.AzureMonitor.Demo");
    DoubleHistogram histogram = meter.histogramBuilder("histogram").build();
    histogram.record(1.0);
    histogram.record(100.0);
    histogram.record(30.0);
    

计数器示例

  1. 注入 OpenTelemetry

    • 春天

      import io.opentelemetry.api.OpenTelemetry;
      
      @Autowired
      OpenTelemetry openTelemetry;
      
    • Quarkus

      import io.opentelemetry.api.OpenTelemetry; 
      
      @Inject
      OpenTelemetry openTelemetry;
      
  2. 创建计数器:

    import io.opentelemetry.api.common.AttributeKey;
    import io.opentelemetry.api.common.Attributes;
    import io.opentelemetry.api.metrics.LongCounter;
    import io.opentelemetry.api.metrics.Meter;
    
    
    Meter meter = openTelemetry.getMeter("OTEL.AzureMonitor.Demo");
    
    LongCounter myFruitCounter = meter.counterBuilder("MyFruitCounter")
                                      .build();
    
    myFruitCounter.add(1, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "red"));
    myFruitCounter.add(2, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));
    myFruitCounter.add(1, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));
    myFruitCounter.add(2, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "green"));
    myFruitCounter.add(5, Attributes.of(AttributeKey.stringKey("name"), "apple", AttributeKey.stringKey("color"), "red"));
    myFruitCounter.add(4, Attributes.of(AttributeKey.stringKey("name"), "lemon", AttributeKey.stringKey("color"), "yellow"));
    

仪表示例

  1. 注入 OpenTelemetry

    • 春天

      import io.opentelemetry.api.OpenTelemetry;
      
      @Autowired
      OpenTelemetry openTelemetry;
      
    • Quarkus

      import io.opentelemetry.api.OpenTelemetry; 
      
      @Inject
      OpenTelemetry openTelemetry;
      
  2. 创建仪表:

    import io.opentelemetry.api.common.AttributeKey;
    import io.opentelemetry.api.common.Attributes;
    import io.opentelemetry.api.metrics.Meter;
    
    Meter meter = openTelemetry.getMeter("OTEL.AzureMonitor.Demo");
    
    meter.gaugeBuilder("gauge")
         .buildWithCallback(
                observableMeasurement -> {
                    double randomNumber = Math.floor(Math.random() * 100);
                    observableMeasurement.record(randomNumber, Attributes.of(AttributeKey.stringKey("testKey"), "testValue"));
                });
    

添加自定义异常

选择检测库会自动报告 Application Insights 的异常。 但是,你可能想要手动报告检测库报告的异常之外的异常。 例如,通常不会报告代码捕获的异常。 你可能希望报告这些异常,以便在相关体验中引起注意,包括故障部分和端到端事务视图。

将状态设置为 error,并记录代码中的异常:

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.trace.StatusCode;

Span span = Span.current();
span.setStatus(StatusCode.ERROR, "errorMessage");
span.recordException(e);

添加自定义范围

你可能想要在两种情况下添加自定义跨度。 首先,当存在检测库尚未收集的依赖项请求时。 其次,当你希望在端到端事务视图上将应用程序进程建模为跨度时。

  1. 注入 OpenTelemetry

    • 春天

      import io.opentelemetry.api.OpenTelemetry;
      
      @Autowired
      OpenTelemetry openTelemetry;
      
    • Quarkus

      import io.opentelemetry.api.OpenTelemetry;
      
      @Inject
      OpenTelemetry openTelemetry;
      
  2. 创建 Tracer

    import io.opentelemetry.api.trace.Tracer;
    
    static final Tracer tracer = openTelemetry.getTracer("com.example");
    
  3. 创建一个范围,使其成为当前范围,然后结束该范围:

    Span span = tracer.spanBuilder("my first span").startSpan();
    try (Scope ignored = span.makeCurrent()) {
        // do stuff within the context of this 
    } catch (Throwable t) {
        span.recordException(t);
    } finally {
        span.end();
    }
    

发送自定义事件

Application Insights 将自定义事件 customEvents 存储在表中。 分析、筛选和可视化它们的一种方法是使用 Application Insights 使用情况体验

如果要自动收集客户端交互事件,可以在 JavaScript SDK 中使用插件

无法在 Java 原生环境中使用 customEvent 属性发送 "microsoft.custom_event.name"

修改遥测

本部分介绍如何修改遥测。

添加范围属性

这些属性可能包括向遥测添加自定义属性。 还可以使用属性来设置 Application Insights 架构中的可选字段,如客户端 IP。

将自定义属性添加到范围

你添加到范围的任何属性都将导出为自定义属性。 它们将填充请求、依赖项、跟踪或异常表中的 customDimensions 字段。

在代码中添加自定义维度:

import io.opentelemetry.api.trace.Span;
import io.opentelemetry.api.common.AttributeKey;

AttributeKey attributeKey = AttributeKey.stringKey("mycustomdimension");
Span.current().setAttribute(attributeKey, "myvalue1");

设置用户 IP

可以通过设置范围的属性来填充请求的 client_IP 字段。 Application Insights 使用 IP 地址生成用户位置属性,然后默认放弃它

该字段会自动进行填充。

设置用户 ID 或经过身份验证的用户 ID

可以使用以下指导填充请求的 user_Iduser_AuthenticatedId 字段。 用户 ID 是匿名用户标识符。 经过身份验证的用户 ID 是已知的用户标识符。

重要

在设置经过身份验证的用户 ID 之前,请参考适用的隐私法律。

填充 user IDrequestsdependencies 表中的 exceptions 字段。

在代码中设置 user_Id

import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("enduser.id", "myuser");

添加日志属性

对于 Spring Boot 原生应用程序,Logback 是开箱即用的。

获取跟踪 ID 或范围 ID

可以使用以下步骤获取当前处于活动状态的范围的 Trace IDSpan ID

在代码中获取请求跟踪 ID 和范围 ID:

import io.opentelemetry.api.trace.Span;

Span span = Span.current();
String traceId = span.getSpanContext().getTraceId();
String spanId = span.getSpanContext().getSpanId();

后续步骤