在 Azure 容器应用 中收集和读取 OpenTelemetry 数据

在Azure 容器应用环境中使用 OpenTelemetry 数据代理,可以选择通过以下方式以 OpenTelemetry 格式发送可观测性数据:

  • 将来自代理的数据输送到所需的终结点。 目标选项包括Azure Monitor Application Insights、Datadog 和任何与 OpenTelemetry 协议(OTLP)兼容的终结点。

  • 轻松更改目标终结点,而无需重新配置其发出数据的方式,也无需手动运行 OpenTelemetry 代理。

本文介绍如何为容器应用设置和配置 OpenTelemetry 代理。

配置 OpenTelemetry 代理

OpenTelemetry 代理位于容器应用环境中。 可以通过 ARM 模板或 Bicep 调用到环境,或者通过 CLI 或 Terraform(使用 AzAPI 提供程序)配置代理设置。

每个终结点类型(Azure Monitor Application Insights、Datadog 和 OTLP)都有特定的配置要求。

先决条件

为环境启用托管 OpenTelemetry 代理并不意味着代理会自动收集数据。 代理仅根据您的配置设置和正确进行代码仪器化来发送数据。

配置源代码

安装 OpenTelemetry SDK,准备应用程序以收集数据,并遵循 OpenTelemetry 指南来检测指标日志跟踪

初始化终结点

在将数据发送到集合目标之前,首先需要创建目标服务的实例。 例如,如果要将数据发送到 Azure Monitor Application Insights,则需要提前创建 Application Insights 实例。

OpenTelemetry 托管代理接受以下目标:

  • Azure Monitor 应用程序洞察
  • 数据狗
  • 任何 OTLP 终结点(例如:New Relic 或 Honeycomb)

注意

Microsoft为发送到Azure Monitor Application Insights的数据提供支持。 将数据存储在任何非Microsoft系统中后,与数据相关的支持由终结点的组织负责。

下表显示了可以发送到每个目标的数据类型:

目标 日志 指标 跟踪
Azure 应用 Insights
Datadog
与 OpenTelemetry 协议(OTLP)兼容的端点

导出目标指南

使用以下指南获取特定于目标的设置和验证详细信息。

目标 指南
数据狗 在 Azure 容器应用 中将 OpenTelemetry 数据导出到 Datadog
其他与 OTLP 兼容的端点 OTLP 终结点

Azure Monitor 应用程序洞察

Application Insights 所需的唯一配置详细信息是连接字符串。 一旦获取到连接字符串,可以通过容器应用的 ARM 模板使用 Azure CLI 命令或 Terraform 来配置代理。

连接字符串中包含一个检测密钥,这是一个用于将遥测数据关联到特定 Application Insights 资源的唯一标识符。 检测密钥不是安全令牌或安全密钥,也不被视为机密。

在部署此模板之前,请将 <PLACEHOLDERS> 替换为你的值。

{
  ...
  "properties": {
    "appInsightsConfiguration ": {
      "connectionString": "<APP_INSIGHTS_CONNECTION_STRING>"
    }
    "openTelemetryConfiguration": {
      ...
      "tracesConfiguration":{
        "destinations": ["appInsights"]
      },
      "logsConfiguration": {
        "destinations": ["appInsights"]
      }
    }
  }
}

数据狗

如果为环境启用托管 OpenTelemetry 代理,则无需在容器应用中运行 Datadog 代理。

有关详细演练,请参阅将遥测数据从Azure 容器应用托管的 OpenTelemetry 代理导出到 Datadog

OpenTelemetry 代理配置需要从您的 Datadog 实例中获取 sitekey 的值。 根据下表从 Datadog 实例收集这些值:

Datadog 实例属性 OpenTelemetry 代理配置属性
DD_SITE site
DD_API_KEY key

获得这些配置详细信息后,可以通过容器应用的 ARM 或Bicep模板或使用Azure CLI命令配置代理。

请不要直接在生产环境中指定机密值,例如 Datadog API 密钥。 请改用对存储在Azure 密钥保管库中的机密的引用。

必须为模板部署启用密钥保管库。 若要启用模板部署,请创建启用了 enabledForTemplateDeployment 属性的密钥保管库,或运行以下 Azure CLI 命令,将 <KEY_VAULT_NAME> 替换为你的值:

