在 Azure Container Apps 中收集和讀取 OpenTelemetry 數據（預覽）

發行項
12/14/2024

使用 OpenTelemetry 數據代理程式搭配 Azure Container Apps 環境，您可以選擇以 OpenTelemetry 格式傳送可觀察性數據，方法是：

將代理程式的數據管線傳送至所需的端點。目的地選項包括 Azure 監視器 Application Insights、Datadog 和任何與 OpenTelemetry 通訊協定（OTLP）相容的端點。
輕鬆變更目的地端點，而不需要重新設定其發出數據的方式，也不需要手動執行 OpenTelemetry 代理程式。

本文說明如何設定和設定容器應用程式的 OpenTelemetry 代理程式。

設定 OpenTelemetry 代理程式

OpenTelemetry 代理程式位於您的容器應用程式環境中。您可以透過ARM範本或 Bicep 呼叫環境，或透過 CLI 或透過 Terraform 設定代理程式設定（透過 AzAPI 提供者）。

每個端點類型（Azure 監視器 Application Insights、DataDog 和 OTLP）都有特定的設定需求。

必要條件

將受控 OpenTelemetry 代理程式啟用到您的環境並不會自動表示代理程式會收集數據。代理程式只會根據組態設定傳送數據，並正確檢測您的程序代碼。

設定原始碼

安裝 OpenTelemetry SDK 並遵循 OpenTelemetry 指導方針來檢測計量、記錄或追蹤，以準備您的應用程式以收集數據。

初始化端點

您必須先建立目的地服務的實例，才能將數據傳送至集合目的地。例如，如果您想要將數據傳送至 Azure 監視器 Application Insights，則需要事先建立 Application Insights 實例。

受控 OpenTelemetry 代理程式接受下列目的地：

Azure 監視器 Application Insights
Datadog
任何 OTLP 端點（例如：New Relic 或 Honeycomb）

下表顯示您可以傳送至每個目的地的資料類型：

Destination	記錄	計量	追蹤
Azure 應用程式見解	是	無	Yes
Datadog	No	.是	Yes
OpenTelemetry 通訊協定（OTLP）已設定的端點	Yes	.是	Yes

Azure 監視器 Application Insights

Application Insights 所需的唯一組態詳細數據是連接字串。連接字串之後，您可以使用 Azure CLI 命令或 Terraform，透過容器應用程式的 ARM 範本來設定代理程式。

連接字串包含檢測密鑰，這是用來將遙測與特定 Application Insights 資源產生關聯的唯一標識符。檢測金鑰不是安全性令牌或安全性金鑰，也不會被視為秘密。

如果您想要保護 Application Insights 資源免於誤用，請參閱 Microsoft Application Insights 的 Entra 驗證。

部署此範本之前，請以您的值取代所包圍的 <> 佔位符。

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

執行命令之前，請以您的值取代以 <> 括住的預留位置。

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

注意

由於連接字串的敏感度，當命令傳回時，您將無法看到連接字串的詳細資料值。系統會將它顯示為 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"]
        }
      }
    }
  })
}

Datadog

Datadog 代理程序組態需要 Datadog 實例的和 key 值site。根據下表，從 Datadog 實例收集這些值：

Datadog 代理程序屬性	Container Apps 組態屬性
`DD_SITE`	`site`
`DD_API_KEY`	`key`

取得這些設定詳細數據之後，您可以透過容器應用程式的 ARM 範本或使用 Azure CLI 命令來設定代理程式。

請避免直接在生產環境中指定秘密的值，例如 Datadog API 密鑰。請改用 Azure 金鑰保存庫中所儲存秘密的參考。

您必須啟用範本部署的金鑰保存庫。若要這樣做，請建立已啟用屬性的 enabledForTemplateDeployment 密鑰保存庫，或執行下列 Azure CLI 命令，並將 <KEY_VAULT_NAME> 取代為您的值：

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

如需詳細資訊，請參閱

建立參數檔案，以從 Azure 金鑰保存庫擷取 Datadog API 金鑰。

在您部署下列檔案之前，請以您的值取代所包圍的 <> 佔位符。

{
  "$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 命令，以您的值取代所包圍的 <> 佔位符。

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

執行命令之前，請以您的值取代以 <> 括住的預留位置。

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

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 端點。它會傳送：

追蹤至應用程式深入解析和 customDashboard
記錄至應用程式深入解析和 customDashboard
DataDog 和的計量 customDashboard

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

範例 OpenTelemetry 組態

下列範例 ARM 範本示範如何設定容器應用程式，以使用 Azure 監視器 Application Insights、Datadog 和名為 customDashboard的自定義 OTLP 代理程式來收集遙測數據。

此範例適用於用來從 Azure 金鑰保存庫擷取 Datadog API 金鑰的參數檔案。

部署此範本之前，請以您的值取代所包圍的 <> 佔位符。

{
  "location": "eastus",
  "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 代理程式會在運行時間自動將一組環境變數插入您的應用程式。

前兩個環境變數遵循標準 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（記錄、計量、追蹤）。

只有在您使用 Managed 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 監視器 Application Insights 和 Datadog，您必須負責這兩項服務所套用的費用。

已知的限制

OpenTelemetry 代理程式處於預覽狀態。
系統數據，例如系統記錄或 Container Apps 標準計量，無法傳送至 OpenTelemetry 代理程式。
Application Insights 端點不接受計量。
Datadog 端點不接受記錄。

下一步

瞭解監視和健康情況

共用方式為

在 Azure Container Apps 中收集和讀取 OpenTelemetry 數據（預覽）

設定 OpenTelemetry 代理程式

必要條件

設定原始碼

初始化端點

Azure 監視器 Application Insights

Datadog

OTLP 端點

設定數據目的地

依數據類型

依端點

範例 OpenTelemetry 組態

環境變數

OpenTelemetry 代理程式成本

已知的限制

下一步

意見反應

其他資源

共用方式為

在 Azure Container Apps 中收集和讀取 OpenTelemetry 數據 （預覽）

設定 OpenTelemetry 代理程式

必要條件

設定原始碼

初始化端點

Azure 監視器 Application Insights

Datadog

OTLP 端點

設定數據目的地

依數據類型

依端點

範例 OpenTelemetry 組態

環境變數

OpenTelemetry 代理程式成本

已知的限制

下一步

意見反應

其他資源

在 Azure Container Apps 中收集和讀取 OpenTelemetry 數據（預覽）