Partilhar via

Coletar e ler dados OpenTelemetry em Aplicativos de Contêiner do Azure (visualização)

  • Artigo

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

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

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

Este artigo mostra como configurar um agente OpenTelemetry para seu aplicativo de contêiner.

Configurar um agente OpenTelemetry

Os agentes OpenTelemetry vivem em seu ambiente de aplicativo de contêiner. Você define as configurações do agente por meio de um modelo ARM ou chamadas Bicep para o ambiente, ou através da CLI ou através do Terraform (através do 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 em seu ambiente não significa automaticamente que o agente coleta dados. Os agentes apenas enviam dados com base nas suas definições de configuração e instrumentam o seu código corretamente.

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, logs ou rastreamentos.

Inicializar pontos de extremidade

Antes de enviar dados para um destino de coleta, primeiro você precisa criar uma instância do serviço de destino. Por exemplo, se você quiser enviar dados para o Azure Monitor Application Insights, precisará criar uma instância do Application Insights com antecedência.

O agente OpenTelemetry gerenciado 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 que tipo de dados você pode enviar para cada destino:

Destino Registos Métricas Rastreios
Azure App Insights Sim No Sim
Datadog Não Sim Sim
Ponto de extremidade configurado para o protocolo OpenTelemetry (OTLP) Sim Sim Sim

Azure Monitor Application Insights

O único detalhe de configuração exigido do Application Insights é a cadeia de conexão. Depois de ter a cadeia de conexão, você pode configurar o agente por meio do modelo ARM do seu 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 telemetria a um recurso específico do Application Insights. As 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, consulte Autenticação do Microsoft Entra para Application Insights.

Antes de implantar esse modelo, substitua os espaços reservados cercados por <> seus valores.

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

Datadog

A configuração do agente Datadog requer um valor para site e key de sua instância Datadog. Reúna esses valores de sua instância Datadog de acordo com esta tabela:

Propriedade do agente Datadog Propriedade de configuração de Aplicativos de Contêiner
DD_SITE site
DD_API_KEY key

Depois de ter esses detalhes de configuração, você pode configurar o agente por meio do modelo ARM do aplicativo contêiner ou com os 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 Cofre de Chaves do Azure.

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

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

Para obter mais informações, consulte:

Crie um arquivo de parâmetro para recuperar sua chave de API Datadog de um Cofre de Chaves do Azure.

Antes de implantar os arquivos a seguir, substitua os espaços reservados cercados por <> seus valores.

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

Agora você pode fazer referência ao datadogapikey parâmetro em seu modelo ARM.

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

Para implantar o recurso, execute o seguinte comando da CLI do Azure, substituindo os espaços reservados cercados por <> seus valores.

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

Ponto de extremidade OTLP

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

Nome do ponto final Dados enviados para o endpoint
oltp1 Métricas e/ou rastreamentos
oltp2 Registos e/ou vestígios

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"]
      }
    }
  }
}
Nome Descrição
resource-group o nome do grupo de recursos. Você pode configurar o grupo padrão usando az configure --defaults group=<NAME>.
name Nome do ambiente Container Apps.
otlp-name Um nome que você seleciona para identificar seu ponto de extremidade configurado para OTLP.
endpoint A URL do destino que recebe os dados coletados.
insecure Padrão true. Define se a segurança de transporte do cliente deve ser habilitada para a conexão gRPC do exportador. Se false, o headers parâmetro é necessário.
headers Valores separados por espaço, no formato 'key=value', que fornece as informações necessárias para a segurança dos pontos de extremidade OTLP. Exemplo: "api-key=key other-config-value=value".

Configurar destinos de dados

Para configurar um agente, use a destinations matriz para definir quais agentes seu aplicativo envia dados. As chaves válidas são appInsights, dataDogou o nome do seu 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 ponto de extremidade.

Por tipo de dados

Opção Exemplo
Selecione um tipo de dados. Você pode configurar logs, métricas e/ou rastreamentos individualmente.
Habilite ou desabilite qualquer tipo de dados. Você pode optar por enviar apenas rastreamentos e nenhum outro dado.
Envie um tipo de dados para vários pontos de extremidade. Você pode enviar logs para o DataDog e para um ponto de extremidade configurado para OTLP.
Envie diferentes tipos de dados para diferentes locais. Você pode enviar rastreamentos para um ponto de extremidade OTLP e métricas para o DataDog.
Desative o envio de todos os tipos de dados. Você pode optar por não enviar nenhum dado através do agente OpenTelemetria.

Por ponto final

  • 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 para OTLP, cada um deve ter um nome distinto.

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

  • rastreios para insights de aplicativos 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"
        ]
      }
    }
  }
}

Exemplo de configuração OpenTelemetry

O modelo ARM 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, Datadog e com um agente OTLP personalizado chamado customDashboard.

Este exemplo funciona com o arquivo de parâmetro usado para recuperar a chave da API Datadog de um Cofre de Chaves do Azure.

Antes de implantar esse modelo, substitua os espaços reservados cercados por <> 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"
        ]
      }
    }
  }
}

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

Variáveis de ambiente

O agente OpenTelemetry injeta automaticamente um conjunto de variáveis de ambiente em seu aplicativo em tempo de execução.

As duas primeiras variáveis de ambiente seguem a configuração padrão do exportador 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 OTLP, consulte Configuração do exportador OTLP.

Nome Descrição
OTEL_EXPORTER_OTLP_ENDPOINT Um URL de ponto final base para qualquer tipo de sinal, com um número de porta especificado opcionalmente. Essa configuração é útil quando você está enviando mais de um sinal para o mesmo ponto de extremidade e deseja que uma variável de ambiente controle o ponto de extremidade. Exemplo: http://otel.service.k8se-apps:4317/
OTEL_EXPORTER_OTLP_PROTOCOL Especifica o protocolo de transporte OTLP usado para todos os dados de telemetria. O agente gerenciado suporta grpcapenas o . Valor: grpc.

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

Essas variáveis só são necessárias se você estiver usando o agente OpenTelemetry gerenciado e outro agente OpenTelemetry . O uso dessas variáveis oferece controle sobre como rotear dados entre os diferentes agentes OpenTelemetria.

Nome Descrição Exemplo
CONTAINERAPP_OTEL_TRACING_GRPC_ENDPOINT URL do ponto de extremidade apenas para dados de rastreamento. http://otel.service.k8se-apps:43178/v1/traces/
CONTAINERAPP_OTEL_LOGGING_GRPC_ENDPOINT URL do ponto de extremidade apenas para dados de log. http://otel.service.k8se-apps:43178/v1/logs/
CONTAINERAPP_OTEL_METRIC_GRPC_ENDPOINT URL do ponto de extremidade apenas para dados métricos. http://otel.service.k8se-apps:43178/v1/metrics/

Custos do agente OpenTelemetry

Você é cobrado pelo cálculo subjacente do agente.

Consulte o serviço de destino para conhecer a estrutura e os termos de faturamento. Por exemplo, se você enviar dados para o Azure Monitor Application Insights e para o Datadog, será responsável pelas cobranças aplicadas por ambos os serviços.

Limitações conhecidas

  • Os agentes OpenTelemetry estão em visualização.
  • Os dados do sistema, como logs do sistema ou métricas padrão dos Aplicativos de Contêiner, não estão disponíveis para serem enviados ao agente OpenTelemetry .
  • O ponto de extremidade do Application Insights não aceita métricas.
  • O ponto de extremidade Datadog não aceita logs.

Próximos passos

Saiba mais sobre monitoramento e integridade