Desplegar el Collector de OpenTelemetry en Container-Optimized OS

En este documento se describe cómo ejecutar el Collector de OpenTelemetry creado por Google en Container-Optimized OS para recoger registros, métricas y trazas de OTLP de aplicaciones instrumentadas y, a continuación, exportar esos datos a Google Cloud.

Antes de empezar

Para ejecutar el OpenTelemetry Collector, se necesitan los siguientes recursos:

  • Un Google Cloud proyecto con las APIs Cloud Monitoring, Cloud Trace y Cloud Logging habilitadas.

    • Si no tienes ningún Google Cloud proyecto, haz lo siguiente:

      1. En la Google Cloud consola, ve a Nuevo proyecto:

        Crear un proyecto

      2. En el campo Nombre del proyecto, escribe el nombre que quieras darle al proyecto y, a continuación, haz clic en Crear.

      3. Ve a Facturación:

        Ir a Facturación

      4. Selecciona el proyecto que acabas de crear si aún no está seleccionado en la parte superior de la página.

      5. Se te pedirá que elijas un perfil de pagos o que crees uno.

      Las APIs Monitoring, Trace y Logging están habilitadas de forma predeterminada en los proyectos nuevos.

    • Si ya tienes un Google Cloud proyecto, asegúrate de que las APIs Monitoring, Trace y Logging estén habilitadas:

      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

  • Una máquina virtual (VM) de Container-Optimized OS. Si no tienes una VM con Container-Optimized OS, sigue las instrucciones que se indican en Crear y configurar instancias.

  • Una instalación de gcloud. Para obtener información sobre cómo instalar gcloud, consulta Instalar Google Cloud CLI.

Configurar los permisos del recopilador

De forma predeterminada, las VMs de Container-Optimized OS usan la cuenta de servicio predeterminada de Compute Engine, PROJECT_NUMBER-compute@developer.gserviceaccount.com. Esta cuenta de servicio suele tener los roles de gestión de identidades y accesos (IAM) necesarios para escribir las métricas y los registros descritos en este documento:

Si vas a configurar una cuenta de servicio personalizada para tu instancia, consulta el artículo Gestionar el acceso a cuentas de servicio.

Implementar el recopilador

Para ejecutar Google-Built OpenTelemetry Collector, debes proporcionar un archivo de configuración para tu máquina virtual con Container-Optimized OS. Puedes usar la herramienta cloud-init para escribir un archivo de configuración. A continuación, se muestra un archivo cloud-initrecomendado para usar el recolector creado por 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")

    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:

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

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

docker network create -d bridge otel

Ejecuta el contenedor Collector 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.134.0 \
    --config=/etc/config/config.yaml

El comando anterior hace lo siguiente:

  • Ejecuta el contenedor del recolector en segundo plano.
  • Asocia el contenedor Collector a la red de puente otel que has creado anteriormente. Otros contenedores pueden conectarse al puente para enviar telemetría.
  • Monta el archivo de configuración en el contenedor para que se pueda acceder a él y configurar el Collector.

Configurar el recopilador

Te proporcionamos una configuración de OpenTelemetry Collector para que la uses con el Collector creado por Google. Esta configuración se ha diseñado para ofrecer grandes volúmenes de métricas, registros y trazas de OTLP. Esta configuración también está diseñada para evitar problemas habituales de ingesta. Puedes añadir elementos a la configuración, pero te recomendamos que no los elimines.

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

Configuración del recopilador proporcionada

Puedes encontrar la configuración de Collector en el directorio google-built-opentelemetry-collector del repositorio 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

Exportadores

La configuración del recopilador incluye los siguientes exportadores:

  • googlecloud exportador, para registros y trazas. Este exportador está configurado con un nombre de registro predeterminado.

  • googlemanagedprometheus exporter 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 la sección Primeros pasos con el Collector de OpenTelemetry de la documentación de Google Cloud Managed Service para Prometheus.

Procesadores

La configuración del Collector incluye los siguientes procesadores:

  • batch: Configurado para agrupar las solicitudes de telemetría en lotes con el Google Cloud número máximo de entradas por solicitud o con el Google Cloud intervalo mínimo de 5 segundos (lo que ocurra primero).

  • memory_limiter: Limita el uso de memoria del recolector para evitar fallos por falta de memoria eliminando puntos de datos cuando se supera el límite.

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

Receptores

La configuración del recopilador solo incluye el otlpreceptor. Para obtener información sobre cómo instrumentar tus aplicaciones para enviar trazas y métricas de OTLP al endpoint de OTLP del Collector, consulta Elegir un método de instrumentación.

Componentes disponibles

El Collector de OpenTelemetry creado por Google contiene los componentes que la mayoría de los usuarios necesitarán para habilitar una experiencia completa en Observabilidad de Google Cloud. Para ver una lista completa de los componentes disponibles, consulta Components (Componentes) en el repositorio opentelemetry-operations-collector.

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

Generar telemetría

