Implantar o coletor do OpenTelemetry criado pelo Google no Cloud Run

Neste documento, mostramos como executar o coletor OpenTelemetry criado pelo Google no Cloud Run para coletar registros, métricas e rastreamentos do OTLP de aplicativos instrumentados e exportar esses dados para Google Cloud.

Antes de começar

Para executar o OpenTelemetry Collector criado pelo Google, você precisa dos seguintes recursos:

  1. 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.

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. 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

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. 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

    8.
  8. Um serviço do Cloud Run. Se você não tiver um serviço do Cloud Run, siga as instruções em Planejar e preparar seu serviço.
  9. Uma instalação do gcloud. Para informações sobre como instalar gcloud, consulte Instalar a CLI gcloud.

    10. Configurar permissões para o coletor

    Por padrão, os jobs e serviços do Cloud Run usam a conta de serviço padrão do Compute Engine, PROJECT_NUMBER-compute@developer.gserviceaccount.com. Essa conta de serviço geralmente tem os papéis do Identity and Access Management (IAM) necessários para gravar as métricas e os registros descritos neste documento:

    Peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

    Também é possível configurar uma conta de serviço gerenciado pelo usuário para o Cloud Run. Uma conta de serviço gerenciado pelo usuário também precisa ter esses papéis. Para mais informações sobre contas de serviço do Cloud Run, consulte Introdução à identidade do serviço.

    Implantar o coletor

    Para instalar o coletor OpenTelemetry criado pelo Google como um sidecar do Cloud Run, primeiro crie um secret para armazenar a configuração do coletor.

    gcloud secrets create SECRET_NAME --data-file=config.yaml --project=PROJECT_ID

    Em seguida, adicione o OpenTelemetry Collector criado pelo Google como um arquivo secundário ao seu service.yaml:

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  annotations:
    run.googleapis.com/launch-stage: ALPHA
  name: google-otel-cloud-run-sample
spec:
  template:
    metadata:
      annotations:
        # [REQUIRED] set the collector as a parent to the app
        run.googleapis.com/container-dependencies: "{app:[collector]}"
        run.googleapis.com/secrets: 'SECRET_NAME:projects/PROJECT_ID/secrets/SECRET_NAME'
    spec:
      containers:
      - image: my-app
        name: app
        ports:
        - containerPort: 8080
        env:
        - name: "OTEL_EXPORTER_OTLP_ENDPOINT"
          value: "http://localhost:4317"
      - image: "us-docker.pkg.dev/cloud-ops-agents-artifacts/google-cloud-opentelemetry-collector/otelcol-google:0.137.0"
        args:
        - --config=/etc/otelcol-google/config.yaml
        name: collector
        startupProbe:
          httpGet:
            path: /
            port: 13133
          timeoutSeconds: 30
          periodSeconds: 30
        livenessProbe:
          httpGet:
            path: /
            port: 13133
          timeoutSeconds: 30
          periodSeconds: 30
        volumeMounts:
        - mountPath: /etc/otelcol-google/
          name: config
      volumes:
      - name: config
        secret:
          items:
          - key: latest
            path: config.yaml
          secretName: 'SECRET_NAME'

    Configurar o coletor

    Fornecemos uma configuração do OpenTelemetry Collector para você usar com o coletor criado pelo Google. Essa configuração foi projetada para fornecer grandes volumes de métricas, registros e traces do OTLP. Essa configuração também foi projetada para evitar problemas comuns de ingestão. É possível adicionar à configuração, mas recomendamos que você 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ê encontra a configuração do coletor no diretório google-built-opentelemetry-collector do 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

    Exportadoras

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

    • Exportador googlecloud para registros e traces. Esse exportador é configurado com um nome de registro padrão.

    • Exportador googlemanagedprometheus para métricas. Esse exportador não exige configuração, mas há opções. Para informações sobre as opções de configuração do exportador googlemanagedprometheus, consulte Introdução ao OpenTelemetry Collector 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 número máximo de entradas por solicitação ou no intervalo mínimo de cada 5 segundos (o que ocorrer primeiro). Google Cloud Google Cloud

    • memory_limiter: Limita o uso da memória do coletor para evitar falhas por falta de memória ao descartar pontos de dados quando o limite é excedido.

    • resourcedetection: Detecta automaticamente rótulos de recursos do Google Cloud , como project_id.

    Recebedores

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

    Componentes disponíveis

    O OpenTelemetry Collector criado pelo Google contém os componentes que a maioria dos usuários precisa para ativar uma experiência completa na Observabilidade do Google Cloud. Para uma lista completa de 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

    Para gerar telemetria, crie um aplicativo do Cloud Run com um coletor sidecar. O documento Escrever métricas OTLP usando um arquivo secundário do OpenTelemetry fornece um tutorial sobre como usar o coletor OpenTelemetry integrado do Google como um arquivo secundário. Use este tutorial para gerar telemetria com o coletor criado pelo Google.

    Ver telemetria

    O coletor do OpenTelemetry criado pelo Google envia métricas, registros e traces dos seus aplicativos instrumentados para o Google Cloud Observability. O coletor também envia métricas de auto-observabilidade. As seções a seguir descrevem como visualizar 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 Collector criado pelo Google também grave algumas autométricas.

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

    1. No console Google Cloud , acesse a página do  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 OpenTelemetry Collector criado pelo Google têm o prefixo prometheus.googleapis.com.
      3. Clique em Aplicar.

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

    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 pelo 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 console Google Cloud , 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 console Google Cloud , selecione seu projeto Google Cloud . Para configurações do App Hub, selecione o projeto host ou de gerenciamento do App Hub.
    3. Na seção de tabela da página, selecione uma linha.

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

      Um painel é aberto com 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 console Google Cloud , acesse a página 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 do app instrumentado. Para conferir os detalhes, expanda a entrada.

    3. Clique em Traces em uma entrada de registro com uma mensagem de trace e selecione View trace details.

      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 do 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 console Google Cloud , 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 OpenTelemetry Collector.
    4. Opcional: para visualizar o painel, selecione-o.

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

      Na caixa de diálogo, selecione o nome do painel e adicione rótulos a ele.

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