Implemente o OpenTelemetry Collector no SO otimizado para contentores

Este documento descreve como executar o coletor OpenTelemetry criado pela Google no SO otimizado para contentores para recolher registos, métricas e rastreios OTLP de aplicações instrumentadas e, em seguida, exportar esses dados para o Google Cloud.

Antes de começar

A execução do OpenTelemetry Collector requer os seguintes recursos:

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

1. Uma máquina virtual (VM) do SO otimizado para contentores. Se não tiver uma VM do SO otimizado para contentores, siga as instruções em Criar e configurar instâncias.
2. Uma instalação da app gcloud. Para obter informações sobre a instalação do gcloud, consulte o artigo Instale a CLI Google Cloud.

Configure as autorizações para o coletor

Por predefinição, as VMs do SO otimizado para contentores usam a conta de serviço predefinida do Compute [e-mail]. Normalmente, esta conta de serviço tem as funções de gestão de identidade e de acesso (IAM) necessárias para escrever as métricas e os registos descritos neste documento:

• Monitoring Metric Writer (roles/monitoring.metricWriter)
• Logging Log Writer (roles/logging.logWriter)

Se estiver a configurar uma conta de serviço personalizada para a sua instância, consulte o artigo Faça a gestão do acesso às contas de serviço.

Implemente o coletor

Para executar o Google-Built OpenTelemetry Collector, tem de fornecer um ficheiro de configuração para a sua VM do SO otimizado para contentores. Pode usar a ferramenta cloud-init para escrever um ficheiro de configuração. Segue-se um ficheiro cloud-init recomendado para usar o coletor criado pela Google:

write_files:
- path: /etc/config/config.yaml
  permissions: 0644
  owner: root
  content: |
    receivers:
      # Open two OTLP servers:
      # - On port 4317, open an OTLP GRPC server
      # - On port 4318, open an OTLP HTTP server
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
      otlp:
        protocols:
          grpc:
            endpoint: localhost:4317
          http:
            cors:
              # This effectively allows any origin
              # to make requests to the HTTP server.
              allowed_origins:
              - http://*
              - https://*
            endpoint: localhost:4318

    processors:
      # The batch processor is in place to regulate both the number of requests
      # being made and the size of those requests.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
      batch:
        send_batch_max_size: 200
        send_batch_size: 200
        timeout: 5s

      # The memorylimiter will check the memory usage of the collector process.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
      memory_limiter:
        check_interval: 1s
        limit_percentage: 65
        spike_limit_percentage: 20

      # The resourcedetection processor is configured to detect GCP resources.
      # Resource attributes that represent the GCP resource the collector is
      # running on will be attached to all telemetry that goes through this
      # processor.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
      resourcedetection:
        detectors: [gcp]
        timeout: 10s

      transform/collision:
        metric_statements:
        - context: datapoint
          statements:
          - set(attributes["exported_location"], attributes["location"])
          - delete_key(attributes, "location")
          - set(attributes["exported_cluster"], attributes["cluster"])
          - delete_key(attributes, "cluster")
          - set(attributes["exported_namespace"], attributes["namespace"])
          - delete_key(attributes, "namespace")
          - set(attributes["exported_job"], attributes["job"])
          - delete_key(attributes, "job")
          - set(attributes["exported_instance"], attributes["instance"])
          - delete_key(attributes, "instance")
          - set(attributes["exported_project_id"], attributes["project_id"])
          - delete_key(attributes, "project_id")

    exporters:
      # The googlecloud exporter will export telemetry to different
      # Google Cloud services:
      # Logs -> Cloud Logging
      # Metrics -> Cloud Monitoring
      # Traces -> Cloud Trace
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
      googlecloud:
        log:
          default_log_name: opentelemetry-collector

      # The googlemanagedprometheus exporter will send metrics to
      # Google Managed Service for Prometheus.
      #
      # Docs:
      # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
      googlemanagedprometheus:

    service:
      pipelines:
        logs:
          receivers:
          - otlp
          processors:
          - resourcedetection
          - memory_limiter
          - batch
          exporters:
          - googlecloud
        metrics/otlp:
          receivers:
          - otlp
          processors:
          - resourcedetection
          - transform/collision
          - memory_limiter
          - batch
          exporters:
          - googlemanagedprometheus
        traces:
          receivers:
          - otlp
          processors:
          - resourcedetection
          - memory_limiter
          - batch
          exporters:
          - googlecloud
      # Internal telemetry for the collector supports both push and pull-based telemetry data transmission.
      # Leveraging the pre-configured OTLP receiver eliminates the need for an additional port.
      #
      # Docs:
      # https://opentelemetry.io/docs/collector/internal-telemetry/
      telemetry:
        metrics:
          readers:
            - periodic:
                exporter:
                  otlp:
                    protocol: grpc
                    endpoint: localhost:4317

