aws-otel-collector-fork 镜像中文技术文档

1. 镜像概述和主要用途

1.1 概述

本镜像为 amazon/aws-otel-collector 的容器分支版本（fork），基于 OpenTelemetry Collector 构建，专注于遥测数据（指标、日志、分布式追踪）的收集、处理与导出。该镜像继承了官方 AWS OpenTelemetry Collector 的核心能力，并可能包含特定场景下的定制化优化，适用于云原生环境中应用与基础设施的可观测性数据管理。

1.2 主要用途

• 统一收集来自应用、容器、AWS 服务的遥测数据（指标、日志、追踪）；
• 对数据进行过滤、转换、聚合等处理；
• 将处理后的数据导出至目标系统（如 AWS CloudWatch、Amazon X-Ray、Prometheus、Jaeger 等）；
• 作为云原生应用可观测性架构的核心组件，支撑监控、故障排查与性能分析。

2. 核心功能和特性

2.1 数据全链路处理

• 多源数据收集：支持通过 receivers 组件采集多种数据源，包括 HTTP/gRPC 协议、Kubernetes 指标、Prometheus 指标、Jaeger 追踪、AWS X-Ray 追踪等。
• 灵活数据处理：通过 processors 组件实现数据过滤（如按属性排除）、转换（如重命名指标）、聚合（如求和/平均）、采样（追踪数据降采样）等操作。
• 多目标导出：通过 exporters 组件将处理后的数据导出至 AWS 服务（CloudWatch Metrics/Logs、X-Ray）、开源工具（Prometheus、Grafana、Jaeger）或第三方系统。

2.2 AWS 深度集成

• 原生支持 AWS 服务认证（IAM 角色、Access Key），无需额外配置即可对接 AWS 可观测性服务；
• 内置 AWS 特定 receivers/exporters，如 aws*** exporter、cloudwatchlogs exporter、awscontainerinsightreceiver 等；
• 兼容 AWS ECS/EKS 环境，可自动发现容器与服务元数据。

2.3 高可配置性与扩展性

• 通过 YAML 配置文件定义数据处理 pipelines（receivers → processors → exporters），支持自定义组件组合；
• 支持热重载配置（部分组件），无需重启容器即可更新配置；
• 可通过插件扩展功能，适配特定业务场景的数据需求。

2.4 轻量与高性能

• 基于容器化设计，资源占用低，支持在边缘节点、Kubernetes Pod 等受限环境部署；
• 异步数据处理架构，支持高吞吐量场景，避免成为系统性能瓶颈。

3. 使用场景和适用范围

3.1 云原生应用监控

• 部署于 Kubernetes 集群，收集微服务架构中的分布式追踪数据、Pod 指标与应用日志，统一导出至 Prometheus + Grafana 或 AWS CloudWatch。

3.2 AWS 服务监控

• 作为 AWS 环境中的遥测数据网关，收集 EC2、RDS、Lambda 等服务的指标与日志，结合 CloudWatch 实现全栈监控。

3.3 混合云环境可观测性

• 在混合云或多云架构中，统一收集来自 AWS、Azure、GCP 及私有云的遥测数据，标准化数据格式后导出至集中化观测平台。

3.4 分布式追踪分析

• 配合 OpenTelemetry 客户端 SDK，收集应用产生的分布式追踪数据，通过 X-Ray 或 Jaeger 可视化调用链路，定位跨服务性能问题。

4. 使用方法和配置说明

4.1 获取镜像

通过 Docker Hub 或私有仓库拉取镜像（假设镜像标签为 my-fork/aws-otel-collector:latest）：

docker pull my-fork/aws-otel-collector:latest

4.2 基本运行示例（docker run）

通过 docker run 启动容器，需挂载配置文件并配置必要环境变量（如 AWS 区域）：

4.2.1 本地配置文件挂载

