maprobe

镜像概述和主要用途

maprobe是Mackerel的外部探针/聚合代理工具，通过Mackerel API获取主机信息，执行多种探针（ping、tcp、http、命令）监控主机状态并上报指标，同时可聚合多个主机的指标生成服务级指标，适用于分布式系统的主机监控和服务指标聚合，每60秒自动循环执行监控任务。

核心功能和特性

探针功能

1. 主机信息获取：从Mackerel API拉取按服务和角色筛选的主机信息
2. 多类型探针执行：支持ping（ICMP）、tcp（TCP连接）、http（HTTP请求）、command（命令执行）四种探针类型，可通过配置文件中的占位符（如{{ .Host.IPAddresses.eth0 }}）动态替换主机属性
3. 指标上报：将探针结果生成为主机指标并上报至Mackerel
4. 定期执行：每60秒循环执行上述流程

聚合功能

1. 主机信息获取：从Mackerel API拉取按服务和角色筛选的主机信息
2. 指标聚合计算：获取指定主机指标，通过sum（求和）、avg（平均）、min/max（最小/大值）、count（计数）等函数计算聚合值
3. 服务指标上报：将聚合结果作为服务指标上报至Mackerel
4. 定期执行：每60秒循环执行上述流程

使用场景和适用范围

• 监控分布式系统中各主机的网络可达性（ping/tcp）、应用健康状态（http）、自定义指标（command）
• 聚合特定服务/角色下的主机指标（如CPU使用率、请求量），生成服务级监控视图
• 自动化清理终止的云实例（通过command探针执行脚本）

详细使用方法和配置说明

镜像获取

Docker镜像托管于DockerHub：fujiwara/maprobe

环境变量

基础命令用法

镜像支持多种命令，核心为agent（持续运行）和once（单次运行）：

# 查看帮助
docker run fujiwara/maprobe --help

# 持续运行agent（推荐生产环境）
docker run -e MACKEREL_APIKEY=your_api_key -v /path/to/config.yaml:/config.yaml fujiwara/maprobe agent --config /config.yaml

# 单次运行（测试或临时任务）
docker run -e MACKEREL_APIKEY=your_api_key -v /path/to/config.yaml:/config.yaml fujiwara/maprobe once --config /config.yaml

配置文件说明

配置文件为YAML格式，支持同时定义探针（probes）和聚合（aggregates）规则，示例如下：

探针配置示例

post_probed_metrics: true  # 是否上报探针指标（false仅日志输出）
probes:
  # ping探针示例：监控server角色主机的ICMP可达性
  - service: '{{ env "SERVICE" }}'  # 从环境变量SERVICE获取服务名
    role: server
    ping:
      address: '{{ .Host.IPAddresses.eth0 }}'  # 使用主机eth0网卡IP
  
  # http探针示例：监控webserver角色主机的健康检查接口
  - service: production
    role: webserver
    http:
      url: 'http://{{ .Host.CustomIdentifier }}/api/healthcheck'  # 使用主机自定义标识符
      method: POST
      headers:
        Content-Type: application/json
      body: '{"hello":"world"}'
      expect_pattern: 'ok'  # 响应需包含"ok"字符串
  
  # tcp+command探针示例：监控redis角色主机的TCP连接和自定义指标
  - service: production
    role: redis
    tcp:
      host: '{{ .Host.IPAddresses.eth0 }}'
      port: 6379
      send: "PING\n"
      expect_pattern: "PONG"  # 期望响应"PONG"
      quit: "QUIT\n"
    command:
      command:  # 执行redis指标插件（数组形式避免shell解析）
        - "mackerel-plugin-redis"
        - "-host={{ .Host.IPAddresses.eth0 }}"
        - "-tempfile=/tmp/redis-{{ .Host.ID }}"  # 按主机ID生成临时文件

聚合配置示例

