Coletar e ler dados do OpenTelemetry nos Aplicativos de Contêiner do Azure

Usando um agente de dados do OpenTelemetry com o ambiente de Aplicativos de Contêiner do Azure, você pode optar por enviar dados de observabilidade em um formato OpenTelemetry:

• Como canalizar dados de um agente para um ponto de extremidade desejado. As opções de destino incluem o Application Insights do Azure Monitor, o Datadog e qualquer destino compatível com o protocolo OpenTelemetry (OTLP).

• Alterar facilmente os pontos de extremidade de destino sem precisar reconfigurar como eles emitem dados e sem precisar executar manualmente um agente do OpenTelemetry.

Esse artigo mostra como instalar e configurar um agente do OpenTelemetry para seu aplicativo de contêiner.

Configurar um agente do OpenTelemetry

Os agentes do OpenTelemetry residem em seu ambiente de aplicativo de contêiner. Você define as configurações do agente por um modelo do ARM ou chamadas Bicep para o ambiente ou pela CLI ou pelo Terraform (pelo provedor AzAPI).

Cada tipo de ponto de extremidade (Azure Monitor Application Insights, DataDog e OTLP) tem requisitos de configuração específicos.

Pré-requisitos

Habilitar o agente OpenTelemetry gerenciado para seu ambiente não significa automaticamente que o agente coleta dados. Os agentes só enviam dados com base nas suas configurações e na instrumentação correta do seu código.

Configurar código-fonte

Prepare seu aplicativo para coletar dados instalando o SDK do OpenTelemetry e siga as diretrizes do OpenTelemetry para instrumentar métricas, logsou rastreamentos.

Inicializar pontos de extremidade

Para enviar dados para um destino de coleção, primeiro você precisa criar uma instância do serviço de destino. Por exemplo, para enviar dados para o Azure Monitor Application Insights, precisará criar uma instância do Application Insights antecipadamente.

O agente gerenciado do OpenTelemetry aceita os seguintes destinos:

• Azure Monitor Application Insights
• Datadog
• Qualquer ponto de extremidade OTLP (por exemplo: New Relic ou Honeycomb).

A tabela a seguir mostra os tipos de dados você pode enviar para cada destino:

Azure Monitor Application Insights

O único detalhe de configuração necessário do Application Insights é a cadeia de conexão. Depois de ter a cadeia de conexão, você poderá configurar o agente por meio do modelo ARM do aplicativo de contêiner, com comandos da CLI do Azure ou Terraform.

A cadeia de conexão contém uma chave de instrumentação, que é um identificador exclusivo usado para associar a telemetria a um recurso específico do Application Insights. Chaves de instrumentação não são tokens de segurança ou chaves de segurança e não são consideradas segredos.

Se você quiser proteger seu recurso do Application Insights contra uso indevido, confira Autenticação do Microsoft Entra para Application Insights. No entanto, o recurso do Application Insights precisa permitir a autenticação local para receber dados do agente de dados 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

Você não precisará executar o agente Datadog em seu aplicativo de contêiner se habilitar o agente OpenTelemetry gerenciado para seu ambiente.

A configuração do agente OpenTelemetry exige um valor para site e key da sua instância do Datadog. Colete esses valores da sua instância do Datadog de acordo com esta tabela:

Se você criou sua instância do Datadog no portal do Azure, consulte as chaves de API para obter mais informações.

Com os detalhes da configuração, você pode definir o agente usando o modelo ARM ou Bicep do aplicativo de contêiner ou com comandos da CLI do Azure.

Evite especificar o valor de um segredo, como sua chave de API Datadog, diretamente em um ambiente de produção. Em vez disso, use uma referência a um segredo armazenado no Azure Key Vault.

Você deve habilitar o cofre de chaves para a implantação do modelo. Para habilitar a implantação de modelo, crie o cofre de chaves com a enabledForTemplateDeployment propriedade habilitada ou execute o seguinte comando da CLI do Azure, substituindo <KEY_VAULT_NAME> pelo seu valor.

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

