Consul Telemetry Collector 镜像文档

1. 镜像概述

Consul Telemetry Collector是基于OpenTelemetry规范构建的轻量级遥测数据收集器，专注于Consul服务网格的可观测性数据采集与处理。该镜像旨在简化Consul环境中的遥测数据收集流程，支持指标（Metrics）、日志（Logs）和分布式追踪（Traces）的标准化采集，并可灵活导出至各类可观测性平台。其轻量级设计使其适用于边缘环境、容器化部署及资源受限场景。

2. 核心功能与特性

• 轻量级架构：优化资源占用，最小化CPU/内存消耗，适合嵌入式及边缘部署
• Consul原生集成：无缝对接Consul Agent与服务网格，自动发现服务并采集遥测数据
• 全量数据支持：覆盖Consul核心遥测数据类型，包括服务健康指标、流量统计、RPC性能等
• 标准化数据处理：遵循OpenTelemetry规范，支持数据过滤、转换、聚合等处理能力
• 多后端导出：兼容Prometheus、Jaeger、Grafana、Datadog等主流可观测性平台
• 动态配置：支持配置热加载，无需重启即可更新采集规则与导出目标

3. 使用场景与适用范围

• Consul服务网格监控：实时跟踪服务健康状态、请求延迟、错误率等核心指标
• 分布式系统可观测性：为基于Consul构建的微服务架构提供统一遥测数据入口
• OpenTelemetry生态集成：作为专用采集器接入OpenTelemetry可观测性平台
• 混合云环境监控：跨多云、混合云环境中Consul集群的统一遥测数据管理
• DevOps运维优化：通过标准化遥测数据支撑容量规划、性能调优与故障排查

4. 使用方法与配置说明

4.1 基础部署（Docker Run）

bash
docker run -d \
  --name consul-telemetry-collector \
  -v $(pwd)/otel-config.yaml:/etc/otel/config.yaml \
  -e CONSUL_ADDR=[***] \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=[***] \
  -p 8889:8889 \
  hashicorp/consul-telemetry-collector:latest

参数说明：

• -v：挂载本地配置文件到容器内默认配置路径
• -e：设置环境变量（Consul地址、导出端点等）
• -p：暴露Prometheus指标端口（如需本地采集）

4.2 Docker Compose配置

yaml
version: '3.8'
services:
  consul-agent:
    image: hashicorp/consul:latest
    command: agent -dev -client=0.0.0.0
    ports:
      - "8500:8500"

  consul-telemetry-collector:
    image: hashicorp/consul-telemetry-collector:latest
    volumes:
      - ./otel-config.yaml:/etc/otel/config.yaml
    environment:
      - CONSUL_ADDR=[***]
      - OTEL_EXPORTER_OTLP_ENDPOINT=[***]
      - LOG_LEVEL=info
    depends_on:
      - consul-agent
    ports:
      - "8889:8889"  # Prometheus指标暴露端口

  otel-collector:
    image: otel/opentelemetry-collector-contrib:latest
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
    ports:
      - "4317:4317"  # OTLP gRPC接收端口

4.3 环境变量配置

4.4 配置文件详解

通过挂载配置文件（推荐）自定义采集规则，典型配置结构如下：

yaml
receivers:
  consul:
    endpoint: ${CONSUL_ADDR}          # 从环境变量获取Consul地址
    collection_interval: ${COLLECTION_INTERVAL}  # 采集间隔
    metrics:
      include: ["consul.service.*", "consul.client.*"]  # 包含指标
      exclude: ["consul.debug.*"]     # 排除调试指标

processors:
  batch:                              # 批量处理优化网络传输
    timeout: 2s
    send_batch_size: 1024
  filter:                             # 过滤特定指标
    metrics:
      include:
        metric_names: ["consul.service.health", "consul.client.rpc"]

exporters:
  otlp:                               # 导出至OTLP后端
    endpoint: ${OTEL_EXPORTER_OTLP_ENDPOINT}
    tls:
      insecure: true                  # 开发环境禁用TLS验证
  prometheus:                         # 导出至Prometheus
    endpoint: ":8889"                 # 暴露Prometheus指标端点
    metric_expiration: 12h

service:
  pipelines:
    metrics:
      receivers: [consul]
      processors: [batch, filter]
      exporters: [otlp, prometheus]

4.5 数据导出示例

导出至Prometheus

1. 配置prometheus导出器暴露端点（如:8889）
2. 在Prometheus配置中添加抓取任务：

yaml
scrape_configs:
  - job_name: 'consul-telemetry'
    static_configs:
      - targets: ['consul-telemetry-collector:8889']

导出至Grafana Cloud

通过OTLP协议对接Grafana Cloud：

yaml
exporters:
  otlp/grafana:
    endpoint: "otlp-gateway-prod-us-central-0.grafana.net:4317"
    headers:
      authorization: "Basic <base64-encoded-api-key>"

5. 注意事项

• 确保Consul Agent已启用遥测功能（默认启用，通过telemetry配置段调整）
• 生产环境建议使用配置文件挂载而非环境变量注入敏感信息
• 高流量场景下可增加collection_interval减少采集频率，或调整batch处理器参数
• 监控容器资源使用，推荐配置资源限制：--memory=256m --cpus=0.5
• 版本兼容性：需与Consul版本（1.11+）及OpenTelemetry规范（v1.0+）匹配