Collecter et lire des données OpenTelemetry dans Azure Container Apps

À l’aide d’un agent de données OpenTelemetry avec votre environnement Azure Container Apps, vous pouvez choisir d’envoyer des données d’observabilité dans un format OpenTelemetry en :

• Redirigeant les données d’un agent vers un point de terminaison souhaité. Les options de destination incluent Azure Monitor Application Insights, Datadog et tout point de terminaison compatible OTLP (OpenTelemetry Protocol).

• Modifiant facilement les points de terminaison de destination sans avoir à reconfigurer la façon dont ils émettent les données et sans avoir à exécuter manuellement un agent OpenTelemetry.

Cet article explique comment installer et configurer un agent OpenTelemetry pour votre application conteneur.

Configurer un agent OpenTelemetry

Les agents OpenTelemetry résident dans votre environnement d’application conteneur. Vous configurez les paramètres de l’agent via un modèle ARM ou des appels Bicep vers l’environnement, ou via l’interface CLI, ou via Terraform (via le fournisseur AzAPI).

Chaque type de point de terminaison (Azure Monitor Application Insights, Datadog et OTLP) est associé à des exigences de configuration spécifiques.

Prérequis

L’activation de l’agent OpenTelemetry managé pour votre environnement ne signifie pas automatiquement que l’agent collecte des données. Les agents envoient uniquement des données en fonction de vos paramètres de configuration et instrumentent correctement votre code.

Configurer le code source

Préparez votre application à collecter des données en installant le Kit de développement logiciel (SDK) OpenTelemetry et suivez les instructions OpenTelemetry pour instrumenter les métriques, les journaux ou les traces.

Initialiser les points de terminaison

Avant de pouvoir envoyer des données à une destination de collecte, vous devez créer une instance du service de destination. Par exemple, si vous souhaitez envoyer des données à Azure Monitor Application Insights, vous devez créer au préalable une instance Application Insights.

L’agent OpenTelemetry managé accepte les destinations suivantes :

• Azure Monitor Application Insights (Outil de surveillance des applications)
• Datadog
• Un point de terminaison OTLP (par exemple, New Relic ou Honeycomb)

Le tableau ci-dessous indique le type de données que vous pouvez envoyer à chaque destination :

Azure Monitor Application Insights (Outil de surveillance des applications)

La chaîne de connexion est la seule information de configuration requise d’Application Insights. Une fois que vous disposez de la chaîne de connexion, vous pouvez configurer l’agent au moyen du modèle ARM de votre application conteneur, avec des commandes Azure CLI ou Terraform.

La chaîne de connexion contient une clé d’instrumentation, un identificateur unique utilisé pour associer la télémétrie à une ressource Application Insights spécifique. Les clés d’instrumentation ne sont pas des jetons de sécurité ni des clés de sécurité, et elles ne sont pas considérées comme des secrets.

Si vous souhaitez protéger votre ressource Application Insights contre une mauvaise utilisation, consultez l’authentification Microsoft Entra pour Application Insights. Toutefois, la ressource Application Insights doit autoriser l’authentification locale à recevoir des données de l’agent de données OpenTelemetry.

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

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

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

Vous n’avez pas besoin d’exécuter l’agent Datadog dans votre application conteneur si vous activez l’agent OpenTelemetry managé pour votre environnement.

La configuration de l’agent OpenTelemetry nécessite une valeur pour site et key depuis votre instance Datadog. Collectez ces valeurs à partir de votre instance Datadog en fonction du tableau suivant :

Si vous avez créé votre instance Datadog dans le portail Azure, consultez les clés API pour plus d’informations.

Une fois que vous avez ces informations de configuration, vous pouvez configurer l’agent à partir du modèle ARM ou Bicep de votre application conteneur, ou avec les commandes Azure CLI.

Évitez de spécifier la valeur d’un secret, par exemple votre clé API Datadog, directement dans un environnement de production. Utilisez plutôt une référence à un secret stocké dans Azure Key Vault.

Vous devez activer le coffre de clés pour le déploiement de modèle. Pour activer le déploiement du modèle, créez le coffre de clés avec la propriété enabledForTemplateDeployment activée ou exécutez la commande Azure CLI suivante, en remplaçant la valeur <KEY_VAULT_NAME> par :

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