Para saber mais, veja:

• Usar o Azure Key Vault para passar um valor de parâmetro seguro durante a implantação
• Tutorial: Integrar o Azure Key Vault em sua implantação de modelo do 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"]
        }
      }
    }
  })
}

Ponto de extremidade OTLP

Um endpoint do protocolo OpenTelemetry (OTLP) é um destino de dados de telemetria que processa dados do OpenTelemetry. Na configuração do aplicativo, você pode adicionar vários endpoints OTLP. O exemplo a seguir adiciona dois pontos de extremidade e envia os dados a seguir a esses pontos de extremidade.

Embora você possa configurar quantos pontos de extremidade configurados por OTLP desejar, cada ponto de extremidade deve ter um nome distinto.

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

Configurar destinos dos dados

Para configurar um agente, use a matriz destinations para definir para quais agentes seu aplicativo envia dados. As chaves válidas são appInsights,dataDog ou o nome do ponto de extremidade OTLP personalizado. Você pode controlar como um agente se comporta com base no tipo de dados e nas opções relacionadas ao endpoint.

Por tipo de dados

Por ponto de extremidade

• Você só pode configurar um ponto de extremidade do Application Insights e do Datadog de cada vez.
• Embora você possa definir mais de um ponto de extremidade configurado por OTLP, cada um deve ter um nome distinto.

O modelo ARM de exemplo a seguir mostra como usar um ponto de extremidade OTLP chamado customDashboard. Ele envia:

• rastreamentos para insights do aplicativo e customDashboard;
• logs para insights do aplicativo e customDashboard;
• métricas para DataDog e customDashboard

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

Exportar sinais OpenTelemetry dos componentes do sistema

Na versão 2024-08-02-preview da API OpenTelemetry, você pode configurar seu ambiente de aplicativo de contêiner para exportar os sinais OpenTelemetry dos componentes do sistema para seus destinos dos dados.

Use a configuração a seguir para exportar rastreamentos de Dapr e métricas KEDA.

Rastreamentos do Dapr

O modelo do ARM de exemplo a seguir mostra como exportar Rastreamentos do Dapr para seus destinos de rastreamento.

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

Para saber mais sobre como usar o Dapr em aplicativos de contêiner, consulte a Visão geral do Dapr.

Métricas KEDA

O modelo arm de exemplo a seguir mostra como exportar métricas KEDA para seus destinos de métricas.

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

Para saber mais sobre o suporte à KEDA em Aplicativos de Contêiner, consulte Definir regras de dimensionamento.

Exemplo de configuração do OpenTelemetry

O modelo de exemplo a seguir mostra como você pode configurar seu aplicativo de contêiner para coletar dados de telemetria usando o Azure Monitor Application Insights, o Datadog e com um agente OTLP personalizado chamado customDashboard.

Este exemplo funciona com o arquivo de parâmetro usado para recuperar a chave de API Datadog de um Azure Key Vault.

Para implantar esse modelo, substitua o <PLACEHOLDERS> pelos seus valores.

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

Para obter mais informações, consulte Microsoft.App/managedEnvironments.

Resiliência de dados

No caso de uma interrupção de mensagens para um ponto de extremidade, o agente OpenTelemetry usa o seguinte procedimento para dar suporte à resiliência de dados:

• Buffer na memória e novas tentativas: o agente mantém os dados na memória e continua tentando novamente (com retirada) por até cinco minutos.
• Descartando dados: se a fila em buffer for preenchida ou o ponto de extremidade ainda estiver inoperante após novas tentativas, o agente descartará os lotes mais antigos para evitar ficar sem memória.

Variáveis de ambiente

O agente do OpenTelemetry injeta automaticamente um conjunto de variáveis de ambiente em seu aplicativo em runtime.