docker run -d \
  --name aws-otel-collector \
  -v /path/to/local/config.yaml:/etc/otel-collector-config.yaml \  # 挂载本地配置文件
  -e AWS_REGION=us-east-1 \                                       # AWS 区域
  -e AWS_ACCESS_KEY_ID=AKIAEXAMPLE \                              # AWS 访问密钥（可选，若使用 IAM 角色则无需）
  -e AWS_SECRET_ACCESS_KEY=secret \                               # AWS 密钥（可选）
  -p 4317:4317 \                                                  # gRPC 接收端口（默认）
  -p 4318:4318 \                                                  # HTTP 接收端口（默认）
  my-fork/aws-otel-collector:latest \
  --config=/etc/otel-collector-config.yaml                        # 指定配置文件路径

4.2.2 配置文件示例（config.yaml）

以下为基础配置示例，定义一个 "metrics" pipeline（收集 Prometheus 指标并导出至 CloudWatch）：

receivers:
  prometheus:
    config:
      scrape_configs:
        - job_name: 'otel-collector'
          static_configs:
            - targets: ['localhost:8888']  # 采集 Collector 自身指标

processors:
  batch:  # 批量处理数据，优化网络传输

exporters:
  awscloudwatchmetrics:  # 导出至 CloudWatch Metrics
    region: ${AWS_REGION}
    namespace: 'MyApp/Metrics'

service:
  pipelines:
    metrics:
      receivers: [prometheus]
      processors: [batch]
      exporters: [awscloudwatchmetrics]

4.3 Docker Compose 配置示例

创建 docker-compose.yaml，定义 Collector 服务及依赖（如 Prometheus，可选）：

version: '3.8'
services:
  otel-collector:
    image: my-fork/aws-otel-collector:latest
    container_name: otel-collector
    volumes:
      - ./config.yaml:/etc/otel-collector-config.yaml  # 挂载本地配置文件
    environment:
      - AWS_REGION=us-east-1
      - AWS_ACCESS_KEY_ID=AKIAEXAMPLE
      - AWS_SECRET_ACCESS_KEY=secret
    ports:
      - "4317:4317"  # gRPC 接收端口
      - "4318:4318"  # HTTP 接收端口
    command: ["--config", "/etc/otel-collector-config.yaml"]
    restart: unless-stopped

启动服务：

docker-compose up -d

4.4 配置文件说明

配置文件是 Collector 的核心，需定义以下关键部分：

• receivers：数据输入源，如 prometheus、jaeger、aws***、filelog 等；
• processors：数据处理组件，如 batch（批量）、filter（过滤）、metricstransform（指标转换）等；
• exporters：数据输出目标，如 awscloudwatchmetrics、aws***、prometheusremotewrite、logging（控制台输出）等；
• service：定义 pipelines，将 receivers、processors、exporters 组合为完整数据链路（如 metrics、logs、traces 三类 pipeline）。

详细配置语法与组件说明可参考 OpenTelemetry Collector 官方文档 及 AWS OTel Collector 文档。

5. 配置参数

Collector 支持通过命令行参数调整运行行为，常用参数如下：

6. 环境变量

容器运行时可通过环境变量注入配置，常用变量如下：

7. 注意事项

• 配置文件权限：挂载本地配置文件时，需确保容器内用户（通常为 otelcol）对文件有读取权限，避免因权限不足导致配置加载失败。
• AWS 认证优先顺序：Collector 优先使用 IAM 角色（如 ECS Task Role、EKS Service Account Role），其次是环境变量 AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY，最后是本地 AWS 凭证文件（~/.aws/credentials）。
• 资源限制：根据数据吞吐量调整容器 CPU/内存资源（如 Kubernetes 中的 resources.limits），避免 OOM 或性能瓶颈。
• 版本兼容性：该镜像为 amazon/aws-otel-collector 的分支版本，使用前需确认与目标 OpenTelemetry 组件（如客户端 SDK）的版本兼容性。
• 配置验证：启动前建议通过 docker run --rm my-fork/aws-otel-collector:latest --config=config.yaml --validate 验证配置文件语法正确性。