Pour plus d'informations, consultez les pages suivantes :

• Utiliser Azure Key Vault pour passer une valeur de paramètre sécurisée pendant le déploiement
• Tutoriel : Intégrer Azure Key Vault dans votre déploiement de modèle ARM

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

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

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

using '<BICEP_TEMPLATE_FILE>'

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

@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'
        ]
      }
    }
  }
}

az deployment group create \
  --resource-group <RESOURCE_GROUP> \
  --template-file <BICEP_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

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

Point de terminaison OTLP

Un point de terminaison OTLP (OpenTelemetry Protocol) est une destination de données de télémétrie qui consomme des données OpenTelemetry. Dans la configuration de votre application, vous pouvez ajouter plusieurs points de terminaison OTLP. L’exemple ci-dessous ajoute deux points de terminaison et envoie les données suivantes à ces points de terminaison.

Bien que vous puissiez configurer autant de points de terminaison OTLP que vous le souhaitez, chaque point de terminaison doit avoir un nom distinct.

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

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

Configurer les destinations des données

Pour configurer un agent, utilisez le tableau destinations pour définir les agents auxquels votre application envoie des données. Les clés valides sont appInsights, dataDog ou le nom de votre point de terminaison OTLP personnalisé. Vous pouvez contrôler le comportement d’un agent en fonction des options liées au type de données et au point de terminaison.

Par type de données

Par point de terminaison

• Vous ne pouvez configurer qu’un seul point de terminaison Application Insights et Datadog à la fois.
• Bien que vous puissiez définir plusieurs points de terminaison OTLP, chacun d’eux doit avoir un nom distinct.

L’exemple de modèle ARM suivant montre comment utiliser un point de terminaison OTLP nommé customDashboard. Il envoie :

• les traces à App Insights et à customDashboard
• les journaux à App Insights et à customDashboard
• les métriques à Datadog et à customDashboard

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

Exporter les signaux OpenTelemetry des composants système

À partir de la version 2024-08-02-previewde l’API OpenTelemetry, vous pouvez configurer votre environnement d’application conteneur pour exporter les signaux OpenTelemetry des composants système vers vos destinations de données.

Utilisez la configuration suivante pour exporter les traces Dapr et les métriques KEDA.

Traces Dapr

L’exemple de modèle ARM suivant montre comment exporter des traces Dapr vers vos destinations de traces.

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

Pour en savoir plus sur l’utilisation de Dapr dans les applications conteneur, consultez La vue d’ensemble de Dapr.

Métriques KEDA

L’exemple de modèle ARM suivant montre comment exporter des métriques KEDA vers vos destinations de métriques.

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

Pour en savoir plus sur la prise en charge de KEDA dans Container Apps, consultez Définir des règles de mise à l’échelle.

Exemple Configuration d’OpenTelemetry

L’exemple de modèle suivant montre comment configurer votre application conteneur pour collecter des données de télémétrie avec Azure Monitor Application Insights, Datadog et avec un agent OTLP personnalisé nommé customDashboard.

Cet exemple fonctionne avec le fichier de paramètres utilisé pour récupérer la clé API Datadog à partir d’un coffre de clés Azure.

Avant de déployer ce modèle, remplacez les <PLACEHOLDERS> par vos valeurs.

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

@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'
        ]
      }
    }
  }
}

Pour plus d’informations, consultez Microsoft.App/managedEnvironments.

Résilience des données

En cas d'interruption de messagerie vers un point de terminaison, l'agent OpenTelemetry utilise la procédure suivante pour prendre en charge la résilience des données :

• Mise en mémoire tampon et tentatives réitérées : l’agent conserve les données en mémoire et continue d'effectuer des tentatives (avec atténuation) pendant une durée maximale de cinq minutes.
• Suppression des données : si la file d'attente mise en mémoire tampon est pleine ou si le point de terminaison est toujours en panne après de nouvelles tentatives, l'agent supprime les lots les plus anciens pour éviter de manquer de mémoire.

Variables d'environnement

L’agent OpenTelemetry injecte automatiquement un ensemble de variables d’environnement dans votre application au moment de l’exécution.