az keyvault update --name <KEY_VAULT_NAME> --enabled-for-template-deployment true

有关详细信息,请参阅:

创建 parameter 文件以从Azure 密钥保管库检索 Datadog API 密钥。

在部署以下文件之前,请将 <PLACEHOLDERS> 替换为你的值。

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentParameters.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "datadogapikey": {
      "reference": {
        "keyVault": {
          "id": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP_NAME>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT_NAME>"
        },
        "secretName": "<KEY_VAULT_SECRET_NAME>"
      }
    }
  }
}

现在可以在 ARM 模板中引用 datadogapikey 参数。

{
  ...
  "parameters": {
    "datadogapikey": {
      "type": "securestring"
    }
  },
  "properties": {
    ...
    "openTelemetryConfiguration": {
      ...
      "destinationsConfiguration":{
        ...
        "dataDogConfiguration":{
          "site": "<YOUR_DATADOG_SUBDOMAIN>.datadoghq.com",
          "key": "<YOUR_DATADOG_KEY>"
        }
      },
      "tracesConfiguration":{
        "destinations": ["dataDog"]
      },
      "metricsConfiguration": {
        "destinations": ["dataDog"]
      }
    }
  }
}

若要部署资源,请运行以下Azure CLI命令,将 <PLACEHOLDERS> 替换为值。

az deployment group create \
  --resource-group <RESOURCE_GROUP> \
  --template-file <ARM_TEMPLATE_FILE> \
  --parameters <PARAMETER_FILE>

OTLP 终结点

OpenTelemetry 协议 (OTLP) 终结点是使用 OpenTelemetry 数据的遥测数据目标。 在应用程序配置中,可以添加多个 OTLP 终结点。 以下示例添加两个终结点,并将以下数据发送到这些终结点。

端点名称 数据发送到终结点
oltp1 指标和/或追踪
oltp2 日志和/或追踪

虽然可以根据需要设置任意数量的 OTLP 配置的终结点,但每个终结点必须具有不同的名称。

{
  "properties": {
    "appInsightsConfiguration": {},
    "openTelemetryConfiguration": {
      "destinationsConfiguration":{
        "otlpConfigurations": [
          {
            "name": "otlp1",
            "endpoint": "ENDPOINT_URL_1",
            "insecure": false,
            "headers": "api-key-1=key"
          },
          {
            "name": "otlp2",
            "endpoint": "ENDPOINT_URL_2",
            "insecure": true
          }
        ]
      },
      "logsConfiguration": { 
        "destinations": ["otlp2"]
      },
      "tracesConfiguration":{
        "destinations": ["otlp1", "otlp2"]
      },
      "metricsConfiguration": {
        "destinations": ["otlp1"]
      }
    }
  }
}

名称 描述
resource-group 资源组的名称。 可以使用 az configure --defaults group=<NAME> 配置默认组。
name 容器应用环境的名称。
otlp-name 您选择的用于标识 OTLP 配置终结点的名称。
endpoint 负责接收所收集数据的目标 URL。
insecure 默认值为 true。 定义是否为导出程序的 gRPC 连接启用客户端传输安全性。 如果为 false,则需要 headers 参数。
headers 空格分隔的值(采用“key=value”格式)提供确保 OTLP 终结点安全性所需的信息。 示例:"api-key=key other-config-value=value"

配置数据目标

若要配置代理,请使用 destinations 数组来定义应用程序将数据发送到哪个代理。 有效键是 appInsightsdataDog 或自定义 OTLP 终结点的名称。 可以控制代理的行为方式,具体取决于数据类型和终结点相关选项。

按数据类型

选项 示例
选择数据类型。 可以单独配置日志、指标和/或跟踪。
启用或禁用任何数据类型。 可以选择仅发送跟踪,而不发送其他数据。
将一种数据类型发送到多个终结点。 可以将日志同时发送到 Datadog 和按 OTLP 配置的端点。
将不同的数据类型发送到不同的位置。 可以将跟踪发送到 OTLP 终结点,并将指标发送到 Datadog。
禁止发送所有数据类型。 可以选择不通过 OpenTelemetry 代理发送任何数据。