Recomendamos que crie uma rede bridge do Docker para facilitar a comunicação entre o contentor do coletor e qualquer outro contentor no sistema que vai enviar telemetria. Para criar a rede, execute o seguinte comando:

docker network create -d bridge otel

Execute o contentor do coletor com o seguinte comando:

docker run -d \
    --network otel \
    --name opentelemetry-collector \
    -v /etc/config:/etc/config \
    us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.137.0 \
    --config=/etc/config/config.yaml

O comando anterior faz o seguinte:

• Executa o contentor do coletor em segundo plano.
• Associa o contentor do coletor à rede da bridge otel criada anteriormente. Outros contentores podem ser ligados à ponte para enviar telemetria.
• Monta o ficheiro de configuração no contentor para que o ficheiro possa ser acedido para configurar o coletor.
Nota: o valor da opção --name, opentelemetry-collector, é usado na secção Gerar telemetria subsequente. Se alterar o valor neste comando, use o seu valor quando definir o marcador de posição opentelemetry-collector nessa secção.

Configure o coletor

Fornecemos uma configuração do OpenTelemetry Collector para usar com o coletor criado pela Google. Esta configuração foi concebida para fornecer volumes elevados de métricas, registos e rastreios OTLP. Esta configuração também foi concebida para evitar problemas comuns de carregamento. Pode adicionar elementos à configuração, mas recomendamos vivamente que não remova elementos.

Esta secção descreve a configuração fornecida, os componentes principais, como exportadores, processadores, recetores e outros componentes disponíveis.

Configuração do coletor fornecida

Pode encontrar a configuração do coletor no diretório google-built-opentelemetry-collector no repositório opentelemetry-operations-collector:
receivers:
  # Open two OTLP servers:
  # - On port 4317, open an OTLP GRPC server
  # - On port 4318, open an OTLP HTTP server
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/receiver/otlpreceiver
  otlp:
    protocols:
      grpc:
        endpoint: localhost:4317
      http:
        cors:
          # This effectively allows any origin
          # to make requests to the HTTP server.
          allowed_origins:
          - http://*
          - https://*
        endpoint: localhost:4318

processors:
  # The batch processor is in place to regulate both the number of requests
  # being made and the size of those requests.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/batchprocessor
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  # The memorylimiter will check the memory usage of the collector process.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector/tree/main/processor/memorylimiterprocessor
  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  # The resourcedetection processor is configured to detect GCP resources.
  # Resource attributes that represent the GCP resource the collector is
  # running on will be attached to all telemetry that goes through this
  # processor.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
  resourcedetection:
    detectors: [gcp]
    timeout: 10s

  transform/collision:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["exported_location"], attributes["location"])
      - delete_key(attributes, "location")
      - set(attributes["exported_cluster"], attributes["cluster"])
      - delete_key(attributes, "cluster")
      - set(attributes["exported_namespace"], attributes["namespace"])
      - delete_key(attributes, "namespace")
      - set(attributes["exported_job"], attributes["job"])
      - delete_key(attributes, "job")
      - set(attributes["exported_instance"], attributes["instance"])
      - delete_key(attributes, "instance")
      - set(attributes["exported_project_id"], attributes["project_id"])
      - delete_key(attributes, "project_id")

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  # Traces -> Cloud Trace
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlecloudexporter
  googlecloud:
    log:
      default_log_name: opentelemetry-collector

  # The googlemanagedprometheus exporter will send metrics to
  # Google Managed Service for Prometheus.
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/googlemanagedprometheusexporter
  googlemanagedprometheus:

extensions:
  # Opens an endpoint on 13133 that can be used to check the
  # status of the collector. Since this does not configure the
  # `path` config value, the endpoint will default to `/`.
  #
  # When running on Cloud Run, this extension is required and not optional.
  # In other environments it is recommended but may not be required for operation
  # (i.e. in Container-Optimized OS or other GCE environments).
  #
  # Docs:
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/extension/healthcheckextension
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions:
  - health_check
  pipelines:
    logs:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
    metrics/otlp:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - transform/collision
      - memory_limiter
      - batch
      exporters:
      - googlemanagedprometheus
    traces:
      receivers:
      - otlp
      processors:
      - resourcedetection
      - memory_limiter
      - batch
      exporters:
      - googlecloud
  # Internal telemetry for the collector supports both push and pull-based telemetry data transmission.
  # Leveraging the pre-configured OTLP receiver eliminates the need for an additional port.
  #
  # Docs:
  # https://opentelemetry.io/docs/collector/internal-telemetry/
  telemetry:
    metrics:
      readers:
        - periodic:
            exporter:
              otlp:
                protocol: grpc
                endpoint: localhost:4317

Exportadores

A configuração do coletor inclui os seguintes exportadores:

• googlecloud exportador, para registos e rastreios. Este exportador está configurado com um nome de registo predefinido.

• googlemanagedprometheus exportador, para métricas. Este exportador não requer nenhuma configuração, mas existem opções de configuração. Para obter informações sobre as opções de configuração do exportador googlemanagedprometheus, consulte o artigo Introdução ao OpenTelemetry Collector na documentação do Google Cloud Managed Service for Prometheus.

Processadores

A configuração do coletor inclui os seguintes processadores:

• batch: Configurado para processar pedidos de telemetria em lote ao Google Cloud número máximo de entradas por pedido ou ao Google Cloud intervalo mínimo de 5 segundos (conforme o que ocorrer primeiro).

• memory_limiter: Limita a utilização de memória do coletor para evitar falhas de memória insuficiente ao rejeitar pontos de dados quando o limite é excedido.

• resourcedetection: Deteta automaticamente Google Cloud etiquetas de recursos, como project_id.

Recetores

A configuração do coletor inclui apenas o recetor otlp. Para obter informações sobre a instrumentação das suas aplicações para enviar rastreios OTLP e métricas para o ponto final OTLP do coletor, consulte a secção Escolha uma abordagem de instrumentação.

Componentes disponíveis

O coletor OpenTelemetry criado pela Google contém os componentes de que a maioria dos utilizadores vai precisar para ativar uma experiência avançada no Google Cloud Observability. Para ver uma lista completa dos componentes disponíveis, consulte o artigo Componentes no repositório opentelemetry-operations-collector.

Para pedir alterações ou adições aos componentes disponíveis, abra um pedido de funcionalidade. no repositório opentelemetry-operations-collector.

Gere telemetria

Pode testar a sua configuração através da ferramenta de código aberto telemetrygen. O projeto OpenTelemetry fornece um contentor no registo de contentores do GitHub.

Antes de executar os seguintes comandos, substitua os seguintes marcadores de posição, se tiver alterado as predefinições usadas nos comandos do Docker em Implemente o coletor:

• otel: o nome que especificou quando criou a rede Docker bridge.
• opentelemetry-collector: o nome que especificou quando executou o contentor.

Gere registos

Para gerar registos através da ferramenta telemetrygen, execute o seguinte comando:

docker run \
  --net=otel \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.105.0 \
  logs --otlp-insecure --rate=3 --duration=5m \
  --otlp-endpoint=opentelemetry-collector:4317

Gere métricas

Para gerar métricas através da ferramenta telemetrygen, execute o seguinte comando:

docker run \
  --net=otel \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.105.0 \
  metrics --otlp-insecure --rate=0.1 --duration=5m \
  --otlp-endpoint=opentelemetry-collector:4317

Gere métricas

Para gerar rastreios através da ferramenta telemetrygen, execute o seguinte comando:

docker run \
  --net=otel \
  ghcr.io/open-telemetry/opentelemetry-collector-contrib/telemetrygen:v0.105.0 \
  traces --otlp-insecure --rate=3 --duration=5m \
  --otlp-endpoint=opentelemetry-collector:4317

Após alguns minutos, a telemetria gerada pela aplicação começa a fluir através do coletor para a Google Cloud consola para cada sinal.

Ver telemetria

O coletor OpenTelemetry criado pela Google envia métricas, registos e rastreios das suas aplicações instrumentadas para o Google Cloud Observability. O coletor também envia métricas de auto-observabilidade. As secções seguintes descrevem como ver esta telemetria.

Veja as suas métricas

O coletor OpenTelemetry criado pela Google recolhe métricas do Prometheus que pode ver através do Explorador de métricas. As métricas recolhidas dependem da instrumentação da app, embora o coletor criado pela Google também escreva algumas métricas próprias.

