配置 Azure Monitor OpenTelemetry

本指南介绍如何使用 Azure Monitor OpenTelemetry 发行版在 Azure Monitor Application Insights 中配置 OpenTelemetry (OTel)。 正确配置可确保跨 .NET、Java、Node.js和 Python 应用程序收集一致的遥测数据收集,从而实现更可靠的监视和诊断。

连接字符串

Application Insights 中的连接字符串定义了用于发送遥测数据的目标位置。

使用以下两种方法来配置连接字符串:

  • 设置环境变量。

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
    
  • 使用配置对象。

    // Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
    const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
    
    // Create a new AzureMonitorOpenTelemetryOptions object.
    const options: AzureMonitorOpenTelemetryOptions = {
      azureMonitorExporterOptions: {
        connectionString: "<your connection string>"
      }
    };
    
    // Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
    useAzureMonitor(options);
    

设置云角色名称和云角色实例

对于支持的语言,Azure Monitor OpenTelemetry 发行版会自动检测资源上下文,并为组件的云角色名称和云角色实例属性提供默认值。 但是,可能需要将默认值替代为对团队有意义的值。 云角色名称值以节点下面的名称出现在应用程序映射上。

通过资源属性设置云角色名称和云角色实例。 云角色名称使用 service.namespaceservice.name 属性,但如果未设置 service.name,它将回滚到 service.namespace。 云角色实例使用 service.instance.id 属性值。 有关资源的标准属性的信息,请参阅 OpenTelemetry 语义约定

// Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, the Resource class, and the SemanticResourceAttributes class from the @azure/monitor-opentelemetry, @opentelemetry/resources, and @opentelemetry/semantic-conventions packages, respectively.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
const { Resource } = require("@opentelemetry/resources");
const { SemanticResourceAttributes } = require("@opentelemetry/semantic-conventions");

// Create a new Resource object with the following custom resource attributes:
//
// * service_name: my-service
// * service_namespace: my-namespace
// * service_instance_id: my-instance
const customResource = new Resource({
  [SemanticResourceAttributes.SERVICE_NAME]: "my-service",
  [SemanticResourceAttributes.SERVICE_NAMESPACE]: "my-namespace",
  [SemanticResourceAttributes.SERVICE_INSTANCE_ID]: "my-instance",
});

// Create a new AzureMonitorOpenTelemetryOptions object and set the resource property to the customResource object.
const options: AzureMonitorOpenTelemetryOptions = {
  resource: customResource
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

启用采样

可能需要启用采样以减少数据引入量,从而降低成本。 Azure Monitor 提供自定义固定速率采样器,该采样器使用采样率填充事件,Application Insights 会将其转换为 ItemCount固定速率采样器可确保准确的体验和事件计数。 采样器旨在跨服务保留跟踪,并可与较旧的 Application Insights 软件开发工具包 (SDK) 互操作。 有关详细信息,请参阅详细了解采样

注意

指标和日志不受采样影响。 如果在 Application Insights 中看到意外费用或高成本,本指南将有所帮助。 它涵盖了常见的原因,例如高遥测量、数据引入峰值和配置错误的采样。 如果您正在解决与成本峰值、遥测数据量、采样失效、数据上限、数据摄取量高或意外计费相关的问题,这将特别有用。 如需入门,请参阅 对 Application Insights 中数据引入量过高的问题进行故障排除

采样器需要 0 到 1 之间(含)的采样率。 0.1 意味着会发送大约 10% 的跟踪。

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object and set the samplingRatio property to 0.1.
const options: AzureMonitorOpenTelemetryOptions = {
  samplingRatio: 0.1
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

提示

如果使用固定比率/百分比采样,并且你不确定将采样率设置为何值,请先设置为 5%。 (0.05 采样率)根据故障和性能窗格中所示的操作的准确性调整比率。 通常情况下,采样率越高,准确度越高。 但是,任何采样都会影响准确度,因此我们建议对不受采样影响的 OpenTelemetry 指标发出警报。

实时指标

实时指标提供实时分析仪表板,用于深入了解应用程序活动和性能。

重要

有关 beta 版本、预览版或尚未正式发布的版本的 Azure 功能所适用的法律条款,请参阅 Microsoft Azure 预览版的补充使用条款

使用 enableLiveMetrics 属性配置发行版时,用户可以启用/禁用实时指标。

const options: AzureMonitorOpenTelemetryOptions = {
    azureMonitorExporterOptions: {
        connectionString:
            process.env["APPLICATIONINSIGHTS_CONNECTION_STRING"] || "<your connection string>",
    },
    enableLiveMetrics: false
};

useAzureMonitor(options);

脱机存储和自动重试

当应用程序与 Application Insights 断开连接并重试发送长达 48 小时时,基于 Azure Monitor OpenTelemetry 的产品/服务会缓存遥测数据。 有关数据处理建议,请参阅 导出和删除专用数据。 由于两个原因,高负载应用程序偶尔会删除遥测:超过允许的时间或超过最大文件大小。 如有必要,产品将最近事件优先于旧事件。

默认情况下,AzureMonitorExporter 将使用以下位置之一进行脱机存储。

  • Windows
    • %TEMP%\Microsoft\AzureMonitor
  • 非 Windows
    • %TMPDIR%/Microsoft/AzureMonitor
    • /var/tmp/Microsoft/AzureMonitor

若要替代默认目录,应设置 storageDirectory

例如:

// Import the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions class from the @azure/monitor-opentelemetry package.
const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");

// Create a new AzureMonitorOpenTelemetryOptions object and set the azureMonitorExporterOptions property to an object with the following properties:
//
// * connectionString: The connection string for your Azure Monitor Application Insights resource.
// * storageDirectory: The directory where the Azure Monitor OpenTelemetry exporter will store telemetry data when it is offline.
// * disableOfflineStorage: A boolean value that specifies whether to disable offline storage.
const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
    connectionString: "<Your Connection String>",
    storageDirectory: "C:\\SomeDirectory",
    disableOfflineStorage: false
  }
};

