配置 Azure Monitor OpenTelemetry

本文介绍 Azure Monitor OpenTelemetry 发行版的配置设置。

连接字符串

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

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

  • 设置环境变量。

    APPLICATIONINSIGHTS_CONNECTION_STRING=<Your Connection String>
    
  • 使用 configure_azure_monitor 函数。

# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor

# Configure OpenTelemetry to use Azure Monitor with the specified connection string.
# Replace `<your-connection-string>` with the connection string of your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="<your-connection-string>",
)

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

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

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

使用 OTEL_RESOURCE_ATTRIBUTES 和/或 OTEL_SERVICE_NAME 环境变量设置资源特性。 OTEL_RESOURCE_ATTRIBUTES 接收一系列以逗号分隔的键值对。 例如,若要将云角色名称设置为 my-namespace.my-helloworld-service ,并将云角色实例设置为 my-instance,可按如下所示设置 OTEL_RESOURCE_ATTRIBUTESOTEL_SERVICE_NAME

export OTEL_RESOURCE_ATTRIBUTES="service.namespace=my-namespace,service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

如果未设置 service.namespace 资源属性,也可仅使用 OTEL_SERVICE_NAME 环境变量或 service.name 资源属性来设置云角色名称。 例如,若要将云角色名称设置为 my-helloworld-service ,并将云角色实例设置为 my-instance,可按如下所示设置 OTEL_RESOURCE_ATTRIBUTESOTEL_SERVICE_NAME

export OTEL_RESOURCE_ATTRIBUTES="service.instance.id=my-instance"
export OTEL_SERVICE_NAME="my-helloworld-service"

启用采样

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

备注

指标和日志不受采样影响。

configure_azure_monitor() 函数会自动利用 ApplicationInsightsSampler 与 Application Insights SDK 的兼容,并对遥测数据进行采样。 OTEL_TRACES_SAMPLER_ARG 环境变量可用于指定采样率,有效范围为 0 到 1,其中 0 代表 0%,1 代表 100%。 例如,值 0.1 表示会发送 10% 的跟踪。

export OTEL_TRACES_SAMPLER_ARG=0.1

提示

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

实时指标

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

重要

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

可以使用适用于 Python 的 Azure Monitor OpenTelemetry 发行版启用实时指标,如下所示:

...
configure_azure_monitor(
	enable_live_metrics=True
)
...

启用 Microsoft Entra ID(前 Azure AD)身份验证

你可能需要启用 Microsoft Entra 身份验证,以便更安全地连接到 Azure,从而防止未经授权的遥测数据引入你的订阅。

用于 Python 的 Azure Monitor OpenTelemetry 发行版支持 Azure 标识提供的凭据类。

  • 建议使用 DefaultAzureCredential 进行本地开发。
  • 建议使用 ManagedIdentityCredential 处理系统分配和用户分配的托管标识。
    • 对于系统分配的托管标识,使用不带参数的默认构造函数。
    • 对于用户分配的托管标识,向构造函数提供 client_id
  • 建议使用 ClientSecretCredential 处理服务主体。
    • 向构造函数提供租户 ID、客户端 ID 和客户端密码。

如果使用 ManagedIdentityCredential

# Import the `ManagedIdentityCredential` class from the `azure.identity` package.
from azure.identity import ManagedIdentityCredential
# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

# Configure the Distro to authenticate with Azure Monitor using a managed identity credential.
credential = ManagedIdentityCredential(client_id="<client_id>")
configure_azure_monitor(
    connection_string="your-connection-string",
    credential=credential,
)

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("hello with aad managed identity"):
    print("Hello, World!")

如果使用 ClientSecretCredential

# Import the `ClientSecretCredential` class from the `azure.identity` package.
from azure.identity import ClientSecretCredential
# Import the `configure_azure_monitor()` function from the `azure.monitor.opentelemetry` package.
from azure.monitor.opentelemetry import configure_azure_monitor
from opentelemetry import trace

