site24x7/opentelemetry-collector

OpenTelemetry Collector with Site24x7 Exporter 镜像文档

1. 镜像概述和主要用途

本镜像是基于 OpenTelemetry Collector 构建的专用版本，集成了 Site24x7 Exporter 组件。OpenTelemetry Collector 是一个开源的可观测性数据处理系统，支持接收、处理、聚合和导出遥测数据（指标、日志、追踪）；Site24x7 Exporter 则负责将处理后的遥测数据转换为 Site24x7 平台兼容格式，并导出至该平台进行监控、分析与告警。

主要用途：作为数据管道中枢，连接分布式系统中的遥测数据源（如应用、服务、基础设施）与 Site24x7 监控平台，实现统一的可观测性数据采集与上报。

2. 核心功能和特性

2.1 基础功能

• 多源数据接收：支持通过 OTLP、Prometheus、Jaeger、Zipkin 等多种协议接收来自应用、服务或基础设施的遥测数据（指标、追踪、日志）。
• 数据处理与聚合：提供丰富的内置处理器（如批处理、过滤、转换、采样），支持对原始数据进行清洗、脱敏、聚合等预处理。
• 高可靠性：支持数据本地缓存、重试机制，避免数据丢失。

2.2 Site24x7 Exporter 特性

• Site24x7 平台深度集成：与 Site24x7 APM 平台无缝对接，支持将遥测数据直接导入 Site24x7 进行可视化与告警配置。
• 多类型数据导出：支持导出指标（Metrics）和分布式追踪（Traces）数据，覆盖应用性能、系统资源、业务指标等场景。
• 灵活配置：支持自定义服务名称、标签、导出频率等参数，适配不同监控需求。

3. 使用场景和适用范围

3.1 典型使用场景

• 微服务架构监控：采集分布式微服务的调用链追踪数据、性能指标（如延迟、错误率、吞吐量），通过 Site24x7 实现服务健康状态实时监控。
• 云原生应用可观测性：在 Kubernetes 等容器编排环境中，统一收集容器、Pod、节点的遥测数据，导出至 Site24x7 进行集群级监控分析。
• 分布式系统问题定位：通过追踪数据关联应用日志和指标，快速定位跨服务调用中的性能瓶颈或错误根源。
• 混合云环境数据聚合：整合多云（公有云、私有云）或混合架构下的分散遥测数据，实现统一监控视图。

3.2 适用范围

• 技术栈：支持所有兼容 OpenTelemetry 规范的应用（如 Java、Python、Go、Node.js 等）。
• 部署环境：容器化环境（Docker、Kubernetes）、虚拟机、物理机均可部署。
• 数据规模：支持中小至大规模遥测数据采集（通过水平扩展 Collector 实例实现高吞吐）。

4. 使用方法和配置说明

4.1 获取镜像

通过 Docker Hub 或私有镜像仓库拉取镜像（假设镜像标签为 otelcol-site24x7:latest）：

bash
docker pull otelcol-site24x7:latest

4.2 配置文件说明

OpenTelemetry Collector 通过 YAML 配置文件定义数据采集流程，核心包括 receivers（数据接收）、processors（数据处理）、exporters（数据导出）和 service（服务管道）四部分。需重点配置 exporters.site24x7 部分。

4.2.1 配置文件结构示例

yaml
# otel-collector-config.yaml
receivers:
  # 示例：接收 OTLP 协议数据（默认端口 4317/gRPC, 4318/HTTP）
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  # 示例：批处理数据以提高导出效率
  batch:
    send_batch_size: 1000
    timeout: 10s

exporters:
  # Site24x7 Exporter 配置
  site24x7:
    # Site24x7 API 密钥（必填，从 Site24x7 控制台获取）
    api_key: "YOUR_SITE24X7_API_KEY"
    # 服务名称（可选，默认为 "otel-collector"，用于在 Site24x7 平台标识数据源）
    service_name: "my-app-service"
    # 导出端点（可选，默认使用 Site24x7 官方端点，私有化部署时需指定）
    endpoint: "https://www.site24x7.com/api/v2/metrics"
    # 超时时间（可选，默认 10s）
    timeout: 15s
    # 自定义标签（可选，添加至所有导出指标）
    resource_attributes:
      env: "production"
      team: "backend"

service:
  pipelines:
    # 指标数据管道：接收 OTLP 指标 -> 批处理 -> 导出至 Site24x7
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [site24x7]
    # 追踪数据管道：接收 OTLP 追踪 -> 批处理 -> 导出至 Site24x7
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [site24x7]

4.3 运行示例

4.3.1 Docker 命令行运行

将本地配置文件挂载至容器，并启动 Collector：

bash
docker run -d \
  --name otel-collector-site24x7 \
  -p 4317:4317  # OTLP gRPC 接收端口 \
  -p 4318:4318  # OTLP HTTP 接收端口 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \
  otelcol-site24x7:latest \
  --config=/etc/otelcol/config.yaml

4.3.2 Docker Compose 配置

创建 docker-compose.yml：

yaml
version: '3.8'
services:
  otel-collector:
    image: otelcol-site24x7:latest
    container_name: otel-collector-site24x7
    ports:
      - "4317:4317"  # OTLP gRPC
      - "4318:4318"  # OTLP HTTP
    volumes:
      - ./otel-collector-config.yaml:/etc/otelcol/config.yaml
    command: ["--config=/etc/otelcol/config.yaml"]
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

5. 配置参数说明

5.1 Site24x7 Exporter 核心参数

5.2 其他通用参数（Collector 全局配置）

6. 验证与故障排查

6.1 验证数据导出

1. 启动 Collector 后，检查容器日志确认无错误：

   bash
   docker logs otel-collector-site24x7
   

   若日志中出现 Successfully exported metrics to Site24x7 或 Successfully exported traces to Site24x7，表示数据导出正常。

2. 登录 Site24x7 控制台，在 APM > 指标浏览器 或 分布式追踪 页面查看是否有新数据流入。

6.2 常见故障排查

• 认证失败：日志出现 401 Unauthorized，检查 api_key 是否正确或未过期。
• 数据接收异常：确认数据源（如应用）是否正确配置 OTLP 端点（Collector 的 4317/4318 端口），且网络连通。
• 内存溢出：日志出现 memory limiter exceeded，需调整 memory_limiter 配置或优化数据采样率。