Sammeln und Lesen von OpenTelemetry-Daten in Azure Container Apps (Vorschau)

Artikel
12/17/2024

Mit einem OpenTelemetry-Datenagent mit Ihrer Azure Container Apps-Umgebung können Sie Einblickdaten in einem OpenTelemetry-Format senden, indem Sie:

Daten von einem Agent an einen gewünschten Endpunkt weiterleiten. Zu den Zieloptionen gehören Azure Monitor Application Insights, Datadog und alle mit OpenTelemetry Protocol (OTLP) kompatiblen Endpunkte.
Einfaches Ändern von Zielendpunkten, ohne dass die Datenausgabe neu konfiguriert werden muss und ohne dass ein OpenTelemetry-Agent manuell ausgeführt werden muss.

In diesem Artikel erfahren Sie, wie Sie einen OpenTelemetry-Agent für Ihre Container-App einrichten und konfigurieren.

Konfigurieren eines OpenTelemetry-Agents

OpenTelemetry-Agents befinden sich in Ihrer Container-App-Umgebung. Sie konfigurieren die Agent-Einstellungen über eine ARM-Vorlage oder Bicep-Aufrufe an die Umgebung oder über die CLI oder über Terraform (via AzAPI-Anbieter).

Jeder Endpunkttyp (Azure Monitor Application Insights, DataDog und OTLP) hat spezifische Konfigurationsanforderungen.

Voraussetzungen

Das Aktivieren des verwalteten OpenTelemetry-Agents für Ihre Umgebung bedeutet nicht automatisch, dass der Agent Daten sammelt. Agents senden Daten nur basierend auf Ihrer Konfigurationseinstellungen und der korrekten Instrumentierung Ihres Codes.

Konfigurieren des Quellcodes

Bereiten Sie Ihre Anwendung auf die Datenerfassung vor, indem Sie das OpenTelemetry SDK installieren und die OpenTelemetry-Richtlinien befolgen, um Metriken, Protokolle oder Ablaufverfolgungen zu instrumentieren.

Initialisieren von Endpunkten

Bevor Sie Daten an ein Sammlungsziel senden können, müssen Sie zuerst eine Instanz des Zieldiensts erstellen. Wenn Sie beispielsweise Daten an Azure Monitor Application Insights senden möchten, müssen Sie zuvor eine Application Insights-Instanz erstellen.

Der verwaltete OpenTelemetry-Agent akzeptiert die folgenden Ziele:

Azure Monitor Application Insights
Datadog
Alle OTLP-Endpunkte (z. B.: New Relic oder Honeycomb)

Die folgende Tabelle zeigt, welche Art von Daten Sie an jedes Ziel senden können:

Destination	Protokolle	Metriken	Traces
Azure App Insights	Ja	Keine	Ja
Datadog	No	Ja	Ja
Konfigurierter Endpunkt des OpenTelemetry-Protokolls (OTLP)	Ja	Ja	Ja

Azure Monitor Application Insights

Das einzige Konfigurationsdetail, das von Application Insights benötigt wird, ist die Verbindungszeichenfolge. Sobald Sie über die Verbindungszeichenfolge verfügen, können Sie den Agent über die ARM-Vorlage Ihrer Container-App oder mit Azure CLI-Befehlen oder Terraform konfigurieren.

Die Verbindungszeichenfolge enthält einen Instrumentierungsschlüssel, einen eindeutigen Bezeichner, der verwendet wird, um Telemetriedaten einer bestimmten Application Insights-Ressource zuzuordnen. Instrumentierungsschlüssel sind keine Sicherheitstoken oder Sicherheitsschlüssel und gelten nicht als geheime Schlüssel.

Wenn Sie Ihre Application Insights-Ressource vor Missbrauch schützen möchten, lesen Sie die Microsoft Entra-Authentifizierung für Application Insights.

Ersetzen Sie von <> umgebene Platzhalter durch Ihre Werte, bevor Sie diese Vorlage bereitstellen.

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

Ersetzen Sie von <> umgebene Platzhalter durch Ihre Werte, bevor Sie diesen Befehl ausführen.

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

Hinweis

Aufgrund der Vertraulichkeit der Verbindungszeichenfolge können Sie die Detailwerte der Verbindungszeichenfolge nicht sehen, wenn der Befehl zurückgegeben wird. Das System zeigt sie als NULL an.

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

Die Konfiguration des Datadog-Agents erfordert einen Wert für site und key von Ihrer Datadog-Instanz. Erfassen Sie diese Werte von Ihrer Datadog-Instanz gemäß dieser Tabelle:

Eigenschaft für Datadog-Agent	Konfigurationseigenschaft für Container Apps
`DD_SITE`	`site`
`DD_API_KEY`	`key`

Sobald Sie über diese Konfigurationsdetails verfügen, können Sie den Agent über die ARM-Vorlage Ihrer Container-App oder mit Azure CLI-Befehlen konfigurieren.