# Configure the Distro to authenticate with Azure Monitor using a client secret credential.
credential = ClientSecretCredential(
    tenant_id="<tenant_id",
    client_id="<client_id>",
    client_secret="<client_secret>",
)
configure_azure_monitor(
    connection_string="your-connection-string",
    credential=credential,
)

with tracer.start_as_current_span("hello with aad client secret identity"):
    print("Hello, World!")

脱机存储和自动重试

为了提高可靠性和复原能力,基于 OpenTelemetry 的 Azure Monitor 产品/服务默认在应用程序与 Application Insights 失去连接时写入脱机/本地存储。 这会将应用程序遥测数据保存到磁盘,并定期尝试再次发送遥测数据,最长持续时间为 48 小时。 在高负载应用程序中,遥测偶尔会出于两个原因而被删除。 首先,当允许的时间超过时;其次,当文件大小超过最大值或 SDK 没有机会清除文件时。 如果需要选择,产品会保存较新的事件,而不是较旧的事件。 了解详细信息

默认情况下,Azure Monitor 导出程序使用以下路径:

<tempfile.gettempdir()>/Microsoft/AzureMonitor/opentelemetry-python-<your-instrumentation-key>

若要替代默认目录,应将 storage_directory 设置为所需的目录。

例如:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and storage directory.
# Replace `your-connection-string` with the connection string to your Azure Monitor Application Insights resource.
# Replace `C:\\SomeDirectory` with the directory where you want to store the telemetry data before it is sent to Azure Monitor.
configure_azure_monitor(
    connection_string="your-connection-string",
    storage_directory="C:\\SomeDirectory",
)
...

若要禁用此功能,应将 disable_offline_storage 设置为 True。 默认为 False

例如:

...
# Configure OpenTelemetry to use Azure Monitor with the specified connection string and disable offline storage.
# Replace `your-connection-string` with the connection string to your Azure Monitor Application Insights resource.
configure_azure_monitor(
    connection_string="your-connection-string",
    disable_offline_storage=True,
)
...

启用 OTLP 导出器

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

备注

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

  1. 安装 opentelemetry-exporter-otlp 包。

  2. 添加以下代码片段。 此示例假设你已经安装了一个 OpenTelemetry 收集器,并且其中正在运行一个 OTLP 接收器。 有关详细信息,请参阅此自述文件

    # Import the `configure_azure_monitor()`, `trace`, `OTLPSpanExporter`, and `BatchSpanProcessor` classes from the appropriate packages.    
    from azure.monitor.opentelemetry import configure_azure_monitor
    from opentelemetry import trace
    from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
    from opentelemetry.sdk.trace.export import BatchSpanProcessor
    
    # Configure OpenTelemetry to use Azure Monitor with the specified connection string.
    # Replace `<your-connection-string>` with the connection string to your Azure Monitor Application Insights resource.
    configure_azure_monitor(
        connection_string="<your-connection-string>",
    )
    
    # Get the tracer for the current module.
    tracer = trace.get_tracer(__name__) 
    
    # Create an OTLP span exporter that sends spans to the specified endpoint.
    # Replace `http://localhost:4317` with the endpoint of your OTLP collector.
    otlp_exporter = OTLPSpanExporter(endpoint="http://localhost:4317")
    
    # Create a batch span processor that uses the OTLP span exporter.
    span_processor = BatchSpanProcessor(otlp_exporter)
    
    # Add the batch span processor to the tracer provider.
    trace.get_tracer_provider().add_span_processor(span_processor)
    
    # Start a new span with the name "test".
    with tracer.start_as_current_span("test"):
        print("Hello world!")
    

OpenTelemetry 配置

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

有关 OpenTelemetry SDK 配置的详细信息,请参阅 OpenTelemetry 文档Azure monitor 发行版使用情况

编辑 URL 查询字符串

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

我们正在 OpenTelemetry 社区中积极工作以支持编辑。