在 Azure 容器应用中收集和读取 OpenTelemetry 数据（预览版）

项目
06/03/2024

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

将来自代理的数据输送到所需的终结点。目标选项包括 Azure Monitor Application Insights、Datadog 和任何与 OpenTelemetry 协议 (OTLP) 兼容的终结点。
轻松更改目标终结点，而无需重新配置其发出数据的方式，也无需手动运行 OpenTelemetry 代理。

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

配置 OpenTelemetry 代理

OpenTelemetry 代理位于容器应用环境中。可通过 ARM 模板或对环境的 Bicep 调用或通过 CLI 配置代理设置。

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

先决条件

向环境启用托管 OpenTelemetry 代理并不意味着代理会收集数据。代理仅根据配置设置发送数据并正确检测代码。

配置源代码

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

初始化终结点

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

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

Azure Monitor Application Insights
Datadog
任何 OTLP 终结点（例如：New Relic 或 Honeycomb）

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

目标	日志	指标	Traces
Azure App Insights	是	No	是
Datadog	否	是	是
OpenTelemetry 协议 (OTLP) 配置的终结点	是	是	是

Azure Monitor Application Insights

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

ARM 模板
Azure CLI

在部署此模板之前，请将使用 <> 括起来的占位符替换为你的值。

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

在运行以下命令之前，请将使用 <> 括起来的占位符替换为你的值。

az containerapp env telemetry app-insights set \
  --connection-string <YOUR_APP_INSIGHTS_CONNECTION_STRING> \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-logs true

Datadog

Datadog 代理配置需要使用来自 Datadog 实例的 site 和 key 值。根据下表从 Datadog 实例收集这些值：

Datadog 代理属性	容器应用配置属性
`DD_SITE`	`site`
`DD_API_KEY`	`key`

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

ARM 模板
Azure CLI

在部署此模板之前，请将使用 <> 括起来的占位符替换为你的值。

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

在运行以下命令之前，请将使用 <> 括起来的占位符替换为你的值。

az containerapp env telemetry data-dog set \
  --site  "<YOUR_DATADOG_SUBDOMAIN>.datadoghq.com" \
  --key <YOUR_DATADOG_KEY> \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-metrics true

OTLP 终结点

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

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

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

ARM 模板
Azure CLI

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

az containerap env telemetry otlp add \
  --name "otlp1"
  --endpoint "ENDPOINT_URL_1" \
  --insecure false \
  --headers "api-key-1=key" \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-metrics true
az containerap env telemetry otlp add \
  --name "otlp2"
  --endpoint "ENDPOINT_URL_2" \
  --insecure true \
  --enable-open-telemetry-traces true \
  --enable-open-telemetry-logs true

名称	描述
`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 配置的终结点，但每个终结点必须具有不同的名称。

以下示例演示如何使用名为 customDashboard 的 OTLP 终结点。它：

将跟踪发送到 App Insights 和 customDashboard
将日志发送到 App Insights 和 customDashboard
将指标发送到 Datadog 和 customDashboard

{
  ...
  "properties": {
    ...
    "openTelemetryConfiguration": {
      ...
      "tracesConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "logsConfiguration": {
        "destinations": [
          "appInsights",
          "customDashboard"
        ]
      },
      "metricsConfiguration": {
        "destinations": [
          "dataDog",
          "customDashboard"
        ]
      }
    }
  }
}

## Example OpenTelemetry configuration

The following example ARM template shows how you might configure your container app to collect telemetry data using Azure Monitor Application Insights, Datadog, and with a custom OTLP agent named `customDashboard`.

Before you deploy this template, replace placeholders surrounded by `<>` with your values.

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

环境变量

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

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

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

名称	描述
`OTEL_EXPORTER_OTLP_ENDPOINT`	任何信号类型的基终结点 URL（具有可选的指定端口号）。将多个信号发送到同一终结点并想要一个控制该终结点的环境变量时，此设置很有用。示例： `http://otel.service.k8se-apps:4317/`
`OTEL_EXPORTER_OTLP_PROTOCOL`	指定用于所有遥测数据的 OTLP 传输协议。托管代理仅支持 `grpc`。值：`grpc`。

其他三个环境变量特定于 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 代理成本

需要为代理的基础计算计费。

请参阅目标服务了解其计费结构和条款。例如，如果将数据发送到 Azure Monitor Application Insights 和 Datadog，则需要负责这两项服务的费用。

已知限制

OpenTelemetry 代理以预览版提供。
系统数据（如系统日志或容器应用标准指标）无法发送到 OpenTelemetry 代理。
Application Insights 终结点不接受指标。
Datadog 终结点不接受日志。

后续步骤

了解监视和运行状况

通过