Implantar o coletor do OpenTelemetry criado pelo Google no Google Kubernetes Engine

Neste documento, descrevemos como executar o Coletor do OpenTelemetry criado pelo Google no Google Kubernetes Engine 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 criado pelo Google requer os seguintes recursos:

Faça login na sua Google Cloud conta do. Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho dos nossos produtos em situações 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 Telemetry, 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 Telemetry, 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. Um cluster do Kubernetes. Se você não tiver um cluster do Kubernetes, siga as instruções no Guia de início rápido para GKE.

2. As seguintes ferramentas de linha de comando:

   • gcloud
   • kubectl

   As ferramentas gcloud e kubectl fazem parte da Google Cloud CLI. Para mais informações sobre como instalá-las, consulte Como gerenciar componentes da CLI do Google Cloud. Para ver os componentes da CLI gcloud que você instalou, execute o seguinte comando:

           gcloud components list
           

Configurar permissões para o coletor

Se você desativou a identidade da carga de trabalho do GKE, pule esta seção.

Para garantir que a conta de serviço do Kubernetes do Coletor do OpenTelemetry tenha as permissões necessárias para exportar a telemetria, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço do Kubernetes do Coletor do OpenTelemetry no seu projeto:

Importante: conceda esses papéis à conta de serviço do Kubernetes do Coletor do OpenTelemetry, não à sua conta de usuário. Se os papéis não forem concedidos ao principal correto, poderão ocorrer erros de permissão.

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

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

O administrador também pode conceder à conta de serviço do Kubernetes do Coletor do OpenTelemetry as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Para configurar as permissões, use os seguintes add-iam-policy-binding comandos:

gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/logging.logWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/monitoring.metricWriter \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector
gcloud projects add-iam-policy-binding projects/PROJECT_ID \
    --role=roles/cloudtrace.agent \
    --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/opentelemetry/sa/opentelemetry-collector

Antes de executar os comandos, substitua as seguintes variáveis:

• PROJECT_ID: o identificador do projeto.
• PROJECT_NUMBER: o Google Cloud número do projeto.

Implantar o coletor

O pipeline do coletor pode ser implantado diretamente dos exemplos verificados fornecidos pelo repositório de ingestão do Kubernetes OTLP autogerenciado. É possível implantar diretamente do GitHub com os seguintes comandos depois de substituir PROJECT_ID pelo ID do seu Google Cloud projeto:

export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export PROJECT_NUMBER=PROJECT_NUMBER
kubectl kustomize https://github.com/GoogleCloudPlatform/otlp-k8s-ingest.git/k8s/base | envsubst | kubectl apply -f -

Antes de executar os comandos, substitua as seguintes variáveis:

• PROJECT_ID: o identificador do projeto.
• PROJECT_NUMBER: o identificador numérico do projeto.

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 entregar grandes volumes de métricas, registros e traces do OTLP com metadados consistentes do GKE e do Kubernetes anexados. 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

É possível encontrar a configuração do coletor para ambientes do Kubernetes no repositório otlp-k8s-ingest:

# Copyright 2024 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

exporters:
  googlecloud:
    log:
      default_log_name: opentelemetry-collector
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  googlemanagedprometheus:
    user_agent: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)
  # The otlphttp exporter is used to send traces to Google Cloud Trace using OTLP http/proto
  # The otlp exporter could also be used to send them using OTLP grpc
  otlphttp:
    encoding: proto
    endpoint: https://telemetry.googleapis.com
    # Use the googleclientauth extension to authenticate with Google credentials
    auth:
      authenticator: googleclientauth


extensions:
  health_check:
    endpoint: ${env:MY_POD_IP}:13133
  googleclientauth:


processors:
  filter/self-metrics:
    metrics:
      include:
        match_type: strict
        metric_names:
        - otelcol_process_uptime
        - otelcol_process_memory_rss
        - otelcol_grpc_io_client_completed_rpcs
        - otelcol_googlecloudmonitoring_point_count
  batch:
    send_batch_max_size: 200
    send_batch_size: 200
    timeout: 5s

  k8sattributes:
    extract:
      metadata:
      - k8s.namespace.name
      - k8s.deployment.name
      - k8s.statefulset.name
      - k8s.daemonset.name
      - k8s.cronjob.name
      - k8s.job.name
      - k8s.replicaset.name
      - k8s.node.name
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.pod.start_time
    passthrough: false
    pod_association:
    - sources:
      - from: resource_attribute
        name: k8s.pod.ip
    - sources:
      - from: resource_attribute
        name: k8s.pod.uid
    - sources:
      - from: connection

  memory_limiter:
    check_interval: 1s
    limit_percentage: 65
    spike_limit_percentage: 20

  metricstransform/self-metrics:
    transforms:
    - action: update
      include: otelcol_process_uptime
      operations:
      - action: add_label
        new_label: version
        new_value: Google-Cloud-OTLP manifests:0.5.0 OpenTelemetry Collector Built By Google/0.131.0 (linux/amd64)

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

  # The relative ordering of statements between ReplicaSet & Deployment and Job & CronJob are important.
  # The ordering of these controllers is decided based on the k8s controller documentation available at
  # https://kubernetes.io/docs/concepts/workloads/controllers.
  # The relative ordering of the other controllers in this list is inconsequential since they directly
  # create pods.
  transform/aco-gke:
    metric_statements:
    - context: datapoint
      statements:
      - set(attributes["top_level_controller_type"], "ReplicaSet") where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.replicaset.name"]) where resource.attributes["k8s.replicaset.name"] != nil
      - set(attributes["top_level_controller_type"], "Deployment") where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.deployment.name"]) where resource.attributes["k8s.deployment.name"] != nil
      - set(attributes["top_level_controller_type"], "DaemonSet") where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.daemonset.name"]) where resource.attributes["k8s.daemonset.name"] != nil
      - set(attributes["top_level_controller_type"], "StatefulSet") where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.statefulset.name"]) where resource.attributes["k8s.statefulset.name"] != nil
      - set(attributes["top_level_controller_type"], "Job") where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.job.name"]) where resource.attributes["k8s.job.name"] != nil
      - set(attributes["top_level_controller_type"], "CronJob") where resource.attributes["k8s.cronjob.name"] != nil
      - set(attributes["top_level_controller_name"], resource.attributes["k8s.cronjob.name"]) where resource.attributes["k8s.cronjob.name"] != nil

  # When sending telemetry to the GCP OTLP endpoint, the gcp.project_id resource attribute is required to be set to your project ID.
  resource/gcp_project_id:
    attributes:
    - key: gcp.project_id
      # MAKE SURE YOU REPLACE THIS WITH YOUR PROJECT ID
      value: ${GOOGLE_CLOUD_PROJECT}
      action: insert
  # The metricstarttime processor is important to include if you are using the prometheus receiver to ensure the start time is set properly.
  # It is a no-op otherwise.
  metricstarttime:
    strategy: subtract_initial_point

receivers:
  # This collector is configured to accept OTLP metrics, logs, and traces, and is designed to receive OTLP from workloads running in the cluster.
  otlp:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:4317
      http:
        cors:
          allowed_origins:
          - http://*
          - https://*
        endpoint: ${env:MY_POD_IP}:4318
  otlp/self-metrics:
    protocols:
      grpc:
        endpoint: ${env:MY_POD_IP}:14317

service:
  extensions:
  - health_check
  - googleclientauth
  pipelines:
    logs:
      exporters:
      - googlecloud
      processors:
      - k8sattributes
      - resourcedetection
      - memory_limiter
      - batch
      receivers:
      - otlp
    metrics/otlp:
      exporters:
      - googlemanagedprometheus
      processors:
      - k8sattributes
      - memory_limiter
      - metricstarttime
      - resourcedetection
      - transform/collision
      - transform/aco-gke
      - batch
      receivers:
      - otlp
    metrics/self-metrics:
      exporters:
      - googlemanagedprometheus
      processors:
      - filter/self-metrics
      - metricstransform/self-metrics
      - k8sattributes
      - memory_limiter
      - resourcedetection
      - batch
      receivers:
      - otlp/self-metrics
    traces:
      exporters:
      - otlphttp
      processors:
      - k8sattributes
      - memory_limiter
      - resource/gcp_project_id
      - resourcedetection
      - batch
      receivers:
      - otlp
  telemetry:
    logs:
      encoding: json
    metrics:
      readers:
      - periodic:
          exporter:
            otlp:
              protocol: grpc
              endpoint: http://${env:MY_POD_IP}:14317
              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 por falta de memória ao descartar pontos de dados quando o limite é excedido.

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

• k8sattributes: mapeia automaticamente os atributos de recursos do Kubernetes para rótulos de telemetria.

• transform: renomeia os rótulos de métricas que entram em conflito com os rótulos em Google Cloud recursos monitorados.

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

Esta seção descreve a implantação de um aplicativo de exemplo e a indicação do aplicativo para o endpoint OTLP do coletor, bem como a visualização da telemetria em Google Cloud. O aplicativo de exemplo é um pequeno gerador que exporta traces, registros e métricas para o coletor.

Se você já tiver um aplicativo instrumentado com um SDK do OpenTelemetry, é possível apontar seu aplicativo para o endpoint do coletor.

Para implantar o aplicativo de amostra, execute o seguinte comando:

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/otlp-k8s-ingest/main/sample/app.yaml

Para apontar os aplicativos existentes que usam o SDK do OpenTelemetry no endpoint do coletor, defina a variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT como http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317.

Após alguns minutos, a telemetria gerada pelo aplicativo começa a fluir pelo coletor para o Google Cloud console para cada indicador.

Visualizar 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 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 coletor criado pelo Google também grave algumas autométricas.

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

1. No Google Cloud console, acesse a  Metrics explorer page:

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