amazon/aws-otel-collector

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 区域）。

示例命令：

bash
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），版本列表见 https://github.com/aws-observability/aws-otel-collector/releases%E3%80%82

4.3 Docker Compose 部署

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

示例 docker-compose.yml：

yaml
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"  # 健康检查端口（可选）

启动命令：

bash
docker-compose up -d

4.4 配置文件说明

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

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

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
  awsxray:  # 导出追踪数据至 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: [awsxray]

详细配置参数可参考 https://aws-observability.github.io/otel.aws/docs/components/collector%E3%80%82

4.5 环境变量说明

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

5. 参考链接

• https://aws-observability.github.io/otel.aws/
• https://github.com/aws-observability/aws-otel-collector
• AWS CloudWatch 集成文档