Les deux premières variables d’environnement suivent la configuration standard de l’exportateur OpenTelemetry et sont utilisées dans les kits de développement logiciel standard OTLP. Si vous définissez explicitement la variable d’environnement dans la spécification de l’application conteneur, votre valeur remplace la valeur injectée automatiquement.

En savoir plus sur la configuration de l’exportateur OTLP, consultez la configuration de l’exportateur OTLP.

Les trois autres variables d’environnement sont spécifiques à Azure Container Apps et sont toujours injectées. Ces variables contiennent les URL des points de terminaison de l’agent pour chaque type de données spécifique (journaux, métriques, traces).

Ces variables ne sont nécessaires que si vous utilisez l’agent OpenTelemetry managé et un autre agent OpenTelemetry. L’utilisation de ces variables vous permet de contrôler l’acheminement des données entre les différents agents OpenTelemetry.

Coûts de l’agent OpenTelemetry

L’agent OpenTelemetry géré s’exécute sans coût de calcul supplémentaire pour vous. Microsoft provisionne et gère l’infrastructure de l’agent dans votre environnement Container Apps.

Toutefois, vous êtes responsable des frais appliqués par les services de destination où vous envoyez vos données de télémétrie. Consultez le service de destination pour connaître la structure et les conditions de facturation correspondantes. Par exemple, si vous envoyez des données à Azure Monitor Application Insights et à Datadog, vous êtes redevable des frais appliqués par les deux services.

Allocation de ressources de l’agent

L’agent OpenTelemetry managé est approvisionné avec les ressources fixes suivantes :

• CPU : 0,5 cœurs vCPU
• Mémoire : 1,5 Go de RAM
• Réplicas : réplica unique (non configurable)

Ces ressources sont gérées par Microsoft et n’apparaissent pas dans vos métriques de facturation ou de consommation de ressources.

Limitations connues

• Les données système, telles que les journaux système ou les métriques standard Container Apps, ne sont pas envoyées à l’agent OpenTelemetry.
• Le point de terminaison Application Insights n’accepte pas les métriques.
• Les paramètres de configuration se trouvent au niveau de l’environnement. Vous pouvez envoyer différents types de données à différentes destinations, mais vous ne pouvez pas fractionner vos données par application. Par exemple, dans la même application, vous pouvez envoyer des métriques à Datadog et des traces à App Insights.
• L’agent managé prend uniquement en charge le protocole de transport gRPC pour les données de télémétrie.
• L’agent OpenTelemetry managé s’exécute en tant qu’instance unique et ne peut pas être mis à l’échelle ni configuré pour garantir une haute disponibilité.
• Les métriques d’état et d’intégrité de l’agent ne sont actuellement pas exposées dans le portail Azure ou par le biais d’API de surveillance.
• Les secrets (tels que les clés API) doivent être spécifiés directement dans les modèles : l’intégration d’Azure Key Vault pour la configuration de l’agent n’est actuellement pas prise en charge.

Questions fréquentes

• Dois-je référencer le Kit de développement logiciel (SDK) OpenTelemetry dans mon code ?

  Oui. Le Kit de développement logiciel (SDK) crée des données de télémétrie et l’agent managé est uniquement responsable de l’acheminement des données.

• Pourquoi la list commande retourne-t-elle null ?

  Lorsque vous exécutez az containerapp env telemetry otlp list, la réponse est null quand la valeur est un jeton sensible qui a besoin de protection.

• Est-ce que je suis facturé pour les ressources de calcul de l’agent OpenTelemetry ?

  Non. Microsoft provisionne et gère l’infrastructure de l’agent sans coût de calcul supplémentaire. Vous êtes facturé uniquement pour les services de destination qui reçoivent vos données de télémétrie.

• Puis-je mettre à l’échelle l’agent OpenTelemetry ou exécuter plusieurs réplicas ?

  Non. L’agent managé s’exécute actuellement en tant que réplica unique avec allocation de ressources fixe (0,5 PROCESSEUR, 1,5 Go de RAM). Les configurations de haute disponibilité ne sont actuellement pas prises en charge.

• Comment puis-je surveiller la santé et l’état de l’agent OpenTelemetry ?

  L’état de l’agent et les métriques de santé ne sont pas actuellement exposés. Cette capacité est prévue pour une version ultérieure.

Étapes suivantes