// Enable Azure Monitor integration using the useAzureMonitor function and the AzureMonitorOpenTelemetryOptions object.
useAzureMonitor(options);

若要禁用此功能,应设置 disableOfflineStorage = true

启用 OTLP 导出器

你可能想要启用 OpenTelemetry 协议 (OTLP) 导出器和 Azure Monitor 导出器,以将遥测数据发送到两个位置。

注意

为方便起见,只展示了 OTLP 导出器。 我们并未正式支持使用 OTLP 导出器或是其下游的任何组件或第三方体验。

  1. 在项目中安装 OpenTelemetry Collector Trace Exporter 和其他 OpenTelemetry 软件包。

        npm install @opentelemetry/api
        npm install @opentelemetry/exporter-trace-otlp-http
        npm install @opentelemetry/sdk-trace-base
        npm install @opentelemetry/sdk-trace-node
    
  2. 添加以下代码片段。 此示例假设你已经安装了一个 OpenTelemetry 收集器,并且其中正在运行一个 OTLP 接收器。 有关详细信息,请参阅 GitHub 上的示例

    // Import the useAzureMonitor function, the AzureMonitorOpenTelemetryOptions class, the trace module, the ProxyTracerProvider class, the BatchSpanProcessor class, the NodeTracerProvider class, and the OTLPTraceExporter class from the @azure/monitor-opentelemetry, @opentelemetry/api, @opentelemetry/sdk-trace-base, @opentelemetry/sdk-trace-node, and @opentelemetry/exporter-trace-otlp-http packages, respectively.
    const { useAzureMonitor, AzureMonitorOpenTelemetryOptions } = require("@azure/monitor-opentelemetry");
    const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
    const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
    
    // Create a new OTLPTraceExporter object.
    const otlpExporter = new OTLPTraceExporter();
    
    // Enable Azure Monitor integration.
    const options: AzureMonitorOpenTelemetryOptions = {
        // Add the SpanEnrichingProcessor
        spanProcessors: [new BatchSpanProcessor(otlpExporter)] 
    }
    useAzureMonitor(options);
    

OpenTelemetry 配置

使用 Azure Monitor OpenTelemetry 发行版时,可以通过环境变量访问以下 OpenTelemetry 配置。

有关 OpenTelemetry SDK 配置的详细信息,请参阅 OpenTelemetry 文档

编辑 URL 查询字符串

若要编辑 URL 查询字符串,请禁用查询字符串收集。 如果使用 SAS 令牌调用 Azure 存储,建议使用此设置。

使用 Azure Monitor OpenTelemetry 发行版包时,可以通过创建一个跨度处理器并将其应用于发行版配置来去除查询字符串。

import { useAzureMonitor, AzureMonitorOpenTelemetryOptions } from "@azure/monitor-opentelemetry";
import { Context } from "@opentelemetry/api";
import { ReadableSpan, Span, SpanProcessor } from "@opentelemetry/sdk-trace-base";
import { SEMATTRS_HTTP_ROUTE, SEMATTRS_HTTP_TARGET, SEMATTRS_HTTP_URL } from "@opentelemetry/semantic-conventions";

class RedactQueryStringProcessor implements SpanProcessor {
  forceFlush(): Promise<void> {
	return Promise.resolve();
  }
  onStart(span: Span, parentContext: Context): void {
    return;
  }
  shutdown(): Promise<void> {
	return Promise.resolve();
  }
  onEnd(span: ReadableSpan) {
    const httpRouteIndex: number = String(span.attributes[SEMATTRS_HTTP_ROUTE]).indexOf('?');
    const httpUrlIndex: number = String(span.attributes[SEMATTRS_HTTP_URL]).indexOf('?');
    const httpTargetIndex: number = String(span.attributes[SEMATTRS_HTTP_TARGET]).indexOf('?');
    if (httpRouteIndex !== -1) {
      span.attributes[SEMATTRS_HTTP_ROUTE] = String(span.attributes[SEMATTRS_HTTP_ROUTE]).substring(0, httpRouteIndex);
    }
    if (httpUrlIndex !== -1) {
      span.attributes[SEMATTRS_HTTP_URL] = String(span.attributes[SEMATTRS_HTTP_URL]).substring(0, httpUrlIndex);
    }
    if (httpTargetIndex !== -1) {
      span.attributes[SEMATTRS_HTTP_TARGET] = String(span.attributes[SEMATTRS_HTTP_TARGET]).substring(0, httpTargetIndex);
    }
  }
}

const options: AzureMonitorOpenTelemetryOptions = {
  azureMonitorExporterOptions: {
      connectionString: <YOUR_CONNECTION_STRING>,
  },
  spanProcessors: [new RedactQueryStringProcessor()]
};

useAzureMonitor(options);