按终结点

  • 每次只能分别设置一个 Application Insights 和一个 Datadog 终结点。
  • 虽然可以定义多个 OTLP 配置的终结点,但每个终结点必须具有不同的名称。

以下示例 ARM 模板演示如何使用名为 customDashboard 的 OTLP 终结点。 它发送:

  • 将追踪数据发送到 App Insights 和 customDashboard
  • 将日志发送到 App Insights 和 customDashboard
  • 发送到 Datadog 和 customDashboard 的指标
{
  ...
  "properties": {
    ...
    "openTelemetryConfiguration": {
      ...
      "tracesConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "logsConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "metricsConfiguration": {
        "destinations": [
          "dataDog",
          "customDashboard"
        ]
      }
    }
  }
}

导出系统组件 OpenTelemetry 信号

从 OpenTelemetry API 版本 2024-08-02-preview,可以将容器应用环境配置为将系统组件 OpenTelemetry 信号导出到数据目标。

使用以下配置导出 Dapr 跟踪和 KEDA 指标。

Dapr 跟踪

以下示例 ARM 模板展示如何将 Dapr 跟踪导出到您的跟踪目标。

{
  ...
  "properties": {
    ...
    "openTelemetryConfiguration": {
      ...
      "tracesConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ],
        "includeDapr": true
      }
    }
  }
}

若要详细了解如何在容器应用中使用 Dapr,请参阅 Dapr 概述

KEDA 指标

以下示例 ARM 模板演示如何将 KEDA 指标导出到指标目标。

{
  ...
  "properties": {
    ...
    "openTelemetryConfiguration": {
      ...
      "metricsConfiguration": {
        "destinations": [
          "dataDog",
          "customDashboard"
        ],
        "includeKeda": true
      }
    }
  }
}

若要详细了解容器应用中的 KEDA 支持,请参阅 “设置缩放规则”。

示例 OpenTelemetry 配置

以下示例模板演示如何将容器应用配置为使用 Azure Monitor Application Insights、Datadog 以及名为 customDashboard 的自定义 OTLP 代理收集遥测数据。

此示例适用于用于从Azure 密钥保管库检索 Datadog API 密钥的参数文件。

在部署此模板之前,请将 <PLACEHOLDERS> 替换为你的值。

{
  "location": "chinanorth3",
  "properties": {
    "appInsightsConfiguration": {
      "connectionString": "<APP_INSIGHTS_CONNECTION_STRING>"
    },
    "openTelemetryConfiguration": {
      "destinationsConfiguration": {
        "dataDogConfiguration": {
          "site": "datadoghq.com",
          "key": "parameters('datadogapikey')]"
        },
        "otlpConfigurations": [
          {
            "name": "customDashboard",
            "endpoint": "<OTLP_ENDPOINT_URL>",
            "insecure": true
          }
        ]
      },
      "tracesConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "logsConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "metricsConfiguration": {
        "destinations": [
          "dataDog",
          "customDashboard"
        ]
      }
    }
  }
}

有关详细信息,请参阅 Microsoft。App/managedEnvironments

数据复原能力

当消息传送中断到终结点时,OpenTelemetry 代理使用以下过程来支持数据复原:

  • 内存中缓冲和重试:代理将数据存储在内存中,并持续重试(使用回退)最多 5 分钟。
  • 删除数据:如果缓冲队列填满,或者终结点在重试后仍在关闭,则代理会丢弃最早的批处理,以避免内存不足。

环境变量

OpenTelemetry 代理在运行时自动将一组环境变量注入应用程序。

前三个环境变量遵循标准 OpenTelemetry 配置,并在 OTLP 标准软件开发工具包中使用。 如果在容器应用规范中显式设置环境变量,则值将覆盖自动注入的值。

请参阅 OTLP 导出程序配置了解 OTLP 导出程序配置。

