View a markdown version of this page

Coletor do OpenTelemetry - Amazon CloudWatch
Receptores compatíveisIntroduçãoAutenticar com um token de portador (chave de API)Exemplos de configuração do coletor

Coletor do OpenTelemetry

O OpenTelemetry Collector é um agente de código aberto, independente de fornecedor, que recebe, processa e exporta dados de telemetria. Ele atua como um pipeline central entre suas aplicações e o Amazon CloudWatch, coletando métricas, logs e rastreamentos de várias fontes e enviando-os para o CloudWatch usando o OpenTelemetry Protocol (OTLP).

Usar o OpenTelemetry Collector com o CloudWatch oferece os seguintes benefícios:

  • Colete telemetria de várias aplicações e hosts por meio de um único agente, reduzindo o número de conexões com o CloudWatch.

  • Processe e filtre a telemetria antes de enviá-la ao CloudWatch, incluindo adicionar ou remover atributos, agrupar dados em lotes e rastrear amostras.

  • Use a mesma configuração de coletor em ambientes on-premises, da AWS e outros de nuvem, fornecendo um pipeline de telemetria consistente, independentemente de onde suas aplicações sejam executadas.

  • Envie métricas para o CloudWatch com rótulos ricos que estão disponíveis para consulta usando ao Prometheus Query Language (PromQL) no CloudWatch Query Studio.

Receptores compatíveis

O OpenTelemetry Collector é compatível com uma ampla variedade de receptores para ingestão de dados de telemetria. Você pode usar receptores do OpenTelemetry, como o receptor do OTLP, para aplicações instrumentadas com OpenTelemetry SDKs, ou receptores do Prometheus, para extrair métricas de exportadores existentes do Prometheus. Os receptores comuns do Prometheus usados com o CloudWatch incluem:

  • Receptor do Prometheus, para extrair qualquer endpoint compatível com o Prometheus

  • Receptor de métricas do host, para coletar métricas em nível de sistema do host

  • Receptor de clusters do Kubernetes, para coletar métricas em nível de cluster do servidor da API do Kubernetes

Você pode configurar vários receptores em um único coletor, o que permite coletar as métricas do OpenTelemetry e do Prometheus e enviá-las ao CloudWatch por meio do mesmo pipeline. Para ver a lista completa dos receptores disponíveis, consulte o repositório do OpenTelemetry Collector.

Introdução

Pré-requisito: se for usar o endpoint do OTLP para rastreamento, certifique-se de que a Pesquisa de transações esteja habilitada.

Etapas:

  1. Faça o download da versão mais recente da distribuição do OpenTelemetry Collector. Para obter mais informações, consulte as versões do OpenTelemetry Collector.

  2. Instale o OpenTelemetry Collector no seu host. O coletor é executado em qualquer plataforma e sistema operacional. Para obter mais informações, consulte Install the Collector.

  3. Configure as credenciais da AWS no host do Amazon EC2 ou on-premises. O coletor usa essas credenciais para se autenticar com o CloudWatch ao enviar dados de telemetria. Consulte abaixo para obter detalhes.

    Setup IAM permissions for Amazon EC2
    Siga o procedimento abaixo para anexar a política CloudWatchAgentServerPolicy do IAM ao perfil do IAM da instância do Amazon EC2.

    1. Abra o console do IAM em https://console.aws.amazon.com/iam/.

    2. Escolha Perfis e localize e selecione o perfil usado pela instância do Amazon EC2.

    3. Na guia Permissões, escolha Adicionar permissões e Anexar políticas.

    4. Usando a caixa de pesquisa, pesquise a política CloudWatchAgentServerPolicy.

    5. Selecione a política CloudWatchAgentServerPolicy e escolha Adicionar permissões.

    Setup IAM permissions for on-premise hosts
    Você pode criar o usuário do IAM a ser usado para fornecer permissões aos hosts on-premises.

    1. Abra o console do IAM em https://console.aws.amazon.com/iam/.

    2. Escolha Usuários, Criar usuário.

    3. Em Detalhes do usuário, em Nome do usuário, insira um nome para o novo usuário do IAM. Esse é o nome de login para a AWS que será usado para autenticar seu host.

    4. Escolha Próximo.

    5. Na página Definir permissões, em Opções de permissões, escolha Anexar políticas diretamente.

    6. Na lista de Políticas de permissões, selecione a política CloudWatchAgentServerPolicy para adicionar ao seu usuário.

    7. Escolha Próximo.

    8. Na página Revisar e criar, certifique-se de que você está satisfeito com o nome de usuário e que a política CloudWatchAgentServerPolicy está no Resumo de permissões.

    9. Selecione Criar usuário.

    10. Crie e recupere a chave secreta e a chave de acesso da AWS: no painel de navegação do console do IAM, escolha Usuários e depois selecione o nome do usuário do usuário que você criou na etapa anterior.

    11. Na página do usuário, escolha a guia Credenciais de segurança.

    12. Na seção Chaves de acesso, escolha Criar chave de acesso.

    13. Em Criar chave de acesso: etapa 1, escolha Command Line Interface (CLI).

    14. Em Criar chave de acesso: etapa 2, insira uma tag opcional e escolha Próximo.

    15. Em Criar chave de acesso: etapa 3, selecione Baixar arquivo .csv para salvar um arquivo .csv com a chave de acesso e a chave de acesso secreta do usuário do IAM. Você precisará dessas informações para as próximas etapas.

    16. Selecione Concluído.

    17. Configure suas credenciais da AWS no host on-premises ao inserir o comando a seguir. Substitua ACCESS_KEY_ID e SECRET_ACCESS_ID pela chave de acesso recém-gerada e pela chave de acesso secreta do arquivo .csv que você baixou na etapa anterior.

      
$ aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID
AWS Secret Access Key [None]: SECRET_ACCESS_ID
Default region name [None]: MY_REGION
Default output format [None]: json
    dica

    Para hosts on-premises que precisam apenas enviar métricas ou logs, você pode usar a autenticação de token do portador como uma alternativa mais simples à configuração de chaves de acesso da AWS. Os tokens do portador não exigem a etapa aws configure ou os arquivos de credenciais no host. Para obter mais informações, consulte Configurar autenticação do token do portador para Metrics.

  4. Configure as credenciais da AWS para os clusters do Amazon EKS ou do Kubernetes. A maneira mais fácil de começar a usar o Amazon EKS é usar o complemento EKS OTel Container Insights. Se preferir usar o OpenTelemetry Collector diretamente, siga o procedimento abaixo para configurar as credenciais da AWS para os clusters do Amazon EKS ou do Kubernetes para enviar telemetria para o CloudWatch.

    Setup IAM permissions for Amazon EKS

    1. Crie um provedor de identidade OIDC do IAM para o cluster com o comando a seguir. 

      eksctl utils associate-iam-oidc-provider --cluster ${CLUSTER_NAME} --region ${REGION} --approve

    2. Atribua perfis do IAM à conta de serviço do Kubernetes para o OTel Collector usando o comando a seguir.

      
eksctl create iamserviceaccount \
--name ${COLLECTOR_SERVICE_ACCOUNT}\
--namespace ${NAMESPACE} \
--cluster ${CLUSTER_NAME} \
--region ${REGION} \
--attach-policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy \
--approve \
--override-existing-serviceaccounts
    Setup IAM permissions for Kubernetes

    1. Configure suas credenciais da AWS no host on-premises ao inserir o comando a seguir. Substitua ACCESS_KEY_ID e SECRET_ACCESS_ID pela chave de acesso recém-gerada e pela chave de acesso secreta do arquivo .csv que você baixou na etapa anterior. Por padrão, o arquivo de credenciais é salvo em /home/user/.aws/credentials.

      
aws configure
AWS Access Key ID [None]: ACCESS_KEY_ID 
AWS Secret Access Key [None]: SECRET_ACCESS_ID 
Default region name [None]: MY_REGION 
Default output format [None]: json

    2. Edite o recurso OpenTelemetry Collector para adicionar o segredo de credenciais da AWS recém-criado usando o seguinte comando: kubectl edit OpenTelemetryCollector otel_collector

    3. Usando o editor de arquivos, inclua as credenciais da AWS no contêiner do OpenTelemetryCollector adicionando a configuração a seguir na parte superior da implantação. Substitua o caminho /home/user/.aws/credentials pelo local do seu arquivo local de credenciais da AWS. 

      
                     spec:
                    volumeMounts:
                    - mountPath: /rootfs
                    volumeMounts:
                    - name: aws-credentials
                    mountPath: /root/.aws
                    readOnly: true
                    volumes:
                    - hostPath:
                    path: /home/user/.aws/credentials
                    name: aws-credentials

  5. Configure o exportador do OTLP na configuração do coletor para enviar telemetria ao endpoint do CloudWatch. Veja exemplos abaixo.

Autenticar com um token de portador (chave de API)

Se você não precisar configurar credenciais da AWS no host — por exemplo, ao executar em outros provedores de nuvem, com infraestrutura fora da AWS ou em pipelines de CI/CD — você pode usar a autenticação de token do portador em vez do SigV4. Os tokens do portador são compatíveis com os endpoints de métricas e logs (chaves de API separadas são necessárias para cada serviço). A autenticação com o token do portador não é compatível com rastreamentos.

Consulte para obter instruções de configuração Configurar autenticação do token do portador para Metrics. Para logs, consulte Como configurar autenticação de token de portador para Logs.