Para ver as métricas recolhidas pelo Google-Built OpenTelemetry Collector, faça o seguinte:

1. Na Google Cloud consola, aceda à página  Explorador de métricas:

   Aceda ao Metrics Explorer

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
3. No elemento Métrica, expanda o menu Selecionar uma métrica, introduza Prometheus Target na barra de filtros e, de seguida, use os submenus para selecionar um tipo de recurso e uma métrica específicos:
   1. No menu Recursos ativos, selecione Alvo do Prometheus.
   2. Para selecionar uma métrica, use os menus Categorias de métricas ativas e Métricas ativas. As métricas recolhidas pelo Google-Built OpenTelemetry Collector têm o prefixo prometheus.googleapis.com.
   3. Clique em Aplicar.

4. Para adicionar filtros que removem séries cronológicas dos resultados da consulta, use o elemento Filter.

5. Configure a forma como os dados são vistos.
   

   Quando as medições de uma métrica são cumulativas, o explorador de métricas normaliza automaticamente os dados medidos pelo período de alinhamento, o que resulta na apresentação de uma taxa no gráfico. Para mais informações, consulte o artigo Tipos, tipos e conversões.

   Quando são medidos valores inteiros ou duplos, como com as métricas counter, o explorador de métricas soma automaticamente todas as séries cronológicas. Para alterar este comportamento, defina o primeiro menu da entrada Agregação como Nenhuma.

   Para mais informações sobre como configurar um gráfico, consulte o artigo Selecione métricas quando usar o explorador de métricas.

Veja os seus rastreios

Para ver os dados de rastreio, faça o seguinte:

1. Na Google Cloud consola, aceda à página Explorador de rastreios:

   Aceda ao Explorador de rastreios

   Também pode encontrar esta página através da barra de pesquisa.

2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião ou o projeto de gestão do App Hub.
3. Na secção da tabela da página, selecione uma linha.

4. No gráfico de Gantt no painel Detalhes do rastreio, selecione um intervalo.

   É aberto um painel que apresenta informações sobre o pedido rastreado. Estes detalhes incluem o método, o código de estado, o número de bytes e o agente do utilizador do autor da chamada.

5. Para ver os registos associados a este rastreio, selecione o separador Registos e eventos.

   O separador mostra registos individuais. Para ver os detalhes da entrada do registo, expanda a entrada do registo. Também pode clicar em Ver registos e ver o registo através do Explorador de registos.

Para mais informações sobre como usar o explorador do Cloud Trace, consulte o artigo Encontre e explore rastreios.

Veja os seus registos

No Explorador de registos, pode inspecionar os seus registos e também ver rastreios associados, quando existirem.

1. Na Google Cloud consola, aceda à página Explorador de registos:

   Aceda ao Explorador de registos

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

2. Localize uma entrada de registo na sua app instrumentada. Para ver os detalhes, expanda a entrada de registo.

3. Clique em Rastreios numa entrada de registo com uma mensagem de rastreio e, de seguida, selecione Ver detalhes do rastreio.

   É aberto um painel Detalhes do rastreio que apresenta o rastreio selecionado.

Para mais informações sobre a utilização do Explorador de registos, consulte o artigo Veja registos através do Explorador de registos.

Observe e depure o coletor

O Google-Built OpenTelemetry Collector fornece automaticamente métricas de autoobservabilidade para ajudar a monitorizar o respetivo desempenho e garantir o tempo de atividade contínuo do pipeline de carregamento do OTLP.

Para monitorizar o coletor, instale o painel de controlo de exemplo para o coletor. Este painel de controlo oferece estatísticas rápidas sobre várias métricas do coletor, incluindo tempo de atividade, utilização de memória e chamadas API para o Google Cloud Observability.

Para instalar o painel de controlo, faça o seguinte:

1. Na Google Cloud consola, aceda à página  Painéis de controlo:

   Aceda a Painéis de controlo

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

2. Clique em Modelos de painéis de controlo.
3. Pesquise o painel de controlo do OpenTelemetry Collector.
4. Opcional: para pré-visualizar o painel de controlo, selecione-o.

5. Clique em Adicionar painel de controlo à sua lista e, em seguida, conclua a caixa de diálogo.

   A caixa de diálogo permite-lhe selecionar o nome do painel de controlo e adicionar etiquetas ao painel de controlo.

Para mais informações sobre a instalação de painéis de controlo, consulte o artigo Instale um modelo de painel de controlo.