statsd/statsd

StatsD

镜像概述和主要用途

StatsD 是一款运行在 Node.js 平台上的流行指标聚合守护进程，通过 UDP 或 TCP 协议监听计数器、计时器等统计数据，按配置的时间间隔聚合指标后发送至一个或多个可插拔的后端服务（如 Graphite）。其核心功能是简化分布式系统中的指标收集与聚合流程，为监控、分析提供统一的数据预处理层。

核心功能和特性

核心概念

• 指标桶（Buckets）：每个指标独立存储于“桶”中，桶名可自定义（需符合后端服务格式要求，如 Graphite 中句号表示层级目录），无需预先定义。
• 值（Values）：指标的具体数值，解释方式取决于修饰符，通常为整数。
• 刷新（Flush）：按配置的刷新间隔（默认 10 秒，由 config.flushInterval 定义），聚合统计数据并发送至上游后端服务。

关键特性

• 多协议支持：同时支持 UDP 和 TCP 协议接收指标数据。
• 可插拔后端：灵活对接 Graphite 等多种后端服务，支持扩展。
• 轻量高效：基于 Node.js 开发，资源占用低，适合高并发指标收集场景。
• 配置灵活：支持自定义刷新间隔、命名空间、调试参数等。
• 调试能力：提供 debug（异常日志与诊断信息）、dumpMessages（入站消息调试）等调试配置。

使用场景和适用范围

StatsD 适用于需实时或定期收集、聚合分布式系统指标的场景，包括但不限于：

• 应用性能监控：收集接口响应时间、错误率、请求量等应用层指标。
• 系统监控：聚合服务器 CPU、内存、网络 IO 等系统级指标。
• 业务数据统计：实时统计用户注册量、订单转化率等业务指标。
• 分布式系统追踪：作为微服务架构中的统一指标汇聚点，简化多节点指标管理。

使用方法和配置说明

安装与部署

Docker 部署

StatsD 提供两种 Docker 部署方式：

• 官方镜像：直接使用 Docker Hub 官方镜像 statsd/statsd。
• 源码构建：基于项目内置 Dockerfile 构建镜像。

Docker Run 示例

bash
# 基础启动（默认配置，需提前准备 config.js）
docker run -d \
  -p 8125:8125/udp \  # UDP 端口（指标接收）
  -p 8125:8125/tcp \  # TCP 端口（指标接收）
  -v /path/to/your/config.js:/usr/src/app/config.js \  # 挂载自定义配置文件
  --name statsd \
  statsd/statsd \
  node stats.js config.js  # 指定配置文件启动

Docker Compose 示例

yaml
version: '3'
services:
  statsd:
    image: statsd/statsd
    ports:
      - "8125:8125/udp"
      - "8125:8125/tcp"
    volumes:
      - ./config.js:/usr/src/app/config.js  # 本地配置文件挂载
    command: node stats.js config.js
    restart: always
    environment:
      - NODE_ENV=production  # 可选：设置 Node.js 环境变量

手动安装

1. 安装 Node.js：支持所有 当前及 LTS 版本。
2. 克隆项目：git clone https://github.com/statsd/statsd.git。
3. 配置文件：从 exampleConfig.js 复制并修改，保存至自定义路径。
4. 启动服务：node stats.js /path/to/config。

配置参数说明

配置文件（如 config.js）关键参数：

• flushInterval：指标聚合刷新间隔（毫秒），默认 10000（10 秒）。
• backends：后端服务列表，默认 ['graphite']，需配置对应后端参数（如 Graphite 的 host、port）。
• debug：布尔值，启用后打印异常日志及诊断信息，默认 false。
• dumpMessages：布尔值，启用后打印入站消息调试信息，默认 false。
• port/udpPort/tcpPort：监听端口，默认 UDP/TCP 均为 8125。

完整配置示例可参考项目 exampleConfig.js。

基本使用方法

指标协议格式

基础行协议格式：
<metricname>:<value>|<type>

• <metricname>：指标桶名（如 api.requests）。
• <value>：指标数值（整数）。
• <type>：指标类型（如 c 表示计数器，ms 表示计时器）。

发送示例

若 StatsD 以默认 UDP 配置运行在本地，可通过以下命令发送指标：

bash
# 发送计数器指标：api.requests 加 1
echo "api.requests:1|c" | nc -u -w0 127.0.0.1 8125

调试

通过配置文件启用调试功能：

• debug: true：记录异常及详细诊断信息。
• dumpMessages: true：打印所有入站指标消息，辅助排查数据发送问题。
  配置项详情见 exampleConfig.js。

测试

项目使用 node-unit 及自定义代码构建测试框架，测试用例位于 test/ 目录。执行以下命令运行测试：

bash
./run_tests.sh

注：测试过程中若出现服务残留，可通过 killall statsd 清理（生产环境禁用）。

更多参考

• https://github.com/statsd/statsd/blob/master/docs/metric_types.md
• https://github.com/statsd/statsd/blob/master/docs/graphite.md
• https://github.com/statsd/statsd/blob/master/docs/server.md
• https://github.com/statsd/statsd/blob/master/docs/backend.md
• https://github.com/statsd/statsd/blob/master/docs/admin_interface.md