AWS Distro for OpenTelemetry Collector 镜像文档

1. 镜像概述和主要用途

AWS Distro for OpenTelemetry Collector（简称 AWS OTel Collector）是由 Amazon 分发的、AWS 官方支持的上游 OpenTelemetry Collector 版本。该镜像旨在提供与 OpenTelemetry 社区组件的兼容性，同时针对 AWS 云环境进行优化，支持在 AWS 计算平台上无缝部署和运行。其核心用途是收集、处理和导出遥测数据（指标、追踪、日志），并将数据转发至 AWS CloudWatch（Metrics、Traces、Logs）及其他支持的后端服务，帮助用户实现统一的可观测性管理。

2. 核心功能和特性

2.1 核心功能

• AWS 官方支持：基于上游 OpenTelemetry Collector 构建，由 AWS 提供技术支持和维护。
• 社区组件兼容性：支持 OpenTelemetry 社区的精选组件（Receivers、Processors、Exporters 等），兼顾社区生态与 AWS 云服务集成。
• AWS 平台适配：完全兼容 AWS 主流计算服务，包括 Amazon EC2、Amazon ECS、Amazon EKS 等。
• 多后端数据导出：支持将遥测数据发送至 AWS CloudWatch（Metrics/Traces/Logs），同时兼容其他第三方可观测性后端（如 Prometheus、Jaeger 等）。

2.2 许可证

镜像遵循 Apache 2.0 开源许可证，允许自由使用、修改和分发。

3. 使用场景和适用范围

3.1 适用场景

• AWS 环境遥测数据收集：在 EC2、ECS、EKS 等 AWS 计算资源中部署，统一收集应用或基础设施的指标、追踪和日志数据。
• CloudWatch 数据集成：将分布式系统的遥测数据集中转发至 CloudWatch，实现基于 AWS 原生工具的监控和告警。
• 混合后端数据导出：同时向 AWS 服务和第三方可观测性平台（如开源工具或商业 APM 系统）导出数据，满足多平台监控需求。

3.2 适用范围

• 用户类型：AWS 云服务用户、采用 OpenTelemetry 标准的可观测性实践团队。
• 部署环境：Amazon EC2 实例、Amazon ECS 容器集群、Amazon EKS Kubernetes 集群。
• 数据类型：需处理和导出的指标（Metrics）、分布式追踪（Traces）、日志（Logs）等遥测数据。

4. 使用方法和配置说明

4.1 前提条件

• 已安装 Docker 或容器运行时环境。
• （可选）AWS 凭证配置：若需向 CloudWatch 导出数据，需通过 IAM 角色（EC2/ECS/EKS 实例角色）或访问密钥（AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY）授予容器对 CloudWatch 的写入权限。
• 配置文件：需准备 OpenTelemetry Collector 配置文件（otel-collector-config.yaml），定义数据采集、处理和导出规则。

4.2 Docker 快速部署（docker run）

通过 docker run 命令直接启动容器，需挂载本地配置文件并设置必要环境变量（如 AWS 区域）。

示例命令：

docker run -d \
  --name aws-otel-collector \
  -v /path/to/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \  # 挂载本地配置文件
  -e AWS_REGION=us-west-2 \  # 设置 AWS 区域
  -p 4317:4317 \  # OTLP gRPC 接收端口
  -p 4318:4318 \  # OTLP HTTP 接收端口
  public.ecr.aws/aws-observability/aws-otel-collector:latest

说明：镜像地址为 AWS ECR Public 仓库，具体版本可替换 latest 为指定标签（如 v0.86.0），版本列表见 AWS OTel Collector 发布页。

4.3 Docker Compose 部署

通过 docker-compose.yml 定义服务，简化多容器协同或配置管理。

示例 docker-compose.yml：

version: '3.8'
services:
  aws-otel-collector:
    image: public.ecr.aws/aws-observability/aws-otel-collector:latest
    container_name: aws-otel-collector
    restart: always
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml  # 挂载配置文件
    environment:
      - AWS_REGION=us-west-2  # AWS 区域
      # 若未使用 IAM 角色，需配置访问凭证（生产环境建议优先使用 IAM 角色）
      # - AWS_ACCESS_KEY_ID=AKIAEXAMPLE
      # - AWS_SECRET_ACCESS_KEY=secret
    ports:
      - "4317:4317"  # OTLP gRPC 接收端口
      - "4318:4318"  # OTLP HTTP 接收端口
      - "8888:8888"  # 健康检查端口（可选）

启动命令：

docker-compose up -d

4.4 配置文件说明

配置文件（otel-collector-config.yaml）是核心，需定义数据采集（Receivers）、处理（Processors）、导出（Exporters）和服务（Service）逻辑。以下为向 CloudWatch 导出数据的基础配置示例：

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

receivers:
  otlp:  # 接收 OTLP 格式数据（默认端口 4317/grpc、4318/http）
    protocols:
      grpc:
      http:

processors:
  batch:  # 批量处理数据，优化网络传输效率
    timeout: 10s
    send_batch_size: 1024

exporters:
  awscloudwatchlogs:  # 导出日志至 CloudWatch Logs
    log_group_name: /aws/otel-collector/example
    log_stream_name: {service.name}-{host.name}
  awscloudwatchmetrics:  # 导出指标至 CloudWatch Metrics
    namespace: AWSOTelExample
  aws***:  # 导出追踪数据至 CloudWatch X-Ray
    region: us-west-2

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [awscloudwatchlogs]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [awscloudwatchmetrics]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [aws***]

详细配置参数可参考 AWS OTel Collector 官方文档。

4.5 环境变量说明

容器运行时支持通过环境变量调整配置，常用变量如下：

5. 参考链接

• AWS OTel Collector 开发者门户
• GitHub 仓库
• AWS CloudWatch 集成文档