Vermeiden Sie die Angabe des Werts eines geheimen Schlüssels, z. B. des Datadog-API-Schlüssels, direkt in einer Produktionsumgebung. Verwenden Sie stattdessen einen Verweis auf einen geheimen Schlüssel, der in Azure Key Vault gespeichert ist.

Sie müssen den Schlüsseltresor für die Vorlagenbereitstellung aktivieren. Erstellen Sie dazu den Schlüsseltresor mit aktivierter enabledForTemplateDeployment-Eigenschaft, oder führen Sie den folgenden Azure CLI-Befehl aus, und ersetzen Sie <KEY_VAULT_NAME> durch Ihren Wert:

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

Weitere Informationen finden Sie unter:

Erstellen Sie eine Parameterdatei, um Ihren Datadog-API-Schlüssel aus einem Azure Key Vault abzurufen.

Bevor Sie den folgenden Befehl ausführen, ersetzen Sie von <> umgebene Platzhalter durch Ihre Werten.

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

Sie können nun auf den datadogapikey-Parameter in der ARM-Vorlage verweisen.

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

Um die Ressource bereitzustellen, führen Sie den folgenden Azure CLI-Befehl aus, und ersetzen Sie die von <> umgebenen Platzhalter durch Ihre Werte.

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

Ersetzen Sie von <> umgebene Platzhalter durch Ihre Werte, bevor Sie diesen Befehl ausführen.

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

Hinweis

Aufgrund der Vertraulichkeit des Schlüssels können Sie die Detailwerte des Schlüssels nicht sehen, wenn der Befehl zurückgegeben wird. Das System zeigt sie als NULL an.

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-Endpunkt

Ein OpenTelemetry-Protokollendpunkt (OTLP) ist ein Telemetriedatenziel, das OpenTelemetry-Daten verwendet. In Ihrer Anwendungskonfiguration können Sie mehrere OTLP-Endpunkte hinzufügen. Im folgenden Beispiel werden zwei Endpunkte hinzugefügt und die folgenden Daten an diese Endpunkte gesendet.

Endpunktname	An Endpunkt gesendete Daten
`oltp1`	Metriken und/oder Ablaufverfolgungen
`oltp2`	Protokolle und/oder Ablaufverfolgungen

Sie können zwar beliebig viele OTLP-konfigurierte Endpunkte einrichten, aber jeder Endpunkt muss einen eindeutigen Namen haben.

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

Hinweis

Aufgrund der Vertraulichkeit des Headerwerts können Sie die Detailwerte des Headerwerts nicht sehen, wenn der Befehl zurückgegeben wird. Das System zeigt sie als NULL an.

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

Name	Beschreibung
`resource-group`	Name der Ressourcengruppe Sie können die Standardgruppe mit `az configure --defaults group=<NAME>` konfigurieren.
`name`	Name der Container-Apps-Umgebung.
`otlp-name`	Ein Name, den Sie auswählen, um Ihren OTLP-konfigurierten Endpunkt zu identifizieren.
`endpoint`	Die URL des Ziels, das gesammelte Daten empfängt.
`insecure`	Die Standardeinstellung ist „true“. Legt fest, ob die Clienttransportsicherheit für die gRPC-Verbindung des Exporters aktiviert wird. Bei „false“ ist der Parameter `headers` erforderlich.
`headers`	Durch Leerzeichen getrennte Werte im Format 'key=value', die erforderliche Informationen für die Sicherheit der OTLP-Endpunkte bereitstellen. Beispiel: `"api-key=key other-config-value=value"`.

Konfigurieren von Datenzielen

Verwenden Sie zum Konfigurieren eines Agents das destinations-Array, um festzulegen, an welche Agents Ihre Anwendung Daten sendet. Gültige Schlüssel sind entweder appInsights, dataDog oder der Name Ihres benutzerdefinierten OTLP-Endpunkts. Sie können das Verhalten eines Agents anhand von datentyp- und endpunktbezogenen Optionen steuern.

Nach Datentyp

Option	Beispiel
Wählen Sie einen Datentyp aus.	Sie können Protokolle, Metriken und/oder Ablaufverfolgungen einzeln konfigurieren.
Aktivieren oder Deaktivieren eines beliebigen Datentyps	Sie können festlegen, dass nur Ablaufverfolgungen und keine anderen Daten gesendet werden sollen.
Senden eines Datentyps an mehrere Endpunkte	Sie können Protokolle sowohl an DataDog als auch an einen OTLP-konfigurierten Endpunkt senden.
Senden von verschiedenen Datentypen an verschiedene Speicherorte	Sie können Ablaufverfolgungen an einen OTLP-Endpunkt und Metriken an DataDog senden.
Das Senden aller Datentypen deaktivieren	Sie können festlegen, dass keine Daten über den OpenTelemetry-Agent gesendet werden.

Nach Endpunkt

Sie können jeweils nur einen Application Insights- und Datadog-Endpunkt einrichten.
Sie können zwar mehrere OTLP-konfigurierte Endpunkte definieren, aber jeder muss einen eindeutigen Namen haben.

In der folgenden ARM-Beispielvorlage wird die Verwendung eines OTLP-Endpunkts namens customDashboard gezeigt. Er sendet:

