Compartir comentarios
Las respuestas se generan en base a la documentación.

OpenTelemetry para la CLI de Docker

Tabla de contenidos
Requiere: Docker Engine 26.1.0 y posterior

La CLI de Docker admite instrumentación OpenTelemetry para emitir métricas sobre las invocaciones de comandos. Esta función está deshabilitada de forma predeterminada. Puedes configurar la CLI para que comience a emitir métricas al punto de conexión (endpoint) que especifiques. Esto te permite capturar información sobre las invocaciones de tus comandos de docker para obtener un mayor conocimiento de tu uso de Docker.

La exportación de métricas es opcional (opt-in) y tú controlas a dónde se envían los datos especificando la dirección de destino del colector de métricas.

¿Qué es OpenTelemetry?

OpenTelemetry, u OTel para abreviar, es un framework de observabilidad abierto para crear y gestionar datos de telemetría, como trazas (traces), métricas y registros (logs). OpenTelemetry es independiente de proveedores y herramientas, lo que significa que se puede utilizar con una amplia variedad de backends de observabilidad.

El soporte para la instrumentación de OpenTelemetry en la CLI de Docker significa que la CLI puede emitir información sobre los eventos que tienen lugar, utilizando los protocolos y convenciones definidos en la especificación de OpenTelemetry.

Cómo funciona

La CLI de Docker no emite datos de telemetría de forma predeterminada. Solo si has establecido una variable de entorno en tu sistema, la CLI de Docker intentará emitir métricas de OpenTelemetry al punto de conexión que especifiques.

DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint>

La variable especifica el punto de conexión de un colector de OpenTelemetry al que se deben enviar los datos de telemetría sobre la invocación de la CLI de docker. Para capturar los datos, necesitarás un colector de OpenTelemetry escuchando en ese punto de conexión.

El propósito de un colector es recibir los datos de telemetría, procesarlos y exportarlos a un backend. El backend es donde se almacenan los datos de telemetría. Puedes elegir entre varios backends diferentes, como Prometheus o InfluxDB.

Algunos backends proporcionan herramientas para visualizar las métricas directamente. Alternativamente, también puedes ejecutar un frontend dedicado con soporte para generar gráficos más útiles, como Grafana.

Configuración

Para comenzar a capturar datos de telemetría para la CLI de Docker, deberás:

  • Establecer la variable de entorno DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT para que apunte al punto de conexión de un colector de OpenTelemetry.
  • Ejecutar un colector de OpenTelemetry que reciba las señales de las invocaciones de comandos de la CLI.
  • Ejecutar un backend para almacenar los datos recibidos del colector.

El siguiente archivo de Docker Compose inicializa un conjunto de servicios para comenzar con OpenTelemetry. Incluye un colector de OpenTelemetry al que la CLI puede enviar métricas y un backend de Prometheus que recopila (scrapes) las métricas del colector.

compose.yaml
name: cli-otel
services:
  prometheus:
    image: prom/prometheus
    command:
      - "--config.file=/etc/prometheus/prom.yml"
    ports:
      # Publicar el frontend de Prometheus en localhost:9091
      - 9091:9090
    restart: always
    volumes:
      # Almacenar los datos de Prometheus en un volumen:
      - prom_data:/prometheus
      # Montar el archivo de configuración prom.yml
      - ./prom.yml:/etc/prometheus/prom.yml
  otelcol:
    image: otel/opentelemetry-collector
    restart: always
    depends_on:
      - prometheus
    ports:
      - 4317:4317
    volumes:
      # Montar el archivo de configuración otelcol.yml
      - ./otelcol.yml:/etc/otelcol/config.yaml

volumes:
  prom_data:

Este servicio asume que los siguientes dos archivos de configuración existen junto a compose.yaml:

  • otelcol.yml
    # Recibir señales a través de gRPC y HTTP
receivers:
  otlp:
    protocols:
      grpc:
      http:

# Establecer un punto de conexión para que Prometheus recopile datos
exporters:
  prometheus:
    endpoint: "0.0.0.0:8889"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheus]
  • prom.yml
    # Configurar Prometheus para recopilar datos del punto de conexión del colector de OpenTelemetry
scrape_configs:
  - job_name: "otel-collector"
    scrape_interval: 1s
    static_configs:
      - targets: ["otelcol:8889"]

Con estos archivos en su lugar:

  1. Inicia los servicios de Docker Compose:

    $ docker compose up

  2. Configura la CLI de Docker para exportar la telemetría al colector de OpenTelemetry.

    $ export DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

  3. Ejecuta un comando de docker para activar el envío de una señal de métrica por parte de la CLI al colector de OpenTelemetry.

    $ docker version

  4. Para ver las métricas de telemetría creadas por la CLI, abre el explorador de expresiones de Prometheus accediendo a http://localhost:9091/graph.

  5. En el campo Query, introduce command_time_milliseconds_total y ejecuta la consulta para ver los datos de telemetría.

Métricas disponibles

La CLI de Docker exporta una única métrica, command.time, que mide la duración de la ejecución de un comando en milisegundos. Esta métrica tiene los siguientes atributos:

  • command.name: el nombre del comando
  • command.status.code: el código de salida del comando
  • command.stderr.isatty: verdadero si stderr está conectado a una TTY
  • command.stdin.isatty: verdadero si stdin está conectado a una TTY
  • command.stdout.isatty: verdadero si stdout está conectado a una TTY