Compartilhar via

Coletar e ler dados do OpenTelemetry em Aplicativos de Contêiner do Azure (versão prévia)

  • Artigo

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 ponto de extremidade compatível com o protocolo 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 meio de um modelo do ARM ou chamadas Bicep para o ambiente ou por meio da CLI ou por meio do Terraform (por meio 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 gerenciado do OpenTelemetry para seu ambiente não significa automaticamente que o agente coleta dados. Os agentes só enviam dados com base nas configurações e instrumentando o 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, 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:

Destino Logs Métricas Rastreamentos
Azure App Insights Sim Não Sim
Datadog Não Sim Yes
Ponto de extremidade configurado pelo protocolo OTLP Sim Sim Yes

O Application Insights do Azure Monitor

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.

Para implantar esse modelo, substitua os espaços reservados entre <> pelos 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 da sua instância do Datadog. Colete esses valores da sua instância do Datadog de acordo com esta tabela:

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

Com os detalhes da configuração, você pode definir o agente usando o modelo ARM 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 implantação de modelo. Para fazer isso, crie o cofre de chaves com a propriedade enabledForTemplateDeployment habilitada 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 saber mais, veja:

Crie um arquivo de parâmetro para recuperar sua chave de API Datadog de um Azure Key Vault.

Antes de implantar os arquivos a seguir, substitua os espaços reservados cercados por <> com 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 referenciar o parâmetro datadogapikey no modelo do 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 <> com 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 OTLP (protocolo OpenTelemetry) é um destino de dados de telemetria que consome dados do OpenTelemetry. Na configuração do aplicativo, você pode adicionar vários pontos de extremidade OTLP. O exemplo a seguir adiciona dois pontos de extremidade e envia os dados a seguir a esses pontos de extremidade.

Nome do ponto de extremidade Dados enviados para o ponto de extremidade
oltp1 Métricas e/ou rastreamentos
oltp2 Logs e/ou rastreamentos

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

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 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.
Habilitar ou desabilitar qualquer tipo de dados. Você pode optar por enviar apenas rastreamentos e nenhum outro dado.
Enviar um tipo de dados para vários pontos de extremidade. Você pode enviar logs para o DataDog e um ponto de extremidade configurado por OTLP.
Enviar tipos de dados diferentes para locais diferentes. Você pode enviar rastreamentos para um ponto de extremidade OTLP e métricas para o DataDog.
Desabilitar o envio de todos os tipos de dados. Você pode optar por não enviar dados por meio do agente do OpenTelemetry.

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

Exemplo de configuração do 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, 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 os espaços reservados entre <> 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"
        ]
      }
    }
  }
}

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

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.

Nome Descrição
OTEL_EXPORTER_OTLP_ENDPOINT Uma URL de ponto de extremidade base de qualquer tipo de sinal, com um número de porta opcionalmente especificado. 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 só dá suporte a grpc. Valor: grpc.

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 URLs de ponto de extremidade do agente de cada tipo de dados específico (logs, métricas e rastreamentos).

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.

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

Custos do agente do OpenTelemetry

Você é cobrado pela computação subjacente do agente.

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.

Limitações conhecidas

  • Os agentes do OpenTelemetry estão na versão prévia.
  • 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.
  • O ponto de extremidade do Datadog não aceita logs.

Próximas etapas

Saiba mais sobre monitoramento e integridade