Ablaufverfolgungen an App Insights und customDashboard
Protokolle an App-Insights und customDashboard
Metriken an DataDog und customDashboard

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

Beispielsweise OpenTelemetry-Konfiguration

Die folgende beispielhafte ARM-Vorlage zeigt, wie Sie Ihre Container App konfigurieren können, um Telemetriedaten mit Azure Monitor Application Insights, Datadog und einem benutzerdefinierten OTLP-Agenten namens customDashboard zu sammeln.

In diesem Beispiel wird die Parameterdatei verwendet, um den Datadog-API-Schlüssel aus einem Azure Key Vault abzurufen.

Ersetzen Sie von <> umgebene Platzhalter durch Ihre Werte, bevor Sie diese Vorlage bereitstellen.

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

Weitere Informationen finden Sie unter Microsoft.App/managedEnvironments.

Umgebungsvariablen

Der OpenTelemetry-Agent fügt zur Runtime automatisch eine Reihe von Umgebungsvariablen in Ihre Anwendung ein.

Die ersten beiden Umgebungsvariablen entsprechen der Standardkonfiguration des OpenTelemetry-Exporters und werden in standardmäßigen OTLP-Software Development Kits verwendet. Wenn Sie die Umgebungsvariable in der Spezifikation der Container-App explizit festlegen, überschreibt Ihr Wert den automatisch eingefügten Wert.

Informationen zur Konfiguration des OTLP-Exporters finden Sie unter OTLP-Exporterkonfiguration.

Name	Beschreibung
`OTEL_EXPORTER_OTLP_ENDPOINT`	Eine Basisendpunkt-URL für einen beliebigen Signaltyp mit optional angegebener Portnummer. Diese Einstellung ist hilfreich, wenn Sie mehr als ein Signal an denselben Endpunkt senden und eine Umgebungsvariable zur Steuerung des Endpunkts nutzen möchten. Beispiel: `http://otel.service.k8se-apps:4317/`
`OTEL_EXPORTER_OTLP_PROTOCOL`	Gibt das OTLP-Transportprotokoll an, das für alle Telemetriedaten verwendet wird. Der verwaltete Agent unterstützt nur `grpc`. Wert: `grpc`.

Die anderen drei Umgebungsvariablen sind spezifisch für Azure Container Apps und werden immer eingefügt. Diese Variablen enthalten die Endpunkt-URLs des Agents für jeden spezifischen Datentyp (Protokolle, Metriken, Ablaufverfolgungen).

Diese Variablen sind nur erforderlich, wenn Sie sowohl den verwalteten OpenTelemetry-Agent als auch einen anderen OpenTelemetry-Agent verwenden. Mithilfe dieser Variablen können Sie steuern, wie Daten zwischen den verschiedenen OpenTelemetry-Agents weitergeleitet werden.

Name	Beschreibung des Dataflows	Beispiel
`CONTAINERAPP_OTEL_TRACING_GRPC_ENDPOINT`	Endpunkt-URL nur für Ablaufverfolgungsdaten.	`http://otel.service.k8se-apps:43178/v1/traces/`
`CONTAINERAPP_OTEL_LOGGING_GRPC_ENDPOINT`	Endpunkt-URL nur für Protokolldaten.	`http://otel.service.k8se-apps:43178/v1/logs/`
`CONTAINERAPP_OTEL_METRIC_GRPC_ENDPOINT`	Endpunkt-URL nur für Metrikdaten.	`http://otel.service.k8se-apps:43178/v1/metrics/`

Kosten für OpenTelemetry-Agents

Die zugrunde liegende Rechenleistung des Agents wird Ihnen in Rechnung gestellt.

Die Abrechnungsstruktur und -bedingungen finden Sie beim jeweiligen Zieldienst. Wenn Sie beispielsweise Daten sowohl an Azure Monitor Application Insights als auch an Datadog senden, sind Sie für die von beiden Diensten erhobenen Gebühren verantwortlich.

Bekannte Einschränkungen

OpenTelemetry-Agents befinden sich in der Vorschau.
Systemdaten, z. B. Systemprotokolle oder Standardmetriken für Container Apps, können nicht an den OpenTelemetry-Agent gesendet werden.
Der Application Insights-Endpunkt akzeptiert keine Metriken.
Der Datadog-Endpunkt akzeptiert keine Protokolle.

Nächste Schritte

Informationen zu Überwachung und Integrität

Freigeben über

Sammeln und Lesen von OpenTelemetry-Daten in Azure Container Apps (Vorschau)

Konfigurieren eines OpenTelemetry-Agents

Voraussetzungen

Konfigurieren des Quellcodes

Initialisieren von Endpunkten

Azure Monitor Application Insights

Datadog

OTLP-Endpunkt

Konfigurieren von Datenzielen

Nach Datentyp

Nach Endpunkt

Beispielsweise OpenTelemetry-Konfiguration

Umgebungsvariablen

Kosten für OpenTelemetry-Agents

Bekannte Einschränkungen

Nächste Schritte

Feedback

Zusätzliche Ressourcen