As duas primeiras variáveis de ambiente seguem a configuração padrão do exportador do OpenTelemetry e são usadas em kits de desenvolvimento de software padrão OTLP. Se você definir explicitamente a variável de ambiente na especificação do aplicativo de contêiner, seu valor substituirá o valor injetado automaticamente.

Saiba mais sobre a configuração do exportador do OTLP, confira Configuração do exportador do OTLP.

As outras três variáveis de ambiente são específicas para Aplicativos de Contêiner do Azure e são sempre injetadas. Essas variáveis contêm as URLs do endpoint do agente para cada tipo específico de dados (logs, métricas e rastros).

Essas variáveis só serão necessárias se você estiver usando o agente gerenciado do OpenTelemetry e outro agente do OpenTelemetry. Usar essas variáveis fornece controle sobre o roteamento dos dados entre os diferentes agentes do OpenTelemetry.

Custos do agente do OpenTelemetry

O agente OpenTelemetry gerenciado é executado sem custo de computação adicional para você. A Microsoft provisiona e gerencia a infraestrutura do agente em seu ambiente de Aplicativos de Contêiner.

No entanto, você é responsável pelos encargos aplicados pelos serviços de destino nos quais envia seus dados de telemetria. Consulte o serviço de destino para obter a estrutura de cobrança e os termos. Por exemplo, se você enviar dados para o Azure Monitor Application Insights e o Datadog, será responsável pelos encargos aplicados por ambos os serviços.

Alocação de recursos do agente

O agente OpenTelemetry gerenciado é provisionado com os seguintes recursos fixos:

• CPU: 0,5 núcleos de vCPU
• Memória: 1,5 GB de RAM
• Réplicas: réplica única (não configurável)

Esses recursos são gerenciados pela Microsoft e não aparecem nas métricas de cobrança ou consumo de recursos.

Limitações conhecidas

• Os dados do sistema, como logs do sistema ou métricas padrão de Aplicativos de Contêiner, não estão disponíveis para serem enviados ao agente do OpenTelemetry.
• O ponto de extremidade do Application Insights não aceita métricas.
• As configurações residem no nível do ambiente. Você pode enviar diferentes tipos de dados para destinos diferentes, mas não pode dividir seus dados por aplicativo. Por exemplo, no mesmo aplicativo, você pode enviar métricas para o Datadog e rastreamentos para o App Insights.
• O agente gerenciado dá suporte apenas ao protocolo de transporte gRPC para dados de telemetria.
• O agente OpenTelemetry gerenciado é executado como uma única réplica e não pode ser dimensionado ou configurado para alta disponibilidade.
• No momento, as métricas de status e integridade do agente não são expostas no portal do Azure ou por meio de APIs de monitoramento.
• Segredos (como chaves de API) devem ser especificados diretamente em modelos – a integração do Azure Key Vault para a configuração do agente não tem suporte no momento.

Perguntas frequentes

• Preciso fazer referência ao SDK do OpenTelemetry no meu código?

  Sim. O SDK cria dados de telemetria e o agente gerenciado é responsável apenas por rotear dados.

• Por que o list comando retorna nulo?

  Quando você executa az containerapp env telemetry otlp list, a resposta é null quando o valor é um token confidencial que precisa de proteção.

• Sou cobrado pelos recursos de computação do agente OpenTelemetry?

  Não. A Microsoft provisiona e gerencia a infraestrutura do agente sem custo de computação adicional. Você só é cobrado pelos serviços de destino que recebem os seus dados de telemetria.

• Posso dimensionar o agente OpenTelemetry ou executar várias réplicas?

  Não. Atualmente, o agente gerenciado é executado como uma única réplica com alocação de recursos fixa (CPU 0,5, 1,5 GB de RAM). No momento, não há suporte para configurações de alta disponibilidade.

• Como posso monitorar a saúde e o status do agente OpenTelemetry?

  As métricas de integridade e status do agente não estão expostas no momento. Essa funcionalidade está planejada para uma versão futura.

Próximas etapas