名称 描述
OTEL_EXPORTER_OTLP_ENDPOINT 任何信号类型的基终结点 URL(具有可选的指定端口号)。 将多个信号发送到同一终结点并想要一个控制该终结点的环境变量时,此设置很有用。 示例: http://otel.service.k8se-apps:4317/
OTEL_EXPORTER_OTLP_PROTOCOL 指定用于所有遥测数据的 OTLP 传输协议。 托管代理仅支持 grpc。 值:grpc
OTEL_RESOURCE_ATTRIBUTES 以逗号分隔的键值对列表,定义了附加到所有遥测数据的资源属性。 托管代理使用容器应用属性(如应用名称和环境)填充此变量。 某些 OpenTelemetry SDK 实现要求显式启用基于环境的资源检测以使用这些属性。 如果在容器应用规范中设置此变量,则值将覆盖自动注入的值。

其他三个环境变量特定于Azure 容器应用,并且始终注入。 这些变量会为每个特定数据类型(日志、指标、跟踪)保存代理的终结点 URL。

仅当同时使用托管的 OpenTelemetry 代理和另一个 OpenTelemetry 代理时,才需要这些变量。 使用这些变量可以控制如何在不同的 OpenTelemetry 代理之间路由数据。

名称 描述 示例
CONTAINERAPP_OTEL_TRACING_GRPC_ENDPOINT 仅用于跟踪数据的终结点 URL。 http://otel.service.k8se-apps:43178/v1/traces/
CONTAINERAPP_OTEL_LOGGING_GRPC_ENDPOINT 仅用于日志数据的终结点 URL。 http://otel.service.k8se-apps:43178/v1/logs/
CONTAINERAPP_OTEL_METRIC_GRPC_ENDPOINT 仅用于指标数据的终结点 URL。 http://otel.service.k8se-apps:43178/v1/metrics/

OpenTelemetry 代理成本

托管 OpenTelemetry 代理无需额外的计算成本即可运行。 Microsoft在容器应用环境中预配和管理代理基础结构。

因此,您需负责您将遥测数据发送到的目的服务所产生的费用。 请参阅目标服务了解其计费结构和条款。 例如,如果同时将数据发送到 Azure Monitor Application Insights 和 Datadog,您需要支付这两项服务收取的费用。

代理资源分配

托管 OpenTelemetry 代理预配了以下固定资源:

  • CPU:0.5 个 vCPU 核心
  • 内存:1.5 GB RAM
  • 副本:单个副本(不可配置)

这些资源由Microsoft管理,不会显示在计费或资源消耗指标中。

已知限制

  • 系统数据(如系统日志或容器应用标准指标)无法发送到 OpenTelemetry 代理。
  • Application Insights 终结点不接受指标。
  • 配置设置驻留在环境级别。 可以将不同的数据类型发送到不同的目标,但不能按应用拆分数据。 例如,在同一应用中,可以将指标发送到 Datadog,并将跟踪发送到 App Insights。
  • 托管代理仅支持遥测数据的 gRPC 传输协议。
  • 托管 OpenTelemetry 代理作为单个副本运行,无法缩放或配置为高可用性。
  • 代理状态和运行状况指标当前不会在Azure门户中或通过监视 API 公开。
  • 机密(如 API 密钥)必须直接在模板中指定 - 当前不支持代理配置的Azure 密钥保管库集成。

常见问题

  • 是否需要在代码中引用 OpenTelemetry SDK?

    是的。 SDK 创建遥测数据,托管代理仅负责路由数据。

  • list为什么命令返回 null?

    运行 az containerapp env telemetry otlp list 时,如果该值是需要保护的敏感令牌,则响应是 null

  • 是否对 OpenTelemetry 代理的计算资源收费?

    否。 Microsoft预配和管理代理基础结构,无需额外的计算费用。 仅对接收遥测数据的目标服务收费。

  • 是否可以缩放 OpenTelemetry 代理或运行多个副本?

    否。 托管代理当前作为具有固定资源分配的单个副本运行(0.5 CPU、1.5GB RAM)。 目前不支持高可用性配置。

  • 如何监视 OpenTelemetry 代理的运行状况和状态?

    代理状态和运行状况指标当前未公开。 此功能计划在将来的版本中使用。

自定义 DNS 配置

托管的 OpenTelemetry 收集器遵循容器应用环境中的自定义 DNS 配置。 如果已配置自定义 DNS 设置,收集器会在连接到外部终结点时自动使用这些设置进行名称解析。 这可确保你的 OpenTelemetry 数据通过网络基础设施正确路由。

后续步骤