Implementa el recopilador de OpenTelemetry creado por Google en Google Kubernetes Engine

En este documento, se describe cómo ejecutar el recopilador de OpenTelemetry integrado en Google en Google Kubernetes Engine para recopilar registros, métricas y seguimientos de OTLP de aplicaciones instrumentadas y, luego, exportar esos datos a Google Cloud.

Antes de comenzar

La ejecución del recopilador de OpenTelemetry integrado en Google requiere los siguientes recursos:

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

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, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). 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, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. Un clúster de Kubernetes. Si no tienes un clúster de Kubernetes, sigue las instrucciones en la Guía de inicio rápido para GKE.

2. Las siguientes herramientas de línea de comandos:

   • gcloud
   • kubectl

   Las herramientas gcloud y kubectl forman parte de la Google Cloud CLI. Para obtener información sobre cómo instalarlos, consulta Administra los componentes de la CLI de Google Cloud. Para ver los componentes de gcloud CLI que instalaste, ejecuta el siguiente comando:

           gcloud components list
           

Configura los permisos para el recopilador

Si inhabilitaste la identidad de carga de trabajo de GKE, puedes omitir esta sección.

Para garantizar que la cuenta de servicio de Kubernetes del recopilador de OpenTelemetry tenga los permisos necesarios para exportar la telemetría, pídele a tu administrador que le otorgue los siguientes roles de IAM a la cuenta de servicio de Kubernetes del recopilador de OpenTelemetry en tu proyecto:

Importante: Debes otorgar estos roles a la cuenta de servicio de Kubernetes del recopilador de OpenTelemetry, no a tu cuenta de usuario. Si no otorgas los roles a la entidad de seguridad correcta, es posible que se produzcan errores de permisos.

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

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar a la cuenta de servicio de Kubernetes del recopilador de OpenTelemetry los permisos necesarios a través de roles personalizados o con otros roles predefinidos.

Para configurar los permisos, usa los siguientes 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 ejecutar los comandos, reemplaza las siguientes variables:

• PROJECT_ID: Es el identificador del proyecto.
• PROJECT_NUMBER: Es el Google Cloud número del proyecto.

Implementa el recopilador

La canalización del recopilador se puede implementar directamente desde los ejemplos verificados que proporciona el repositorio de transferencia de OTLP de Kubernetes autoadministrado. Puedes implementar directamente desde GitHub con los siguientes comandos después de reemplazar PROJECT_ID por el ID de tu Google Cloud proyecto:

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 ejecutar los comandos, reemplaza las siguientes variables:

• PROJECT_ID: Es el identificador del proyecto.
• PROJECT_NUMBER: Es el identificador numérico del proyecto.

Configura el recopilador

Te proporcionamos una configuración del recopilador de OpenTelemetry para que la uses con el recopilador integrado en Google. Esta configuración está diseñada para entregar grandes volúmenes de métricas, registros y seguimientos de OTLP con metadatos coherentes de GKE y Kubernetes adjuntos. Esta configuración también está diseñada para evitar problemas comunes de transferencia. Puedes agregar a la configuración, pero te recomendamos que no quites elementos.

En esta sección, se describe la configuración proporcionada, los componentes clave, como exportadores, procesadores, receptores y otros componentes disponibles.

Configuración del recopilador proporcionada

Puedes encontrar la configuración del recopilador para entornos de Kubernetes en el otlp-k8s-ingest repositorio:

# 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

Exportadores

La configuración del recopilador usa lo siguiente:

• El exportador de gRPC de OTLP para enviar registros, métricas y seguimientos a la API de Telemetry (OTLP).
• El googleclientauthextension para la autenticación de la API.

Procesadores

La configuración del recopilador incluye los siguientes procesadores:

• batch:Se configura para solicitudes de telemetría por lotes en la Google Cloud cantidad máxima de entradas por solicitud o en el Google Cloud intervalo mínimo de 5 segundos (lo que ocurra primero).

• memory_limiter: Limita el uso de memoria del recopilador para evitar fallas por memoria insuficiente mediante la eliminación de datos cuando se supera el límite.

• resourcedetection: Detecta automáticamente Google Cloud las etiquetas de recursos, como project_id y cluster_name.

• k8sattributes: Asigna de forma automática los atributos de recursos de Kubernetes a etiquetas de telemetría.

• transform: Cambia el nombre de las etiquetas de métricas que entran en conflicto con las etiquetas de los Google Cloud recursos supervisados.

Receptores

La configuración del recopilador solo incluye el otlp receptor. Para obtener información sobre cómo instrumentar tus aplicaciones para enviar seguimientos de OTLP y métricas al extremo de OTLP del recopilador, consulta Elige un enfoque de instrumentación.

Componentes disponibles

El recopilador de OpenTelemetry integrado en Google contiene los componentes que la mayoría de los usuarios necesitarán para habilitar una experiencia enriquecida en Google Cloud Observability. Para obtener una lista completa de los componentes disponibles, consulta Componentes en el opentelemetry-operations-collector repositorio.

Para solicitar cambios o adiciones a los componentes disponibles, abre una solicitud de función. en el repositorio opentelemetry-operations-collector.

Genera telemetría

En esta sección, se describe cómo implementar una aplicación de ejemplo y cómo apuntar esa aplicación al extremo de OTLP del recopilador y cómo ver la telemetría en Google Cloud. La aplicación de muestra es un generador pequeño que exporta seguimientos, registros y métricas al recopilador.

Si ya tienes una aplicación instrumentada con un SDK de OpenTelemetry, puedes apuntar tu aplicación al extremo del recopilador.

