在 Azure Container Apps 中收集和读取 OpenTelemetry 数据

在Azure Container Apps环境中使用 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 App Insights	是	否	是
Datadog	是	是	是
OpenTelemetry 协议 (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"]
      }
    }
  }
}

resource environment 'Microsoft.App/managedEnvironments@2024-10-02-preview' = {
  ...
  properties: {
    appInsightsConfiguration: {
      connectionString: '<APP_INSIGHTS_CONNECTION_STRING>'
    }
    openTelemetryConfiguration: {
      ...
      tracesConfiguration: {
        destinations: [
          'appInsights'
        ]
      }
      logsConfiguration: {
        destinations: [
          'appInsights'
        ]
      }
    }
  }
}

运行此命令之前，请将 <PLACEHOLDERS> 替换为你的值。

az containerapp env telemetry app-insights set \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --connection-string <APP_INSIGHTS_CONNECTION_STRING> \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-logs true

注意

由于连接字符串的敏感度，命令返回时看不到connection string的详细信息值。系统将其显示为 null。

resource "azapi_update_resource" "app_insights_open_telemetry_integration" {
  name      = azurerm_container_app_environment.managed_environment.name
  parent_id = azurerm_resource_group.resource_group.id
  type      = "Microsoft.App/managedEnvironments@2023-11-02-preview"
  body = jsonencode({
    properties = {
      appInsightsConfiguration = {
        connectionString = azurerm_application_insights.applicationinsights.connection_string
      }
      appLogsConfiguration = {
        destination = "log-analytics"
        logAnalyticsConfiguration = {
          customerId = azurerm_log_analytics_workspace.workspace.workspace_id
          sharedKey  = azurerm_log_analytics_workspace.workspace.primary_shared_key
        }
      }
      openTelemetryConfiguration = {
        tracesConfiguration = {
          destinations = ["appInsights"]
        }
        logsConfiguration = {
          destinations = ["appInsights"]
        }
      }
    }
  })
}

数据狗

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

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

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

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

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

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

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

有关详细信息，请参阅：

创建 parameter 文件以从Azure Key Vault检索 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>

创建 parameter 文件以从Azure Key Vault检索 Datadog API 密钥。

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

using '<BICEP_TEMPLATE_FILE>'

param datadogapikey = az.getSecret('<SUBSCRIPTION_ID>', '<RESOURCE_GROUP_NAME>', '<KEY_VAULT_NAME>', '<SECRET_NAME>', '<SECRET_VERSION_ID>')

订阅 ID 的格式为 aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e。机密版本 ID 的格式为 123e4567e89b12d3a456426614174000。

现在可以在 Bicep 文件中引用 datadogapikey 参数。

@secure()
param datadogapikey string

resource environment 'Microsoft.App/managedEnvironments@2024-10-02-preview' = {
  ...
  properties: {
    openTelemetryConfiguration: {
      destinationsConfiguration: {
        dataDogConfiguration: {
          site: 'datadoghq.com'
          key: datadogapikey
        }
      }
      ...
      metricsConfiguration: {
        destinations: [
          'dataDog'
          'customDashboard'
        ]
      }
    }
  }
}

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

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

运行此命令之前，请将 <PLACEHOLDERS> 替换为你的值。

az containerapp env telemetry data-dog set \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --site "<DATADOG_SUBDOMAIN>.datadoghq.com" \
  --key <DATADOG_KEY> \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-metrics true

注意

由于键的敏感度，命令返回时看不到键的详细信息值。系统将其显示为 null。

resource "azapi_update_resource" "app_insights_open_telemetry_integration" {
  name      = azurerm_container_app_environment.managed_environment.name
  parent_id = azurerm_resource_group.resource_group.id
  type      = "Microsoft.App/managedEnvironments@2023-11-02-preview"
  body = jsonencode({
    properties = {
      openTelemetryConfiguration = {
        destinationsConfiguration = {
          dataDogConfiguration = {
            site = "<YOUR_DATADOG_SUBDOMAIN>.datadoghq.com"
            key = "<YOUR_DATADOG_KEY>"
          }
        }
        tracesConfiguration = {
          destinations = ["dataDog"]
        }
        metricsConfiguration = {
          destinations = ["dataDog"]
        }
      }
    }
  })
}

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 environment 'Microsoft.App/managedEnvironments@2024-10-02-preview' = {
  ...
  properties: {
    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'
        ]
      }
    }
  }
}

az containerapp env telemetry otlp add \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --otlp-name "otlp1" \
  --endpoint "ENDPOINT_URL_1" \
  --insecure false \
  --headers "api-key-1=key" \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-metrics true
az containerapp env telemetry otlp add \
  --resource-group <RESOURCE_GROUP_NAME> \
  --name <ENVIRONMENT_NAME> \
  --otlp-name "otlp2" \
  --endpoint "ENDPOINT_URL_2" \
  --insecure true \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-logs true

注意

由于标头值的敏感度，命令返回时看不到标头值的详细信息值。系统将其显示为 null。

resource "azapi_update_resource" "app_insights_open_telemetry_integration" {
  name      = azurerm_container_app_environment.managed_environment.name
  parent_id = azurerm_resource_group.resource_group.id
  type      = "Microsoft.App/managedEnvironments@2023-11-02-preview"
  body = jsonencode({
    properties = {
      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 数组来定义应用程序将数据发送到哪个代理。有效键是 appInsights、dataDog 或自定义 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 Key Vault检索 Datadog API 密钥的参数文件。

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

ARM 模板
Bicep

{
  "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"
        ]
      }
    }
  }
}

@secure()
param datadogapikey string

resource environment 'Microsoft.App/managedEnvironments@2024-10-02-preview' = {
  name: '<ENVIRONMENT_NAME>'
  location: '<LOCATION>'
  properties: {
    appInsightsConfiguration: {
      connectionString: '<APP_INSIGHTS_CONNECTION_STRING>'
    }
    openTelemetryConfiguration: {
      destinationsConfiguration: {
        dataDogConfiguration: {
          site: 'datadoghq.com'
          key: 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`。

其他三个环境变量特定于Azure Container Apps，并且始终注入。这些变量会为每个特定数据类型（日志、指标、跟踪）保存代理的终结点 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 Key Vault集成。

常见问题

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

是的。 SDK 创建遥测数据，托管代理仅负责路由数据。
list为什么命令返回 null？

运行 az containerapp env telemetry otlp list 时，如果该值是需要保护的敏感令牌，则响应是 null。
是否对 OpenTelemetry 代理的计算资源收费？

否。 Microsoft预配和管理代理基础结构，无需额外的计算费用。仅对接收遥测数据的目标服务收费。
是否可以缩放 OpenTelemetry 代理或运行多个副本？

否。托管代理当前作为具有固定资源分配的单个副本运行（0.5 CPU、1.5GB RAM）。目前不支持高可用性配置。
如何监视 OpenTelemetry 代理的运行状况和状态？

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

后续步骤

学习关于监控和健康

Last updated on 2026-04-22

共用方式為