post_aggregated_metrics: true  # 是否上报聚合指标（false仅日志输出）
aggregates:
  - service: production
    role: app-server  # 聚合production服务下app-server角色的主机指标
    metrics:
      - name: cpu.user.percentage  # 源主机指标：CPU用户使用率
        outputs:
          - func: sum  # 求和函数
            name: cpu.user.sum_percentage  # 输出服务指标名
          - func: avg  # 平均值函数
            name: cpu.user.avg_percentage
      - name: cpu.idle.percentage  # 源主机指标：CPU空闲率
        outputs:
          - func: sum
            name: cpu.idle.sum_percentage
          - func: avg
            name: cpu.idle.avg_percentage

探针类型及指标说明

Ping探针

通过ICMP协议检查主机可达性，配置及生成指标如下：

ping:
  address: "192.168.1.1"  # 目标地址（必填）
  count: 5  # 探测次数（默认3）
  timeout: "500ms"  # 单次超时（默认1秒）
  metric_key_prefix: "custom_ping"  # 指标前缀（默认ping）

生成指标：

• ping.count.success：成功次数
• ping.count.failure：失败次数
• ping.rtt.min/max/avg：最小/最大/平均往返时间（秒）

TCP探针

建立TCP连接（可选TLS）并验证响应，配置及指标：

tcp:
  host: "memcached.example.com"  # 目标主机（必填）
  port: 11211  # 目标端口（必填）
  timeout: 10s  # 连接超时（默认5秒）
  send: "VERSION\n"  # 发送字符串
  expect_pattern: "^VERSION 1"  # 期望响应的正则表达式
  tls: false  # 是否启用TLS（默认false）
  no_check_certificate: false  # 是否跳过证书校验（默认false）
  metric_key_prefix: "custom_tcp"  # 指标前缀（默认tcp）

生成指标：

• tcp.check.ok：检查结果（0失败，1成功）
• tcp.elapsed.seconds：连接耗时（秒）

HTTP探针

发送HTTP请求并验证响应，配置及指标：

http:
  url: "[***]"  # 请求URL（必填）
  method: "GET"  # 请求方法（默认GET）
  headers:  # 请求头
    Foo: "bar"
  body: '{"key":"value"}'  # 请求体
  expect_pattern: "ok"  # 期望响应的正则表达式
  timeout: 10s  # 请求超时（默认15秒）
  no_check_certificate: false  # 跳过证书校验（默认false）
  metric_key_prefix: "custom_http"  # 指标前缀（默认http）

生成指标：

• http.check.ok：检查结果（0失败，1成功；状态码≥400时为0）
• http.response_time.seconds：响应时间（秒）
• http.status.code：HTTP状态码
• http.content.length：响应体长度（字节）

Command探针

执行自定义命令获取指标（需符合Mackerel插件输出格式），配置及说明：

command:
  command:  # 命令（字符串或数组，数组形式不通过shell解析）
    - "/path/to/script.sh"
    - "{{ .Host.ID }}"  # 传递主机ID作为参数
  timeout: "5s"  # 命令超时（默认15秒）
  graph_defs: true  # 是否上报图表定义（首次运行建议设为true）

• 命令输出需符合Mackerel自定义指标格式（如metric.name value timestamp）
• graph_defs: true时，自动设置环境变量MACKEREL_AGENT_PLUGIN_META=1以获取图表定义

Docker部署示例

单容器部署（docker run）

docker run -d \
  --name maprobe \
  --restart always \
  -e MACKEREL_APIKEY="your_mackerel_api_key_here" \
  -e LOG_LEVEL="info" \
  -v /host/path/to/your/config.yaml:/app/config.yaml \  # 挂载本地配置文件
  fujiwara/maprobe agent --config /app/config.yaml  # 运行agent并指定配置文件

Docker Compose部署

version: '3.8'
services:
  maprobe:
    image: fujiwara/maprobe
    restart: always
    environment:
      - MACKEREL_APIKEY=your_mackerel_api_key_here  # 替换为实际API密钥
      - LOG_LEVEL=info  # 日志级别：debug/info/warn/error
    volumes:
      - ./config.yaml:/app/config.yaml  # 相对路径挂载配置文件（需确保文件存在）
    command: agent --config /app/config.yaml  # 启动agent模式并加载配置