Para ver um exemplo de configuração de coletor usando tokens de portador, consulte o exemplo de métricas de token de portador nos exemplos de configuração de coletor abaixo.

Exemplos de configuração do coletor

Copie e cole o conteúdo abaixo para configurar o coletor com o objetivo de enviar logs e rastreamentos ao endpoint do OTLP.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlphttp/logs:
    compression: gzip
    logs_endpoint: logs_otlp_endpoint
    headers: 
      x-aws-log-group: ency_log_group
      x-aws-log-stream: default
    auth:
      authenticator: sigv4auth/logs
      
  otlphttp/traces:
    compression: gzip
    traces_endpoint: traces_otlp_endpoint
    auth:
      authenticator: sigv4auth/traces

extensions:
  sigv4auth/logs:
    region: "region"
    service: "logs"
  sigv4auth/traces:
    region: "region"
    service: "xray"

service:
  telemetry:
  extensions: [sigv4auth/logs, sigv4auth/traces]
  pipelines:
    logs:
      receivers: [otlp]
      exporters: [otlphttp/logs]
    traces:
      receivers: [otlp]
      exporters: [otlphttp/traces]

Veja a seguir um exemplo de como enviar logs e rastreamentos usando sigv4 para us-east-1.

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlphttp/logs:
    compression: gzip
    logs_endpoint: https://logs.us-east-1.amazonaws.com/v1/logs
    headers: 
      x-aws-log-group: MyApplicationLogs
      x-aws-log-stream: default
    auth:
      authenticator: sigv4auth/logs
      
  otlphttp/traces:
    compression: gzip
    traces_endpoint: https://xray.us-east-1.amazonaws.com/v1/traces
    auth:
      authenticator: sigv4auth/traces

extensions:
  sigv4auth/logs:
    region: "us-east-1"
    service: "logs"
  sigv4auth/traces:
    region: "us-east-1"
    service: "xray"

service:
  telemetry:
  extensions: [sigv4auth/logs, sigv4auth/traces]
  pipelines:
    logs:
     receivers: [otlp]
      exporters: [otlphttp/logs]
    traces:
      receivers: [otlp]
      exporters: [otlphttp/traces]
nota

Configure os SDKs do OpenTelemetry com uma configuração de amostragem always_on para registrar de forma confiável 100% de extensões e obter visibilidade total das aplicações críticas com o CloudWatch Application Signals. Para obter mais informações, consulte um exemplo de configuração do sampler do SDK Java do OpenTelemetry. Para obter um exemplo sobre como configurar o OpenTelemetry Collector com o endpoint do OTLP do X-Ray, consulte o repositório de demonstração de sinais de aplicações.

Copie e cole o conteúdo abaixo para configurar o coletor com o objetivo de enviar métricas para endpoints do OTLP.

receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:4318"

processors:
  batch:
    send_batch_size: 200
    timeout: 10s

exporters:
  otlphttp:
    tls:
      insecure: false
    endpoint: metrics_otlp_endpoint
    auth:
      authenticator: sigv4auth

extensions:
  sigv4auth:
    service: "monitoring"
    region: "region"

service:
  extensions: [sigv4auth]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

Confira a seguir um exemplo de como enviar métricas usando sigv4 para us-east-1.

receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:4318"

processors:
  batch:
    send_batch_size: 200
    timeout: 10s

exporters:
  otlphttp:
    tls:
      insecure: false
    endpoint: "https://monitoring.us-east-1.amazonaws.com/v1/metrics:443"
    auth:
      authenticator: sigv4auth

extensions:
  sigv4auth:
    service: "monitoring"
    region: "us-east-1"

service:
  extensions: [sigv4auth]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

Métricas com autenticação de token do portador

Confira a seguir um exemplo de como enviar métricas usando token do portador para us-east-1. Para obter instruções de configuração e práticas recomendadas de segurança, consulte Configurar autenticação do token do portador para Metrics.

extensions:
  bearertokenauth:
    filename: "/etc/otel/cw-api-key"

receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:4318"

processors:
  batch:
    send_batch_size: 200
    timeout: 10s

exporters:
  otlphttp:
    tls:
      insecure: false
    endpoint: "https://monitoring.us-east-1.amazonaws.com/v1/metrics"
    auth:
      authenticator: bearertokenauth

service:
  extensions: [bearertokenauth]
  pipelines:
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]
Importante

Nunca codifique chaves de API diretamente nos arquivos de configuração do coletor. Utilize filename para ler a partir de um segredo montado ou ${env:VAR} para ler a partir de uma variável de ambiente injetada pelo seu gerenciador de segredos.

nota

Diferentemente do SigV4, os tokens de portador não exigem arquivos de credenciais da AWS, perfis do IAM ou configuração do IRSA. O coletor pode ser executado em qualquer plataforma sem dependências do SDK da AWS.