Implantar o coletor do OpenTelemetry no Container-Optimized OS

Neste documento, descrevemos como executar o Coletor do OpenTelemetry criado pelo Google no Container-Optimized OS para coletar registros, métricas e traces do OTLP de aplicativos instrumentados e exportar esses dados para Google Cloud.

Antes de começar

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

Faça login na sua Google Cloud conta do. Se você não conhece o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em cenários reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

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 role (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 role (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 Container-Optimized OS. Se você não tiver uma VM do Container-Optimized OS, siga as instruções em Como criar e configurar instâncias.
2. Uma instalação do gcloud. Para informações sobre como instalar gcloud, consulte Instalar a Google Cloud CLI.

Configurar permissões para o coletor

Por padrão, as VMs do Container-Optimized OS usam a conta de serviço padrão do Compute Engine, [e-mail]. Essa conta de serviço geralmente tem os papéis do Identity and Access Management (IAM) necessários para gravar a telemetria descrita neste documento:

• Gravador de métricas do Monitoring (roles/monitoring.metricWriter)
• Gravador de registros (roles/logging.logWriter)
• Agente do Cloud Trace

Se você estiver configurando uma conta de serviço personalizada para sua instância, consulte Gerenciar o acesso a contas de serviço.

Implantar o coletor

Para executar o Coletor do OpenTelemetry criado pelo Google, é necessário fornecer um arquivo de configuração para sua VM do Container-Optimized OS. Você pode usar a ferramenta cloud-init para gravar um arquivo de configuração. A seguir, apresentamos um arquivo cloud-init recomendado para usar o coletor criado pelo 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")

      transform/set_project_id:
        error_mode: ignore
        trace_statements:
        - set(resource.attributes["gcp.project_id"], resource.attributes["gcp.project.id"]) where resource.attributes["gcp.project.id"] != nil
        - set(resource.attributes["gcp.project_id"], resource.attributes["cloud.account.id"]) where resource.attributes["gcp.project_id"] == nil and resource.attributes["cloud.account.id"] != nil

    exporters:
      # The googlecloud exporter will export telemetry to different
      # Google Cloud services:
      # Logs -> Cloud Logging
      # Metrics -> Cloud Monitoring
      #
      # 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:

      # The otlp exporter is used to send traces to GCP Telemetry API using OTLP gRPC
      otlp:
        endpoint: telemetry.googleapis.com:443
        compression: none
        balancer_name: pick_first
        auth:
          authenticator: googleclientauth

    extensions:
      googleclientauth:

    service:
      extensions:
      - googleclientauth
      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
          - transform/set_project_id
          - batch
          exporters:
          - otlp
      # 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: http://localhost:4317
                    insecure: true

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

docker network create -d bridge otel

Execute o contêiner 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.151.0 \
    --config=/etc/config/config.yaml

O comando anterior faz o seguinte:

• Executa o contêiner do coletor em segundo plano.
• Anexa o contêiner do coletor à rede otel de bridge criada anteriormente. Outros contêineres podem ser conectados à bridge para enviar telemetria.
• Monta o arquivo de configuração no contêiner para que ele possa ser acessado para configurar o coletor.

Observação: o valor da opção --name, opentelemetry-collector, é usado na seção Gerar telemetria subsequente. Se você mudar o valor nesse comando, use seu valor ao definir o opentelemetry-collector marcador nessa seção.

Configurar o coletor

Fornecemos uma configuração do Coletor do OpenTelemetry para você usar com o coletor criado pelo Google. Essa configuração foi projetada para oferecer grandes volumes de métricas, registros e traces do OTLP. Essa configuração também foi projetada para evitar problemas comuns de ingestão. Você pode adicionar à configuração, mas recomendamos que não remova elementos.

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

Configuração do coletor fornecida

Você pode encontrar a configuração do coletor no google-built-opentelemetry-collector diretório no opentelemetry-operations-collector repositório:

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")

  transform/set_project_id:
    error_mode: ignore
    trace_statements:
    - set(resource.attributes["gcp.project_id"], resource.attributes["gcp.project.id"]) where resource.attributes["gcp.project.id"] != nil
    - set(resource.attributes["gcp.project_id"], resource.attributes["cloud.account.id"]) where resource.attributes["gcp.project_id"] == nil and resource.attributes["cloud.account.id"] != nil

exporters:
  # The googlecloud exporter will export telemetry to different
  # Google Cloud services:
  # Logs -> Cloud Logging
  # Metrics -> Cloud Monitoring
  #
  # 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:

  # The otlp exporter is used to send traces to GCP Telemetry API using OTLP gRPC
  otlp:
    endpoint: telemetry.googleapis.com:443
    compression: none
    balancer_name: pick_first
    auth:
      authenticator: googleclientauth

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
  googleclientauth:

service:
  extensions:
  - health_check
  - googleclientauth
  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
      - transform/set_project_id
      - batch
      exporters:
      - otlp
  # 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: http://localhost:4317
                insecure: true

Exportadoras

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

• googlecloud exportador, para registros e traces. Esse exportador está configurado com um nome de registro padrão.

• googlemanagedprometheus exportador, para métricas. Esse exportador não requer nenhuma configuração, mas há opções de configuração. Para informações sobre as opções de configuração do exportador googlemanagedprometheus, consulte Introdução ao Coletor do OpenTelemetry na documentação do Google Cloud Managed Service para Prometheus.

Processadores

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

• batch: configurado para agrupar solicitações de telemetria com o Google Cloud número máximo de entradas por solicitação ou no Google Cloud intervalo mínimo de cada 5 segundos (o que ocorrer primeiro).

• memory_limiter: limita o uso da memória do coletor para evitar falhas de memória insuficiente, descartando pontos de dados quando o limite é excedido.

• resourcedetection: detecta automaticamente os Google Cloud rótulos de recursos, como project_id.

Recebedores

A configuração do coletor inclui apenas o otlp receptor. Para informações sobre como instrumentar seus aplicativos para enviar traces do OTLP e métricas para o endpoint do OTLP do coletor, consulte Escolher uma abordagem de instrumentação.

Componentes disponíveis

O Coletor do OpenTelemetry criado pelo Google contém os componentes que a maioria dos usuários precisa para ativar uma experiência avançada no Google Cloud Observability. Para uma lista completa dos componentes disponíveis, consulte Componentes no repositório opentelemetry-operations-collector.

Para solicitar mudanças ou adições aos componentes disponíveis, abra uma solicitação de recurso. no repositório opentelemetry-operations-collector.

Gerar telemetria

Você pode testar sua configuração usando a ferramenta de código aberto telemetrygen. O projeto OpenTelemetry fornece um contêiner no registro de contêiner do GitHub.

Antes de executar os comandos a seguir, substitua os marcadores a seguir, se você tiver mudado os padrões usados nos comandos do Docker em Implantar o coletor:

• otel: o nome especificado ao criar a rede bridge do Docker.
• opentelemetry-collector: o nome especificado ao executar o contêiner.

Gerar registros

Para gerar registros usando a 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

Gerar métricas

Para gerar métricas usando a 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

Gerar traces

Para gerar traces usando a 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 pelo aplicativo começa a fluir pelo coletor para o Google Cloud console para cada indicador.

Acessar a telemetria

O Coletor do OpenTelemetry criado pelo Google envia métricas, registros e traces dos aplicativos instrumentados para o Google Cloud Observability. O coletor também envia métricas de auto-observabilidade. As seções a seguir descrevem como acessar essa telemetria.

Ver suas métricas

O Coletor do OpenTelemetry criado pelo Google coleta métricas do Prometheus que podem ser visualizadas usando o Metrics Explorer. As métricas coletadas dependem da instrumentação do app, embora o coletor criado pelo Google também grave algumas métricas próprias.

Para acessar as métricas coletadas pelo Coletor do OpenTelemetry criado pelo Google, faça o seguinte:

1. No Google Cloud console, acesse a  página Metrics Explorer:

   Acesse o Metrics Explorer

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Na barra de ferramentas do console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host do App Hub ou o projeto de gerenciamento da pasta habilitada para apps.
3. No elemento Metric, expanda o menu Selecionar uma métrica, digite Prometheus Target na barra de filtro e use os submenus para selecionar um tipo de recurso e métrica específicos:
   1. No menu Active resources, selecione Prometheus Target.
   2. Para selecionar uma métrica, use os menus Categorias de métricas ativas e Métricas ativas. As métricas coletadas pelo Coletor do OpenTelemetry criado pelo Google têm o prefixo prometheus.googleapis.com.
   3. Clique em Aplicar.

4. Para adicionar filtros que removem série temporal dos resultados da consulta, use o Filtro elemento.

5. Configure a visualização dos dados.
   

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

   Quando valores inteiros ou duplos são medidos, como acontece com as métricas counter, o Metrics Explorer soma automaticamente todas as série temporal. Para mudar esse comportamento, defina o primeiro menu da entrada Agregação como Nenhum.

   Para mais informações sobre como configurar um gráfico, consulte Selecionar métricas ao usar o Metrics Explorer.

Visualizar os rastros

Para visualizar os dados de trace, faça o seguinte:

1. No Google Cloud console, acesse a página Explorador de traces:

   Acessar o Explorador de traces

   Também é possível encontrar essa página usando a barra de pesquisa.

2. Na barra de ferramentas do Google Cloud console, selecione seu Google Cloud projeto. Para App Hub configurações, selecione o projeto host do App Hub ou o projeto de gerenciamento.
3. Na seção de tabela da página, selecione uma linha.

4. No gráfico de Gantt no painel Detalhes do trace , selecione um período.

   Um painel é aberto mostrando informações sobre a solicitação rastreada. Esses detalhes incluem o método, o código de status, o número de bytes e o user agent do autor da chamada.

5. Para visualizar os registros associados a esse trace, selecione a guia Registros e eventos.

   A guia mostra registros individuais. Para exibir os detalhes da entrada de registro, expanda a entrada de registro. Também é possível clicar em Ver registros e ver o registro usando a Análise de registros.

Para mais informações sobre como usar o explorador do Cloud Trace, consulte Encontrar e explorar traces.

Acessar os registros

Na Análise de registros, é possível inspecionar os registros e visualizar os traces associados, quando eles existirem.

1. No Google Cloud console do, acesse a página segmento Análise de registros:

   Acessar a Análise de registros

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Logging.

2. Localize uma entrada de registro no app instrumentado. Para ver os detalhes, expanda a entrada de registro.

3. Clique em Traces em uma entrada de registro com uma mensagem de trace e selecione Ver detalhes do trace.

   O painel Detalhes do trace é aberto e mostra o trace selecionado.

Para mais informações sobre como usar a Análise de registros, consulte Ver registros usando a Análise de registros.

Observar e depurar o coletor

O Coletor do OpenTelemetry criado pelo Google fornece automaticamente métricas de auto-observabilidade para ajudar você a monitorar o desempenho e garantir o tempo de atividade contínuo do pipeline de ingestão OTLP.

Para monitorar o Coletor, instale o painel de amostra dele. Esse painel do Google Analytics oferece insights gerais sobre várias métricas do Coletor, incluindo tempo de atividade, uso de memória e chamadas de API para a observabilidade do Google Cloud.

Para instalar o painel, faça o seguinte:

1. No Google Cloud console, acesse a página  Painéis:

   Acesse Painéis

   Se você usar a barra de pesquisa para encontrar essa página, selecione o resultado com o subtítulo Monitoring.

2. Clique em Modelos de painel.
3. Pesquise o painel Coletor do OpenTelemetry.
4. Opcional: para visualizar o painel, selecione-o.

5. Clique em Adicionar painel à sua lista e preencha a caixa de diálogo.

   A caixa de diálogo permite selecionar o nome do painel e adicionar rótulos a ele.

Para mais informações sobre como instalar painéis, consulte Instalar um modelo de painel.