OpenTelemetry Collector Contrib (开发/CI构建版) 镜像文档

一、镜像概述和主要用途

镜像名称

otel/opentelemetry-collector-contrib (开发/CI构建版)

概述

本镜像为 opentelemetry-collector-contrib 项目的开发/持续集成（CI）构建版本，用于开发、测试及CI流程中验证代码变更和新功能。相较于正式发布版，该镜像包含项目最新开发进度的代码，提供尚未正式发布的功能和修复，适合开发环境和预发布验证场景。

二、核心功能和特性

1. 扩展组件集合
   包含社区贡献的丰富组件，覆盖更多接收器（Receivers）、处理器（Processors）、导出器（Exporters）和扩展（Extensions），支持与各类观测性工具（如Prometheus、Jaeger、Zipkin、AWS CloudWatch等）的集成。

2. 开发测试优化
   针对开发场景优化，支持快速验证新功能、调试组件交互逻辑，包含详细日志输出和调试工具集成。

3. CI流程适配
   适合作为CI流水线的构建依赖，用于自动化验证代码提交后的功能完整性和兼容性。

4. 最新构建版本
   基于项目主分支或开发分支最新代码构建，包含尚未纳入正式发布的特性和修复。

三、使用场景和适用范围

1. 开发环境功能测试
   开发人员在本地环境测试opentelemetry-collector-contrib的新功能或自定义组件。

2. CI流程验证
   在持续集成流程中，用于验证代码变更对Collector功能的影响，确保提交代码的兼容性和稳定性。

3. 自定义Collector开发
   基于开发版镜像构建包含自定义逻辑的Collector，加速开发迭代。

4. 新组件兼容性测试
   验证第三方工具与Collector社区贡献组件的兼容性（如测试新数据库的接收器插件）。

四、使用方法和配置说明

4.1 获取镜像

通过Docker Hub拉取最新开发版镜像：

docker pull otel/opentelemetry-collector-contrib:latest

4.2 基本运行命令

镜像运行需指定配置文件，通过挂载本地配置文件到容器内实现自定义配置：

docker run -v /path/to/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml otel/opentelemetry-collector-contrib:latest --config=/etc/otelcol-contrib/config.yaml

4.3 配置文件说明

配置文件采用YAML格式，包含receivers（接收器）、processors（处理器）、exporters（导出器）、extensions（扩展）和service（服务）五大核心模块。

配置示例（otel-collector-config.yaml）：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:
    timeout: 1s
    send_batch_size: 1024

exporters:
  logging:
    loglevel: debug

extensions:
  health_check:
    endpoint: 0.0.0.0:13133

service:
  extensions: [health_check]
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [logging]

五、Docker部署方案示例

5.1 docker run 命令示例

# 挂载本地配置文件并运行开发版Collector
docker run -d \
  --name otel-collector-dev \
  -p 4317:4317 \  # OTLP gRPC端口
  -p 4318:4318 \  # OTLP HTTP端口
  -p 13133:13133 \ # 健康检查端口
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  otel/opentelemetry-collector-contrib:latest \
  --config=/etc/otelcol-contrib/config.yaml

5.2 docker-compose 配置示例

创建 docker-compose.yml 文件：

version: '3.8'

services:
  otel-collector-dev:
    image: otel/opentelemetry-collector-contrib:latest
    container_name: otel-collector-dev
    ports:
      - "4317:4317"  # OTLP gRPC
      - "4318:4318"  # OTLP HTTP
      - "13133:13133"  # Health check
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml
    command: ["--config=/etc/otelcol-contrib/config.yaml"]
    restart: unless-stopped

启动服务：

docker-compose up -d

六、注意事项

1. 稳定性说明
   本镜像为开发/CI构建版，包含未经过充分测试的代码，可能存在功能不稳定或兼容性问题，不建议用于生产环境。生产环境请使用项目正式发布的镜像版本。

2. 配置文件格式
   配置文件需遵循 OpenTelemetry Collector 配置规范，具体组件参数可参考 opentelemetry-collector-contrib 文档。

3. 资源限制
   运行时建议根据实际数据量和处理需求配置CPU/内存限制，避免资源耗尽。例如，在docker-compose中添加 deploy.resources 配置。

4. 更新频率
   开发版镜像随项目代码提交频繁更新，如需固定版本，可通过提交哈希或分支标签指定（如 otel/opentelemetry-collector-contrib:sha-xxxxxx）。

七、参考链接

• opentelemetry-collector-contrib 项目仓库
• OpenTelemetry 官方文档
• 贡献指南