Para implementar la aplicación de muestra, ejecuta el siguiente comando:

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

Para apuntar a las aplicaciones existentes que usan el SDK de OpenTelemetry en el extremo del recopilador, establece la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT en http://opentelemetry-collector.opentelemetry.svc.cluster.local:4317.

Después de unos minutos, la telemetría que genera la aplicación comienza a fluir a través del recopilador hacia la Google Cloud consola de para cada indicador.

Visualiza la telemetría

El recopilador de OpenTelemetry integrado en Google envía métricas, registros y seguimientos de tus aplicaciones instrumentadas a Google Cloud Observability. El recopilador también envía métricas de autoobservabilidad. En las siguientes secciones, se describe cómo ver esta telemetría.

Consulta tus métricas

El recopilador de OpenTelemetry integrado en Google recopila métricas de Prometheus que puedes ver mediante el Explorador de métricas. Las métricas recopiladas dependen de la instrumentación de la app, aunque el recopilador integrado en Google también escribe algunas métricas propias.

Para ver las métricas recopiladas por el recopilador de OpenTelemetry integrado en Google, haz lo siguiente:

1. En la Google Cloud consola de, accede a la  Explorador de métricas página:

   Acceder al Explorador de métricas

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

2. En la barra de herramientas de la Google Cloud consola de, elige el Google Cloud proyecto. Para las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de administración de la carpeta habilitada para apps.
3. En el elemento Métrica, expande el menú Seleccionar una métrica, ingresa Prometheus Target en la barra de filtros y, luego, usa los submenús para seleccionar un métrica y tipo de recurso específicos:
   1. En el menú Recursos activos, elige Destino de Prometheus.
   2. Para seleccionar una métrica, usa los menús Categorías de métricas activas y Métricas activas. Las métricas recopiladas por el recopilador de OpenTelemetry integrado en Google tienen el prefijo prometheus.googleapis.com.
   3. Haz clic en Aplicar.

4. Para agregar filtros, que quitan series temporales de los resultados de la consulta, usa el Filtro elemento.

5. Configura cómo se ven los datos.
   

   Cuando las mediciones de una métrica son acumulativas, el Explorador de métricas normaliza automáticamente los datos medidos por el período de alineación, lo que hace que el gráfico muestre una frecuencia. Para obtener más información, consulta Categorías, tipos y conversiones.

   Cuando se miden valores de números enteros o dobles, como con las métricas counter, el Explorador de métricas suma automáticamente todas las series temporales. Para cambiar este comportamiento, establece el primer menú de la entrada Agregación como Ninguna.

   Para obtener más información sobre la configuración de un gráfico, consulta elige métricas cuando uses el Explorador de métricas.

Ve tus seguimientos

Para ver tus datos de seguimiento, haz lo siguiente:

1. En la Google Cloud consola de, ve a la Explorador de seguimientos página:

   Ir al Explorador de seguimientos

   También puedes usar la barra de búsqueda para encontrar esta página.

2. En la barra de herramientas de la Google Cloud consola, elige el Google Cloud proyecto. Para las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de administración.
3. En la sección de la tabla de la página, selecciona una fila.

4. En el diagrama de Gantt del panel Detalles de seguimiento , selecciona un intervalo.

   Se abre un panel que muestra información sobre la solicitud rastreada. Estos detalles incluyen el método, el código de estado, la cantidad de bytes y el usuario-agente del emisor.

5. Para ver los registros asociados con este seguimiento, selecciona la pestaña Registros y eventos.

   La pestaña muestra registros individuales. Para ver los detalles de la entrada de registro, expande la entrada de registro. También puedes hacer clic en Ver registros y ver el registro con el Explorador de registros.

Si deseas obtener más información para usar el explorador de Cloud Trace, consulta Busca y explora seguimientos.

Mira los registros

En el Explorador de registros, puedes inspeccionar tus registros y, también, puedes ver los seguimientos asociados, cuando existen.

1. En la Google Cloud consola de, ve a la página Explorador de registros del segmento:

   Ir al Explorador de registros

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

2. Busca una entrada de registro de tu app instrumentada. Para ver los detalles, expande la entrada de registro.

3. Haz clic en Seguimientos en una entrada de registro con un mensaje de seguimiento y, luego, selecciona Ver detalles de seguimiento.

   Se abrirá el panel Detalles de seguimiento y se mostrará el seguimiento seleccionado.

Para obtener más información sobre el uso del Explorador de registros, consulta Visualiza registros con el Explorador de registros.

Observa y depura el recopilador

El recopilador de OpenTelemetry integrado en Google proporciona automáticamente métricas de autoobservabilidad para ayudarte a supervisar su rendimiento y garantizar un tiempo de actividad continuo de la canalización de transferencia de OTLP.

Para supervisar el recopilador, instala el panel de muestra para el recopilador. Este panel ofrece estadísticas resumidas sobre varias métricas del recopilador, incluidos el tiempo de actividad, el uso de memoria y las llamadas a la API de Google Cloud Observability.

Para instalar el panel, haz lo siguiente:

1. En la Google Cloud consola de, accede a la  Paneles página:

   Acceder a Paneles

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Monitoring.

2. Haz clic en Plantillas de panel.
3. Busca el panel Recopilador de OpenTelemetry.
4. Opcional: Para obtener una vista previa del panel, selecciónalo.

5. Haz clic en Agregar panel a tu lista y luego, completa el cuadro de diálogo.

   El cuadro de diálogo te permite seleccionar el nombre del panel y agregarle etiquetas.

Para obtener más información sobre la instalación de paneles, consulta Instala una plantilla de panel.