Docker CLI 的 OpenTelemetry

要求: Docker Engine 26.1.0 及更高版本

Docker CLI 支持 OpenTelemetry 观测,用于发出有关命令调用的指标。默认情况下此功能是禁用的。你可以配置 CLI 开始向指定的端点发出指标。这使你能够捕获有关 docker 命令调用的信息,从而更深入地了解你的 Docker 使用情况。

指标导出是可选加入的功能,你可以通过指定指标收集器的目标地址来控制数据的发送位置。

什么是 OpenTelemetry?

OpenTelemetry,简称 OTel,是一个开放的可观测性框架,用于创建和管理遥测数据,例如追踪、指标和日志。OpenTelemetry 与厂商和工具无关,这意味着它可以用于各种可观测性后端。

Docker CLI 中对 OpenTelemetry 观测的支持意味着 CLI 可以使用 Open Telemetry 规范中定义的协议和约定,发出有关发生的事件的信息。

工作原理

Docker CLI 默认不发出遥测数据。只有当你设置了系统环境变量后,Docker CLI 才会尝试向你指定的端点发出 OpenTelemetry 指标。

DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint>

该变量指定 OpenTelemetry 收集器的端点,用于发送有关 docker CLI 调用的遥测数据。要捕获数据,你需要一个在该端点上监听的 OpenTelemetry 收集器。

收集器的目的是接收遥测数据,进行处理,并将其导出到后端。后端是存储遥测数据的地方。你可以选择多种不同的后端,例如 Prometheus 或 InfluxDB。

一些后端直接提供指标可视化工具。另外,你也可以运行一个支持生成更有用图表的专用前端,例如 Grafana。

设置

要开始捕获 Docker CLI 的遥测数据,你需要执行以下操作:

  • 设置 DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT 环境变量,使其指向 OpenTelemetry 收集器端点
  • 运行一个接收 CLI 命令调用信号的 OpenTelemetry 收集器
  • 运行一个后端来存储从收集器接收到的数据

以下 Docker Compose 文件会启动一组服务,以便你开始使用 OpenTelemetry。它包括一个 Docker CLI 可以发送指标的 OpenTelemetry 收集器,以及一个从收集器抓取指标的 Prometheus 后端。

compose.yaml
name: cli-otel
services:
  prometheus:
    image: prom/prometheus
    command:
      - "--config.file=/etc/prometheus/prom.yml"
    ports:
      # Publish the Prometheus frontend on localhost:9091
      - 9091:9090
    restart: always
    volumes:
      # Store Prometheus data in a volume:
      - prom_data:/prometheus
      # Mount the prom.yml config file
      - ./prom.yml:/etc/prometheus/prom.yml
  otelcol:
    image: otel/opentelemetry-collector
    restart: always
    depends_on:
      - prometheus
    ports:
      - 4317:4317
    volumes:
      # Mount the otelcol.yml config file
      - ./otelcol.yml:/etc/otelcol/config.yaml

volumes:
  prom_data:

此服务假设以下两个配置文件与 compose.yaml 并列存在:

  • otelcol.yml
    # Receive signals over gRPC and HTTP
    receivers:
      otlp:
        protocols:
          grpc:
          http:
    
    # Establish an endpoint for Prometheus to scrape from
    exporters:
      prometheus:
        endpoint: "0.0.0.0:8889"
    
    service:
      pipelines:
        metrics:
          receivers: [otlp]
          exporters: [prometheus]
  • prom.yml
    # Configure Prometheus to scrape the OpenTelemetry collector endpoint
    scrape_configs:
      - job_name: "otel-collector"
        scrape_interval: 1s
        static_configs:
          - targets: ["otelcol:8889"]

有了这些文件,请执行以下操作:

  1. 启动 Docker Compose 服务

    $ docker compose up
    
  2. 配置 Docker CLI 将遥测数据导出到 OpenTelemetry 收集器。

    $ export DOCKER_CLI_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
    
  3. 运行 docker 命令以触发 CLI 向 OpenTelemetry 收集器发送指标信号。

    $ docker version
    
  4. 要查看 CLI 创建的遥测指标,请访问 http://localhost:9091/graph 打开 Prometheus 表达式浏览器。

  5. 查询字段中,输入 command_time_milliseconds_total,并执行查询以查看遥测数据。

可用指标

Docker CLI 当前仅导出单个指标 command.time,它测量命令的执行时长(以毫秒为单位)。此指标具有以下属性:

  • command.name: 命令的名称
  • command.status.code: 命令的退出码
  • command.stderr.isatty: 如果 stderr 连接到 TTY,则为 true
  • command.stdin.isatty: 如果 stdin 连接到 TTY,则为 true
  • command.stdout.isatty: 如果 stdout 连接到 TTY,则为 true
页面选项