Implementa el recopilador de OpenTelemetry en Container-Optimized OS

En este documento, se describe cómo ejecutar el recopilador de OpenTelemetry integrado en Google en Container-Optimized OS 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 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 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. Una máquina virtual (VM) de Container-Optimized OS. Si no tienes una VM de Container-Optimized OS, sigue las instrucciones en Crea y configura instancias.
2. Una instalación de gcloud. Para obtener información sobre la instalación de gcloud, consulta Instala Google Cloud CLI.

Configura los permisos para el recopilador

De forma predeterminada, las VMs de Container-Optimized OS usan la cuenta de servicio predeterminada de Compute Engine, [e-mail]. Por lo general, esta cuenta de servicio tiene los roles de Identity and Access Management (IAM) necesarios para escribir la telemetría que se describe en este documento:

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

Si configuras una cuenta de servicio personalizada para tu instancia, consulta Administra el acceso a las cuentas de servicio.

Implementa el recopilador

Para ejecutar el recopilador de OpenTelemetry integrado en Google, debes proporcionar un archivo de configuración para tu VM de Container-Optimized OS. Puedes usar la cloud-init herramienta para escribir un archivo de configuración. A continuación, se muestra un archivo cloud-init recomendado para usar el recopilador integrado en 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

Te recomendamos que crees una red bridge de Docker para facilitar la comunicación entre el contenedor del recopilador y cualquier otro contenedor del sistema que enviará telemetría. Para crear la red, ejecuta el siguiente comando:

docker network create -d bridge otel

Ejecuta el contenedor del recopilador con el siguiente 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

El comando anterior hace lo siguiente:

• Ejecuta el contenedor del recopilador en segundo plano.
• Conecta el contenedor del recopilador a la red de puente otel creada anteriormente. Se pueden conectar otros contenedores al puente para enviar telemetría.
• Activa el archivo de configuración en el contenedor para que se pueda acceder a él y configurar el recopilador.

Nota: El valor de la opción --name, opentelemetry-collector, se usa en la sección Genera telemetría posterior. Si cambias el valor en este comando, usa tu valor cuando configures el opentelemetry-collector marcador de posición en esa sección.

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. 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 en el google-built-opentelemetry-collector directorio del opentelemetry-operations-collector repositorio:

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

Exportadores

La configuración del recopilador incluye los siguientes exportadores:

• googlecloud exportador para registros y seguimientos. El exportador se configura con un nombre de registro predeterminado.

• googlemanagedprometheus exportador para métricas. Este exportador no requiere ninguna configuración, pero hay opciones de configuración. Para obtener información sobre las opciones de configuración del exportador googlemanagedprometheus, consulta Comienza a usar el recopilador de OpenTelemetry en la documentación de Google Cloud Managed Service para Prometheus.

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 las etiquetas de recursos, como project_id. Google Cloud

Receptores

La configuración del recopilador incluye solo 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

Puedes probar tu configuración con la herramienta de código abierto telemetrygen. El proyecto OpenTelemetry proporciona un contenedor en el registro de contenedores de GitHub.

Antes de ejecutar los siguientes comandos, reemplaza los siguientes marcadores de posición, si cambiaste los valores predeterminados que se usan en los comandos de Docker en Implementa el recopilador:

• otel: El nombre que especificaste cuando creaste la red de Docker bridge.
• opentelemetry-collector: El nombre que especificaste cuando ejecutaste el contenedor.

Genera registros

Para generar registros con la herramienta telemetrygen, ejecuta el siguiente 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

Genera métricas

Para generar métricas con la herramienta telemetrygen, ejecuta el siguiente 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

Genera seguimientos

Para generar seguimientos con la herramienta telemetrygen, ejecuta el siguiente 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

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 con 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 la app.
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, configura el primer menú de la entrada Agregación como Ninguno.

   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 seguimiento página:

   Ve al Explorador de seguimiento

   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. Ubica 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 página  Paneles:

   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.