Puede probar su configuración con la herramientatelemetrygen de código abierto. El proyecto OpenTelemetry proporciona un contenedor en el registro de contenedores de GitHub.

Antes de ejecutar los siguientes comandos, sustituya los marcadores de posición si ha cambiado los valores predeterminados utilizados en los comandos de Docker en Implementar el Collector:

  • otel: el nombre que especificaste al crear la red bridge de Docker.
  • opentelemetry-collector: el nombre que especificaste al ejecutar el contenedor.

Generar 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

Generar 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

Generar métricas

Para generar trazas 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

Al cabo de unos minutos, la telemetría generada por la aplicación empieza a fluir a través del Collector a la Google Cloud consola de cada señal.

Ver telemetría

El OpenTelemetry Collector creado por Google envía métricas, registros y trazas 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.

Ver tus métricas

El Collector de OpenTelemetry creado por Google recoge métricas de Prometheus que puede ver con el explorador de métricas. Las métricas recogidas dependen de la instrumentación de la aplicación, aunque el Collector creado por Google también escribe algunas métricas propias.

Para ver las métricas recogidas por el OpenTelemetry Collector creado por Google, haz lo siguiente:

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

    Ve al explorador de métricas.

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

  2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En las configuraciones de App Hub, selecciona el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
  3. En el elemento Métrica, despliega el menú Seleccionar una métrica, introduce Prometheus Target en la barra de filtros y, a continuación, usa los submenús para seleccionar un tipo de recurso y una métrica específicos:
    1. En el menú Recursos activos, selecciona 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 recogidas por el Collector de OpenTelemetry creado por Google tienen el prefijo prometheus.googleapis.com.
    3. Haz clic en Aplicar.

  4. Para añadir filtros que eliminen series temporales de los resultados de la consulta, usa el elemento Filter.

  5. Configure cómo se ven los datos.

    Cuando las mediciones de una métrica son acumulativas, Explorador de métricas normaliza automáticamente los datos medidos por el periodo de alineación, lo que hace que el gráfico muestre una tasa. Para obtener más información, consulta Tipos, clases y conversiones.

    Cuando se miden valores 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, selecciona Ninguna en el primer menú de la entrada Agregación.

    Para obtener más información sobre cómo configurar un gráfico, consulta el artículo Seleccionar métricas al utilizar el explorador de métricas.

Ver tus trazas

Para ver los datos de la traza, haz lo siguiente:

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

    Ir a Explorador de trazas

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

  2. En la barra de herramientas de la Google Cloud consola, selecciona tu Google Cloud proyecto. En el caso de las configuraciones de App Hub, seleccione el proyecto host de App Hub o el proyecto de gestión de la carpeta habilitada para aplicaciones.
  3. En la sección de la tabla de la página, seleccione una fila.

  4. En el gráfico de Gantt del panel Detalles del seguimiento, selecciona un intervalo.

    Se abrirá un panel con información sobre la solicitud registrada. Estos detalles incluyen el método, el código de estado, el número de bytes y el agente de usuario de la persona que llama.

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

    En la pestaña se muestran los registros individuales. Para ver los detalles de la entrada de registro, despliégala. También puede hacer clic en Ver registros y consultar el registro con el Explorador de registros.

Para obtener más información sobre cómo usar el explorador de Cloud Trace, consulta Buscar y explorar trazas.

Consultar los registros

En Explorador de registros, puedes inspeccionar tus registros y ver las trazas asociadas, si las hay.

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

    Ve al Explorador de registros.

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

  2. Busca una entrada de registro de tu aplicación instrumentada. Para ver los detalles, despliega la entrada de registro.

  3. Haz clic en Trazas en una entrada de registro con un mensaje de traza y, a continuación, selecciona Ver detalles de la traza.

    Se abre el panel Detalles de la traza, donde se muestra la traza seleccionada.

Para obtener más información sobre cómo usar el Explorador de registros, consulta el artículo Ver registros con el Explorador de registros.

Observar y depurar el Collector

El Collector de OpenTelemetry creado por Google proporciona automáticamente métricas de autoobservabilidad para ayudarte a monitorizar su rendimiento y asegurar el tiempo de actividad continuo de la canalización de ingestión de OTLP.

Para monitorizar el Collector, instala el panel de control de ejemplo del Collector. Este panel de control ofrece información general sobre varias métricas del recopilador, como el tiempo de actividad, el uso de memoria y las llamadas a la API de Google Cloud Observability.

Para instalar el panel de control, siga estos pasos:

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

    Ve a Paneles.

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

  2. Haz clic en Plantillas de panel de control.
  3. Busca el panel de control OpenTelemetry Collector.
  4. Opcional: Para previsualizar el panel de control, selecciónalo.

  5. Haz clic en Añadir panel de control a tu lista y, a continuación, completa el cuadro de diálogo.

    En el cuadro de diálogo, puedes seleccionar el nombre del panel de control y añadirle etiquetas.

Para obtener más información sobre cómo instalar paneles de control, consulta el artículo Instalar una plantilla de panel de control.