Blue Matador Agent Docker 镜像文档

1. 镜像概述和主要用途

Blue Matador Agent 是 Blue Matador 平台提供的轻量级数据收集和监控代理程序，旨在与容器化环境（尤其是 Kubernetes 集群）集成，用于实时收集、处理和转发系统及应用指标至 Blue Matador 监控平台，支持用户实现对基础设施和应用的可视化监控与告警。

2. 核心功能和特性

2.1 核心功能

• 指标收集：支持通过多种协议（如 StatsD）收集系统、容器及应用指标。
• Kubernetes 集成：原生适配 Kubernetes 环境，可自动发现集群内资源（Pod、Node、Service 等）并收集相关指标。
• 数据转发：将收集的指标标准化后转发至 Blue Matador 平台，支持数据压缩和加密传输。
• 轻量级设计：基于 Alpine Linux 构建，镜像体积小，资源占用低（CPU/内存消耗可控）。

2.2 关键特性

• 低侵入性：无需修改应用代码即可实现指标采集。
• 协议支持：内置 StatsD 协议支持（默认暴露 UDP 8125 端口，兼容 StatsD 客户端）。
• 自动配置：支持通过环境变量或配置文件灵活调整采集规则和转发目标。

3. 使用场景和适用范围

3.1 主要使用场景

• Kubernetes 集群监控：部署于 Kubernetes 集群内，作为 DaemonSet 或 Deployment 运行，监控集群节点、Pod 及应用性能。
• 应用性能监控（APM）：收集应用输出的业务指标（如请求延迟、错误率），辅助性能问题定位。
• 基础设施监控：监控主机资源（CPU、内存、磁盘 I/O）及网络流量。

3.2 适用范围

• 容器化应用环境（Docker、Kubernetes）。
• 需要对接 Blue Matador 监控平台的用户。
• 采用 StatsD 协议输出指标的应用场景。

4. 使用方法和部署示例

4.1 前置条件

• 已注册 Blue Matador 平台账号，获取 API 密钥（用于 agent 与平台认证）。
• 目标环境需支持 Docker 或 Kubernetes。

4.2 Docker 直接运行

基础命令

bash
docker run -d \
  --name bluematador-agent \
  -p 8125:8125/udp \  # 暴露 StatsD 端口，接收指标数据
  -e BLUEMATADOR_API_KEY="your-api-key" \  # Blue Matador 平台 API 密钥
  -e COLLECTION_INTERVAL="10s" \  # 指标采集间隔（默认 10s）
  bluematador/agent:latest

挂载自定义配置文件

若需通过配置文件自定义采集规则，可挂载本地配置文件至容器内（假设配置文件路径为 /etc/bluematador/config.yaml）：

bash
docker run -d \
  --name bluematador-agent \
  -p 8125:8125/udp \
  -v /path/to/local/config.yaml:/etc/bluematador/config.yaml \  # 挂载配置文件
  -e BLUEMATADOR_CONFIG_FILE="/etc/bluematador/config.yaml" \  # 指定配置文件路径
  bluematador/agent:latest

4.3 Docker Compose 部署

创建 docker-compose.yml 文件：

yaml
version: '3'
services:
  bluematador-agent:
    image: bluematador/agent:latest
    container_name: bluematador-agent
    ports:
      - "8125:8125/udp"  # StatsD 端口
    environment:
      - BLUEMATADOR_API_KEY=your-api-key  # 替换为实际 API 密钥
      - COLLECTION_INTERVAL=10s  # 指标采集间隔
      - LOG_LEVEL=info  # 日志级别（debug/info/warn/error）
    volumes:
      - ./config.yaml:/etc/bluematador/config.yaml  # 可选：挂载自定义配置
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

5. 配置说明

5.1 环境变量

5.2 配置文件

若通过 BLUEMATADOR_CONFIG_FILE 指定自定义配置文件，文件格式为 YAML，示例如下（具体字段需参考***文档）：

yaml
# 指标采集规则
collection:
  kubernetes:
    enabled: true  # 启用 Kubernetes 指标采集
    namespaces: ["default", "kube-system"]  # 监控的命名空间
  statsd:
    enabled: true  # 启用 StatsD 协议支持
    port: 8125     # 覆盖默认端口

# 数据转发配置
forward:
  url: "[***]"  # Blue Matador 数据接收端点
  timeout: "30s"  # 转发超时时间

# 日志配置
logging:
  level: "info"
  format: "json"  # 日志格式：text/json

6. 注意事项

• API 密钥安全：BLUEMATADOR_API_KEY 为敏感信息，建议通过 Kubernetes Secrets 或 Docker Secrets 管理，避免明文暴露。
• 端口冲突：若宿主机或其他容器已占用 8125/udp 端口，需通过 STATSD_PORT 环境变量或配置文件修改监听端口。
• 资源限制：在 Kubernetes 环境部署时，建议设置资源限制（如 resources.limits.cpu=100m, memory=256Mi），避免资源耗尽。
• 版本兼容性：请确保 agent 版本与 Blue Matador 平台版本兼容，推荐使用 latest 标签或指定稳定版本号。