StatsD 入门与实践基于 Node.js 的实时指标聚合守护进程完全指南【免费下载链接】statsdDaemon for easy but powerful stats aggregation项目地址: https://gitcode.com/gh_mirrors/st/statsdStatsD 是一个运行在 Node.js 平台上的网络守护进程负责通过 UDP 或 TCP 接收应用发送的计数器、计时器等统计指标按固定周期聚合后转发给一个或多个可插拔后端服务典型如 Graphite。本指南将以本仓库 README.md 为主线结合 stats.js 入口、exampleConfig.js 配置样例与 docs/ 系列文档完整覆盖核心概念、安装方式、行协议用法、指标类型、服务器/后端扩展机制与调试运维手段帮助你从零搭建一套可用的 StatsD 指标采集链路。StatsD 是什么StatsD 本质上是一个轻量级的“指标路由器”运行于Node.js 平台当前仓库的 package.json 声明engines: { node: 8 }README 表示所有 Current 与 LTS 版本均受支持监听统计指标包括计数器counters与计时器timers等通过UDP或TCP传输按 flush 周期聚合并发送到一个或多个可插拔的后端服务如 Graphite 时间序列数据库。从源码结构看整个程序的核心入口是 stats.js它先通过 lib/config.js 读取配置文件加载后端loadBackend与服务器startServer随后在handlePacket中完成消息解析、采样率处理与各类指标的入桶最后由flushMetrics在每个 flush 周期把聚合结果交给后端。可见“接收 → 聚合 → 转发”三个环节全部由这一套事件驱动模型串起来。核心概念README 定义了三个基础概念理解它们是上手 StatsD 的前提buckets桶每一条统计都位于独立的“桶”中。桶无需预定义可以任意命名只要名字能映射到 Graphite 即可英文句点会被 Graphite 当作目录层级分隔符。例如stats.timers.api.request_time会在 Graphite 中形成多层路径。values值每条统计都带一个数值其含义取决于修饰符metric type。一般情况下值应为整数。flush刷新每经过一个 flush 周期由config.flushInterval定义默认 10 秒StatsD 将聚合后的统计发送给上游后端服务。在 stats.js 中flushInterval Number(config.flushInterval || 10000)随后通过flushMetrics组装counters / gauges / timers / timer_counters / sets / counter_rates / timer_data等数据backendEvents.emit(flush, time_stamp, metrics)交给各后端处理。安装与配置使用 DockerREADME 说明 StatsD 支持三种 Docker 使用方式使用官方容器镜像GitHub Container Registry使用官方容器镜像Docker Hub直接使用仓库内置的 Dockerfile 构建镜像仓库还附带了 docker-compose.yml 可参考编排。手动安装安装 Node.js支持所有 Current 与 LTS 版本克隆本项目创建配置文件从 exampleConfig.js 复制一份并按需修改放到合适位置启动守护进程node stats.js /path/to/config其中/path/to/config即配置文件路径。lib/config.js 中configFile会读取该文件并且默认通过fs.watch监听配置变化——只要automaticConfigReload未显式设为false配置文件变更时会自动重新加载。基础使用行协议README 给出的行协议line protocol格式非常简单metricname:value|type例如在默认 UDP 服务器运行于 localhost 的前提下最简单的发送方式是echo foo:1|c | nc -u -w0 127.0.0.1 8125这条命令把foo:1|c计数器foo加 1通过 UDP 发送到本机 8125 端口。stats.js 的handlePacket会按|切分字段判断指标类型并写入对应桶c计入countersms计入timersg计入gaugess计入sets同时还会解析可选的采样率字段0.1见下文。每次收到合法消息都会递增packets_received与metrics_received计数器非法行则计入bad_lines_seen。指标类型详解README 将指标类型细节指向 docs/metric_types.md以下结合该文档与 stats.js 源码逐类展开。计数器Countergorets:1|c向gorets桶累加 1。每次 flush 时把当前计数值发送出去并重置为 0参见 stats.js 中 flush 后清空 counters 的逻辑。若 flush 时计数为 0可通过config.deleteCounters选择完全不发送该指标仅对 graphite 后端生效。StatsD 每次 flush 会同时发送速率rate与计数值count两种形式。采样Samplinggorets:1|c|0.1告诉 StatsD该计数器是每 1/10 次采样发送一次。StatsD 会据此把收到的值放大乘以1/sampleRate以还原真实总量。stats.js 中通过fields[2].match(/^([\d\.])/)提取采样率计数器累加时执行counters[key] Number(fields[0] || 1) * (1 / sampleRate)。计时器Timingglork:320|ms|0.1表示本次glork耗时 320ms。在 flush 周期内StatsD 会为该计时器计算百分位数、均值mean、标准差、总和sum、下界lower与上界upper。百分位阈值由config.percentThreshold控制默认 90可以是单个数值也可以是数值列表源码中会把单值listify成数组。每个阈值会生成如下指标stats.timers.$KEY.mean_$PCT stats.timers.$KEY.upper_$PCT stats.timers.$KEY.sum_$PCT其中$KEY是发送指标时的 key$PCT是百分位阈值。注意区别mean是 flush 周期内全部计时值的均值而mean_$PCT是落入$PCT百分位范围内样本的均值sum、upper同理。若 flush 时计时器计数为 0可设置config.deleteTimers不发送该指标。计时器同样支持采样率字段上面的0.1该字段可选默认 1采样率同时作用于计时器自带的那份计数器timer_counters。直方图Histogram通过config.histogram可以要求 StatsD 为计时器跨时间维护直方图指定要匹配的指标名与一组有序的非包含式上界bin 上限用inf表示无穷大下界默认假设为 0。每个 flush 周期StatsD 记录落在每个区间内的值的绝对频次。示例// 只为 render 计时维护直方图不等距区间并带无穷大兜底区间 [ { metric: render, bins: [ 0.01, 0.1, 1, 10, inf] } ] // 除 foo 之外的所有计时器等距区间 兜底 [ { metric: foo, bins: [] }, { metric: , bins: [ 50, 100, 150, 200, inf] } ]注意默认值为[]不维护任何直方图对某指标第一个匹配的规则生效bin 上限可含小数由于每个区间可任意宽这比严格意义的直方图更灵活。仪表Gaugegaugor:333|g仪表直接取所赋的任意值并一直保持到下次被设置。flush 时若未被更新默认仍发送上一次的值可通过config.deleteGauges改为不发送。带符号的值会改变而非设置仪表gaugor:-10|g gaugor:4|g若gaugor原为 333则上述两条命令将其变为333 - 10 4 327。这意味着无法直接把仪表显式设置为负数除非先将其置 0。stats.js 中对应逻辑为gauges[key] fields[0].match(/^[-]/)时累加否则赋值。集合Setuniques:765|sStatsD 用 Set 数据结构统计两次 flush 之间唯一事件出现的次数。flush 时计数为 0 时可设置config.deleteSets不发送该指标。集合的底层实现位于 lib/set.js。多指标包Multi-Metric Packets单个数据包内可用换行分隔多条指标gorets:1|c\nglork:320|ms\ngaugor:333|g\nuniques:765|s注意控制载荷总长度不超过所在网络的 MTU。README/docs 给出的参考上限已计入最大 IP UDP 头快速以太网1432内网环境最常见千兆以太网8932配合 Jumbo Frames 可显著提升效率公网链路512跨公网路由时该值较稳妥可尝试更高但取决于沿途各跳。服务器与协议StatsD 的服务器模块是可插拔的详见 docs/server.md。仓库内置两种UDPudp监听 UDP 端口接收指标。一个 UDP 包至少包含一条指标多条指标可用\n分隔在同一包中对应 servers/udp.js。TCPtcp监听 TCP 端口接收指标。由于指标可能横跨多个 TCP 包每条指标必须以\n结尾对应 servers/tcp.js。默认自动加载udp服务器当前一次只能运行一个服务器。选择方式是在配置中设置server变量为要加载的模块名——由于该名称同时用于require指令可用相对路径指定如./servers/udp。服务器本质上是实现 docs/server_interface.md 所述接口的 npm 模块。从 stats.js 源码看server_config config.servers || [config]即若未配置servers数组则回退使用顶层的server / address / address_ipv6 / port等配置以保持向后兼容。服务器加载后其回调handlePacket会仿照 dgram 的message事件签名msg, rinfo被调用。后端系统StatsD 的后端同样可插拔详见 docs/backend.md。后端负责把本地聚合的统计发布到后端服务或数据存储可以是时序数据库、可视化系统也可以是基于阈值的告警系统甚至能汇总多台主机上报的指标。仓库内置三种后端Graphitegraphite开源时序数据存储提供浏览器端可视化对应 backends/graphite.jsConsoleconsole把收到的指标输出到 stdout适合开发期观察对应 backends/console.jsRepeaterrepeater利用packet事件 API把 StatsD 收到的原始数据包转发给多个下游 StatsD 实例对应 backends/repeater.js。默认自动加载graphite后端多个后端可同时运行。通过配置backends数组选择要加载的后端backends: [ ./backends/console, ./backends/graphite ]stats.js 中loadBackend会require每个后端并调用其init(startup_time, config, backendEvents, l)初始化失败则记录 ERROR 并退出进程。后端同样只是实现 docs/backend_interface.md 所述接口的 npm 模块可用相对路径加载。社区还提供了大量第三方后端如 Datadog、InfluxDB、OpenTSDB、Zabbix 等可满足写入各类数据库、队列与第三方服务的需求。Graphite 集成要点若选择 Graphite 作为后端docs/graphite.md 专门讨论了最容易踩坑的“数据丢失 / 被平均 / 未落盘”问题核心是两类配置必须与 StatsD 的 flush 节奏对齐。Storage Schemas保留策略编辑 Graphite 的conf/storage-schemas.conf示例[stats] pattern ^stats.* retentions 10s:6h,1m:6d,10m:1800d含义对所有以stats开头的指标即 StatsD 发送的全部指标——保留 6 小时 10 秒分辨率数据近实时保留 6 天 1 分钟数据保留 5 年1800 天10 分钟数据。经验上该组合是文件大小与数据价值间的较好折衷每个 stats 数据库文件约 3.2MB。注意retentions 按顺序匹配、先匹配先生效且每个指标在首次创建数据库文件时固化保留策略之后修改配置不影响已有文件需用 whisper 自带的whisper-info.py/whisper-resize.py调整。与 flush 周期的关系若 StatsD 的 flush 周期短于最高分辨率保留间隔如 10 秒同一 10 秒内到达的多条值只有最后一条被持久化数据会部分丢失。因此 flush 周期应至少等于最高分辨率保留间隔但周期过长又会引发其他问题见下文聚合部分。Storage Aggregation降采样聚合Graphite 对降采样默认采用平均值但这并不适合所有 StatsD 指标例如计时器的.count应求和而非求平均。参考配置conf/storage-aggregation.conf[min] pattern \.lower$ xFilesFactor 0.1 aggregationMethod min [max] pattern \.upper(_\d)?$ xFilesFactor 0.1 aggregationMethod max [sum] pattern \.sum$ xFilesFactor 0 aggregationMethod sum [count] pattern \.count$ xFilesFactor 0 aggregationMethod sum [count_legacy] pattern ^stats_counts.* xFilesFactor 0 aggregationMethod sum [default_average] pattern .* xFilesFactor 0.3 aggregationMethod average要点以.lower/.upper结尾的指标所有计时器都会发送在滚动降采样时保留最小/最大值少于 10% 数据点时存None名称含count/sum或以stats_counts开头的指标非归一化的计数器全部求和仅在无任何数据点时存None这样会命中所有非归一化计数器但忽略按秒归一化的计数器其余指标按平均值降采样少于 30% 数据点时存None。xFilesFactor需要特别注意flush 周期不够长、样本不足时会因不满足最低因子而在第一次降采样周期丢失数据但设得过低又会产生误导性的结果例如 10 分钟内仅 1 个 10 秒均值样本不应被降采样成 10 分钟均值。对计数类指标求和语义下每个计数都应被计入故因子为 0。命名空间备注.count对所有计时器都会计算v0.5.0 及之前非归一化计数器写于stats_counts之下而 0.5.0 之后若配置legacyNamespacefalse计数器会写到stats.counters下包含两种变体按秒的rate与按 flush 的非归一化count。与 retentions 相同聚合规则也在指标首次接收时固化修改不影响已有指标。指标命名空间Graphite 后端的命名前缀是可配置的详见 docs/namespacing.md。默认所有统计都归入 Graphite 的stats前缀下便于统一 schema。可在graphite配置键下调整graphite: { legacyNamespace: true, // 是否使用旧命名空间 [默认 true] globalPrefix: stats, // 全局前缀 [默认 stats] prefixCounter: counters,// 计数器前缀 prefixTimer: timers, // 计时器前缀 prefixGauge: gauges, // 仪表前缀 prefixSet: sets // 集合前缀 }关闭 legacy 命名空间除了前缀变化外还有一处破坏性变更计数器提交方式改变。旧命名空间下速率直接记录在stats.counter_name绝对值记录在stats_counts.counter_name关闭 legacy 后使用默认前缀变为stats.counters.counter_name.rate stats.counters.counter_name.count集合的元素个数则记录在stats.sets.set_name.count其中sets即prefixSet。相关实现可在 backends/graphite.js 中看到legacyNamespace / globalPrefix / prefixCounter / prefixTimer / prefixGauge / prefixSet / globalSuffix等变量对命名空间的组装逻辑。管理 TCP 接口StatsD 默认在8126 端口暴露一个极简 TCP 管理接口可在配置中覆盖对应配置项mgmt_address/mgmt_port默认分别为0.0.0.0与8126灵感来自 memcache 的 stats 做法可用来监控运行中的服务器详见 docs/admin_interface.md。用 telnet 连接后可用命令如下通用命令health [up|down]查看/设置健康状态。单独执行返回当前状态传入第二个参数则设置为新值合法值为up与downconfig导出当前配置quit由服务端关闭连接。StatsD 专属命令stats运行状态统计counters导出当前全部计数器gauges导出当前全部仪表timers导出当前全部计时器delcounters/delgauges/deltimers删除单个指标或某目录前缀下的指标。stats输出目前包含uptime自启动以来的秒数、messages.last_msg_seen距上次收到消息的秒数、messages.bad_lines_seen自启动以来的坏行数。删除指标的示例# 删除单个计数器 sandbox.test.temporary echo delcounters sandbox.test.temporary | nc 127.0.0.1 8126 # 删除目录 sandbox.test.* 下的计数器 echo delcounters sandbox.test.* | nc 127.0.0.1 8126每个后端还会发布一组以模块名称为前缀的统计。Graphite 后端提供graphite.last_flush上次成功 flush 的 unix 时间戳、graphite.last_exception上次 flush 异常时间戳、graphite.flush_length发送给 graphite 的字符串长度、graphite.flush_time发送耗时。这些统计也会以stats.statsd.graphiteStats.last_exception与stats.statsd.graphiteStats.last_flush命名空间发往 Graphite。仓库 utils/ 目录提供了可用于检查指标阈值的检查脚本例如距上次成功 flush 的秒数。另外healthStatus配置项可设置启动时的默认健康状态up或down。管理接口的命令处理逻辑含delcounters等删除操作可在 stats.js 的mgmt_server.start回调中看到。完整配置参考exampleConfig.js 是官方配置模板下面整理其全部配置项含默认值与说明Graphite 必备变量graphiteHostGraphite 服务器的主机名或 IP。留空则不向 Graphite 发送统计配合debug开启时等于以 dry 调试模式运行适合在无 Graphite 服务器的情况下测试客户端。可选变量graphitePortGraphite 文本收集端口 [默认 2003]graphitePicklePortGraphite pickle 收集端口 [默认 2004]graphiteProtocoltext或pickle[默认text]backends要加载的后端数组模块需存在于backends/目录不指定则默认加载 graphite 后端servers服务器配置数组。不指定则使用顶层server / address / address_ipv6 / port配置单个服务器向后兼容。每个服务器配置支持server要加载的服务器模块存在于servers/目录不指定默认加载 udp 服务器address监听地址 [默认0.0.0.0]address_ipv6地址是否为 IPv6 [true/false默认 false]port监听端口 [默认 8125]socket仅 TCP接收指标所用的 unix domain socket 路径 [默认 undefined]socket_mod仅 TCPunix domain socket 的文件模式 [默认 undefined]debug调试开关记录异常并输出更多诊断信息 [默认 false]mgmt_address/mgmt_port管理 TCP 接口的地址与端口 [默认0.0.0.0/ 8126]title覆盖进程标题 [默认statsd]设为 false 则不覆盖标题长度须不超过二进制名 CLI 参数长度healthStatusStatsD 启动时的默认健康状态 [up或down默认up]dumpMessages记录所有收到的消息flushInterval向各后端 flush 指标的间隔mspercentThreshold计时器百分位阈值可为单个值或浮点值列表负值表示取top N 百分位 [默认 90]flush_counts是否发送stats_counts指标 [默认 true]keyFlush记录最频繁发送的 key [对象默认 undefined]interval记录频繁 key 的频率 [ms默认 0]percent记录高频 key 的百分比 [默认 100]log高频 key 日志文件位置 [默认 STDOUT]deleteIdleStats不向 graphite 发送空闲计数器/集合/仪表/计时器的值而非发送 0对仪表而言是取消设置而非发送旧值。可被各 delete 项单独覆盖 [默认 false]deleteGauges不发送空闲仪表值默认发送旧值[默认 false]gaugesMaxTTL仪表被标记为空闲前等待的 flush 周期数与deleteGauges配合使用 [默认 1]deleteTimers/deleteSets/deleteCounters不发送空闲计时器/集合/计数器默认发送 0[默认 false]prefixStats本实例统计数据的命名前缀 [默认statsd]对 legacy 与新命名空间均生效keyNameSanitize入口处净化所有指标名 [默认 true]若关闭则由后端按自身存储要求净化对应 stats.js 中sanitizeKeyName的空格转_、/转-、非法字符剔除逻辑calculatedTimerMetrics要发送的计时器指标列表默认发送全部按百分位过滤时在指标名后追加_percent如[count, median, upper_percent, histogram]console.prettyprint是否美化 console 后端输出 [默认 true]log日志设置 [默认 undefined]backendstdout或syslog[默认stdout]applicationsyslog 应用名 [默认statsd]level日志级别 [默认LOG_INFO]graphite.legacyNamespace / globalPrefix / prefixCounter / prefixTimer / prefixGauge / prefixSet见上文命名空间一节graphite.globalSuffix发送给 graphite 的全局后缀 [默认 ]适合按主机区分统计例如设为require(os).hostname().split(.)[0]repeater数组元素为{ host, port }指明收到的数据包要重复复制发送到的其他 statsd 服务器如[ { host: 10.10.10.10, port: 8125 }, { host: observer, port: 88125 } ]repeaterProtocolrepeater 使用的协议udp4、udp6或tcp[默认udp4]histogram见上文直方图一节默认[]automaticConfigReload是否监听配置文件并在变更时重载 [默认 true]设 false 关闭。最小可用配置示例即 exampleConfig.js 底部实际给出的默认值{ graphitePort: 2003 , graphiteHost: graphite.example.com , port: 8125 , backends: [ ./backends/graphite ] }调试与排障README 明确给出的调试配置变量debug记录异常并输出更多诊断信息dumpMessages打印收到的每条消息的调试信息。两者在 stats.js 中均有对应逻辑debug模式下加载服务器/后端时会输出 DEBUG 日志dumpMessages开启时每条消息会被记录。更多细节见 exampleConfig.js。另外docs/admin_interface.md 提到可用health命令配合监控health单独执行查看当前状态health up|down改变状态healthStatus配置项设置启动默认值——这些组合可以很方便地接入外部健康检查。运行测试项目使用 nodeunit 框架并配有自定义的启动/操控 StatsD 的测试代码。任何新功能或 bug 修复都应在 test/ 目录下补充测试。README 提醒实时服务器的测试较为微妙已尽力消除竞态条件但仍可能偶发卡死开发时可用killall statsd清理后台残留的测试服务器切勿在生产机器上执行。执行测试的方式以仓库实际内容为准node run_tests.js或通过 package.json 的脚本执行npm test内部同样是node run_tests.js。测试框架入口见 run_tests.js它会加载 nodeunit 并运行test/目录下的全部用例失败时以非零码退出。测试覆盖范围可从 test/ 目录窥见一斑例如graphite_tests.js、graphite_legacy_tests.js、process_metrics_tests.js、server_tests.js、set_tests.js等分别对应 Graphite 后端、指标处理、服务器与集合等核心模块。历史与灵感StatsD 最初由Etsy开发并随一篇详细讲解其工作原理与诞生缘由的博客文章一同发布。它的设计严重地受启发于 Flickr 的同名项目后者由 Cal Henderson 撰写深度介绍并开源了 Perl 版实现。这些背景解释了 StatsD 为何选择极简行协议 服务器端聚合 可插拔后端这一架构让客户端发送开销降到最低把聚合与存储的复杂度收敛到服务端。【免费下载链接】statsdDaemon for easy but powerful stats aggregation项目地址: https://gitcode.com/gh_mirrors/st/statsd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 StatsD 入门与实践：基于 Node.js 的实时指标聚合守护进程完全指南
StatsD 入门与实践基于 Node.js 的实时指标聚合守护进程完全指南【免费下载链接】statsdDaemon for easy but powerful stats aggregation项目地址: https://gitcode.com/gh_mirrors/st/statsdStatsD 是一个运行在 Node.js 平台上的网络守护进程负责通过 UDP 或 TCP 接收应用发送的计数器、计时器等统计指标按固定周期聚合后转发给一个或多个可插拔后端服务典型如 Graphite。本指南将以本仓库 README.md 为主线结合 stats.js 入口、exampleConfig.js 配置样例与 docs/ 系列文档完整覆盖核心概念、安装方式、行协议用法、指标类型、服务器/后端扩展机制与调试运维手段帮助你从零搭建一套可用的 StatsD 指标采集链路。StatsD 是什么StatsD 本质上是一个轻量级的“指标路由器”运行于Node.js 平台当前仓库的 package.json 声明engines: { node: 8 }README 表示所有 Current 与 LTS 版本均受支持监听统计指标包括计数器counters与计时器timers等通过UDP或TCP传输按 flush 周期聚合并发送到一个或多个可插拔的后端服务如 Graphite 时间序列数据库。从源码结构看整个程序的核心入口是 stats.js它先通过 lib/config.js 读取配置文件加载后端loadBackend与服务器startServer随后在handlePacket中完成消息解析、采样率处理与各类指标的入桶最后由flushMetrics在每个 flush 周期把聚合结果交给后端。可见“接收 → 聚合 → 转发”三个环节全部由这一套事件驱动模型串起来。核心概念README 定义了三个基础概念理解它们是上手 StatsD 的前提buckets桶每一条统计都位于独立的“桶”中。桶无需预定义可以任意命名只要名字能映射到 Graphite 即可英文句点会被 Graphite 当作目录层级分隔符。例如stats.timers.api.request_time会在 Graphite 中形成多层路径。values值每条统计都带一个数值其含义取决于修饰符metric type。一般情况下值应为整数。flush刷新每经过一个 flush 周期由config.flushInterval定义默认 10 秒StatsD 将聚合后的统计发送给上游后端服务。在 stats.js 中flushInterval Number(config.flushInterval || 10000)随后通过flushMetrics组装counters / gauges / timers / timer_counters / sets / counter_rates / timer_data等数据backendEvents.emit(flush, time_stamp, metrics)交给各后端处理。安装与配置使用 DockerREADME 说明 StatsD 支持三种 Docker 使用方式使用官方容器镜像GitHub Container Registry使用官方容器镜像Docker Hub直接使用仓库内置的 Dockerfile 构建镜像仓库还附带了 docker-compose.yml 可参考编排。手动安装安装 Node.js支持所有 Current 与 LTS 版本克隆本项目创建配置文件从 exampleConfig.js 复制一份并按需修改放到合适位置启动守护进程node stats.js /path/to/config其中/path/to/config即配置文件路径。lib/config.js 中configFile会读取该文件并且默认通过fs.watch监听配置变化——只要automaticConfigReload未显式设为false配置文件变更时会自动重新加载。基础使用行协议README 给出的行协议line protocol格式非常简单metricname:value|type例如在默认 UDP 服务器运行于 localhost 的前提下最简单的发送方式是echo foo:1|c | nc -u -w0 127.0.0.1 8125这条命令把foo:1|c计数器foo加 1通过 UDP 发送到本机 8125 端口。stats.js 的handlePacket会按|切分字段判断指标类型并写入对应桶c计入countersms计入timersg计入gaugess计入sets同时还会解析可选的采样率字段0.1见下文。每次收到合法消息都会递增packets_received与metrics_received计数器非法行则计入bad_lines_seen。指标类型详解README 将指标类型细节指向 docs/metric_types.md以下结合该文档与 stats.js 源码逐类展开。计数器Countergorets:1|c向gorets桶累加 1。每次 flush 时把当前计数值发送出去并重置为 0参见 stats.js 中 flush 后清空 counters 的逻辑。若 flush 时计数为 0可通过config.deleteCounters选择完全不发送该指标仅对 graphite 后端生效。StatsD 每次 flush 会同时发送速率rate与计数值count两种形式。采样Samplinggorets:1|c|0.1告诉 StatsD该计数器是每 1/10 次采样发送一次。StatsD 会据此把收到的值放大乘以1/sampleRate以还原真实总量。stats.js 中通过fields[2].match(/^([\d\.])/)提取采样率计数器累加时执行counters[key] Number(fields[0] || 1) * (1 / sampleRate)。计时器Timingglork:320|ms|0.1表示本次glork耗时 320ms。在 flush 周期内StatsD 会为该计时器计算百分位数、均值mean、标准差、总和sum、下界lower与上界upper。百分位阈值由config.percentThreshold控制默认 90可以是单个数值也可以是数值列表源码中会把单值listify成数组。每个阈值会生成如下指标stats.timers.$KEY.mean_$PCT stats.timers.$KEY.upper_$PCT stats.timers.$KEY.sum_$PCT其中$KEY是发送指标时的 key$PCT是百分位阈值。注意区别mean是 flush 周期内全部计时值的均值而mean_$PCT是落入$PCT百分位范围内样本的均值sum、upper同理。若 flush 时计时器计数为 0可设置config.deleteTimers不发送该指标。计时器同样支持采样率字段上面的0.1该字段可选默认 1采样率同时作用于计时器自带的那份计数器timer_counters。直方图Histogram通过config.histogram可以要求 StatsD 为计时器跨时间维护直方图指定要匹配的指标名与一组有序的非包含式上界bin 上限用inf表示无穷大下界默认假设为 0。每个 flush 周期StatsD 记录落在每个区间内的值的绝对频次。示例// 只为 render 计时维护直方图不等距区间并带无穷大兜底区间 [ { metric: render, bins: [ 0.01, 0.1, 1, 10, inf] } ] // 除 foo 之外的所有计时器等距区间 兜底 [ { metric: foo, bins: [] }, { metric: , bins: [ 50, 100, 150, 200, inf] } ]注意默认值为[]不维护任何直方图对某指标第一个匹配的规则生效bin 上限可含小数由于每个区间可任意宽这比严格意义的直方图更灵活。仪表Gaugegaugor:333|g仪表直接取所赋的任意值并一直保持到下次被设置。flush 时若未被更新默认仍发送上一次的值可通过config.deleteGauges改为不发送。带符号的值会改变而非设置仪表gaugor:-10|g gaugor:4|g若gaugor原为 333则上述两条命令将其变为333 - 10 4 327。这意味着无法直接把仪表显式设置为负数除非先将其置 0。stats.js 中对应逻辑为gauges[key] fields[0].match(/^[-]/)时累加否则赋值。集合Setuniques:765|sStatsD 用 Set 数据结构统计两次 flush 之间唯一事件出现的次数。flush 时计数为 0 时可设置config.deleteSets不发送该指标。集合的底层实现位于 lib/set.js。多指标包Multi-Metric Packets单个数据包内可用换行分隔多条指标gorets:1|c\nglork:320|ms\ngaugor:333|g\nuniques:765|s注意控制载荷总长度不超过所在网络的 MTU。README/docs 给出的参考上限已计入最大 IP UDP 头快速以太网1432内网环境最常见千兆以太网8932配合 Jumbo Frames 可显著提升效率公网链路512跨公网路由时该值较稳妥可尝试更高但取决于沿途各跳。服务器与协议StatsD 的服务器模块是可插拔的详见 docs/server.md。仓库内置两种UDPudp监听 UDP 端口接收指标。一个 UDP 包至少包含一条指标多条指标可用\n分隔在同一包中对应 servers/udp.js。TCPtcp监听 TCP 端口接收指标。由于指标可能横跨多个 TCP 包每条指标必须以\n结尾对应 servers/tcp.js。默认自动加载udp服务器当前一次只能运行一个服务器。选择方式是在配置中设置server变量为要加载的模块名——由于该名称同时用于require指令可用相对路径指定如./servers/udp。服务器本质上是实现 docs/server_interface.md 所述接口的 npm 模块。从 stats.js 源码看server_config config.servers || [config]即若未配置servers数组则回退使用顶层的server / address / address_ipv6 / port等配置以保持向后兼容。服务器加载后其回调handlePacket会仿照 dgram 的message事件签名msg, rinfo被调用。后端系统StatsD 的后端同样可插拔详见 docs/backend.md。后端负责把本地聚合的统计发布到后端服务或数据存储可以是时序数据库、可视化系统也可以是基于阈值的告警系统甚至能汇总多台主机上报的指标。仓库内置三种后端Graphitegraphite开源时序数据存储提供浏览器端可视化对应 backends/graphite.jsConsoleconsole把收到的指标输出到 stdout适合开发期观察对应 backends/console.jsRepeaterrepeater利用packet事件 API把 StatsD 收到的原始数据包转发给多个下游 StatsD 实例对应 backends/repeater.js。默认自动加载graphite后端多个后端可同时运行。通过配置backends数组选择要加载的后端backends: [ ./backends/console, ./backends/graphite ]stats.js 中loadBackend会require每个后端并调用其init(startup_time, config, backendEvents, l)初始化失败则记录 ERROR 并退出进程。后端同样只是实现 docs/backend_interface.md 所述接口的 npm 模块可用相对路径加载。社区还提供了大量第三方后端如 Datadog、InfluxDB、OpenTSDB、Zabbix 等可满足写入各类数据库、队列与第三方服务的需求。Graphite 集成要点若选择 Graphite 作为后端docs/graphite.md 专门讨论了最容易踩坑的“数据丢失 / 被平均 / 未落盘”问题核心是两类配置必须与 StatsD 的 flush 节奏对齐。Storage Schemas保留策略编辑 Graphite 的conf/storage-schemas.conf示例[stats] pattern ^stats.* retentions 10s:6h,1m:6d,10m:1800d含义对所有以stats开头的指标即 StatsD 发送的全部指标——保留 6 小时 10 秒分辨率数据近实时保留 6 天 1 分钟数据保留 5 年1800 天10 分钟数据。经验上该组合是文件大小与数据价值间的较好折衷每个 stats 数据库文件约 3.2MB。注意retentions 按顺序匹配、先匹配先生效且每个指标在首次创建数据库文件时固化保留策略之后修改配置不影响已有文件需用 whisper 自带的whisper-info.py/whisper-resize.py调整。与 flush 周期的关系若 StatsD 的 flush 周期短于最高分辨率保留间隔如 10 秒同一 10 秒内到达的多条值只有最后一条被持久化数据会部分丢失。因此 flush 周期应至少等于最高分辨率保留间隔但周期过长又会引发其他问题见下文聚合部分。Storage Aggregation降采样聚合Graphite 对降采样默认采用平均值但这并不适合所有 StatsD 指标例如计时器的.count应求和而非求平均。参考配置conf/storage-aggregation.conf[min] pattern \.lower$ xFilesFactor 0.1 aggregationMethod min [max] pattern \.upper(_\d)?$ xFilesFactor 0.1 aggregationMethod max [sum] pattern \.sum$ xFilesFactor 0 aggregationMethod sum [count] pattern \.count$ xFilesFactor 0 aggregationMethod sum [count_legacy] pattern ^stats_counts.* xFilesFactor 0 aggregationMethod sum [default_average] pattern .* xFilesFactor 0.3 aggregationMethod average要点以.lower/.upper结尾的指标所有计时器都会发送在滚动降采样时保留最小/最大值少于 10% 数据点时存None名称含count/sum或以stats_counts开头的指标非归一化的计数器全部求和仅在无任何数据点时存None这样会命中所有非归一化计数器但忽略按秒归一化的计数器其余指标按平均值降采样少于 30% 数据点时存None。xFilesFactor需要特别注意flush 周期不够长、样本不足时会因不满足最低因子而在第一次降采样周期丢失数据但设得过低又会产生误导性的结果例如 10 分钟内仅 1 个 10 秒均值样本不应被降采样成 10 分钟均值。对计数类指标求和语义下每个计数都应被计入故因子为 0。命名空间备注.count对所有计时器都会计算v0.5.0 及之前非归一化计数器写于stats_counts之下而 0.5.0 之后若配置legacyNamespacefalse计数器会写到stats.counters下包含两种变体按秒的rate与按 flush 的非归一化count。与 retentions 相同聚合规则也在指标首次接收时固化修改不影响已有指标。指标命名空间Graphite 后端的命名前缀是可配置的详见 docs/namespacing.md。默认所有统计都归入 Graphite 的stats前缀下便于统一 schema。可在graphite配置键下调整graphite: { legacyNamespace: true, // 是否使用旧命名空间 [默认 true] globalPrefix: stats, // 全局前缀 [默认 stats] prefixCounter: counters,// 计数器前缀 prefixTimer: timers, // 计时器前缀 prefixGauge: gauges, // 仪表前缀 prefixSet: sets // 集合前缀 }关闭 legacy 命名空间除了前缀变化外还有一处破坏性变更计数器提交方式改变。旧命名空间下速率直接记录在stats.counter_name绝对值记录在stats_counts.counter_name关闭 legacy 后使用默认前缀变为stats.counters.counter_name.rate stats.counters.counter_name.count集合的元素个数则记录在stats.sets.set_name.count其中sets即prefixSet。相关实现可在 backends/graphite.js 中看到legacyNamespace / globalPrefix / prefixCounter / prefixTimer / prefixGauge / prefixSet / globalSuffix等变量对命名空间的组装逻辑。管理 TCP 接口StatsD 默认在8126 端口暴露一个极简 TCP 管理接口可在配置中覆盖对应配置项mgmt_address/mgmt_port默认分别为0.0.0.0与8126灵感来自 memcache 的 stats 做法可用来监控运行中的服务器详见 docs/admin_interface.md。用 telnet 连接后可用命令如下通用命令health [up|down]查看/设置健康状态。单独执行返回当前状态传入第二个参数则设置为新值合法值为up与downconfig导出当前配置quit由服务端关闭连接。StatsD 专属命令stats运行状态统计counters导出当前全部计数器gauges导出当前全部仪表timers导出当前全部计时器delcounters/delgauges/deltimers删除单个指标或某目录前缀下的指标。stats输出目前包含uptime自启动以来的秒数、messages.last_msg_seen距上次收到消息的秒数、messages.bad_lines_seen自启动以来的坏行数。删除指标的示例# 删除单个计数器 sandbox.test.temporary echo delcounters sandbox.test.temporary | nc 127.0.0.1 8126 # 删除目录 sandbox.test.* 下的计数器 echo delcounters sandbox.test.* | nc 127.0.0.1 8126每个后端还会发布一组以模块名称为前缀的统计。Graphite 后端提供graphite.last_flush上次成功 flush 的 unix 时间戳、graphite.last_exception上次 flush 异常时间戳、graphite.flush_length发送给 graphite 的字符串长度、graphite.flush_time发送耗时。这些统计也会以stats.statsd.graphiteStats.last_exception与stats.statsd.graphiteStats.last_flush命名空间发往 Graphite。仓库 utils/ 目录提供了可用于检查指标阈值的检查脚本例如距上次成功 flush 的秒数。另外healthStatus配置项可设置启动时的默认健康状态up或down。管理接口的命令处理逻辑含delcounters等删除操作可在 stats.js 的mgmt_server.start回调中看到。完整配置参考exampleConfig.js 是官方配置模板下面整理其全部配置项含默认值与说明Graphite 必备变量graphiteHostGraphite 服务器的主机名或 IP。留空则不向 Graphite 发送统计配合debug开启时等于以 dry 调试模式运行适合在无 Graphite 服务器的情况下测试客户端。可选变量graphitePortGraphite 文本收集端口 [默认 2003]graphitePicklePortGraphite pickle 收集端口 [默认 2004]graphiteProtocoltext或pickle[默认text]backends要加载的后端数组模块需存在于backends/目录不指定则默认加载 graphite 后端servers服务器配置数组。不指定则使用顶层server / address / address_ipv6 / port配置单个服务器向后兼容。每个服务器配置支持server要加载的服务器模块存在于servers/目录不指定默认加载 udp 服务器address监听地址 [默认0.0.0.0]address_ipv6地址是否为 IPv6 [true/false默认 false]port监听端口 [默认 8125]socket仅 TCP接收指标所用的 unix domain socket 路径 [默认 undefined]socket_mod仅 TCPunix domain socket 的文件模式 [默认 undefined]debug调试开关记录异常并输出更多诊断信息 [默认 false]mgmt_address/mgmt_port管理 TCP 接口的地址与端口 [默认0.0.0.0/ 8126]title覆盖进程标题 [默认statsd]设为 false 则不覆盖标题长度须不超过二进制名 CLI 参数长度healthStatusStatsD 启动时的默认健康状态 [up或down默认up]dumpMessages记录所有收到的消息flushInterval向各后端 flush 指标的间隔mspercentThreshold计时器百分位阈值可为单个值或浮点值列表负值表示取top N 百分位 [默认 90]flush_counts是否发送stats_counts指标 [默认 true]keyFlush记录最频繁发送的 key [对象默认 undefined]interval记录频繁 key 的频率 [ms默认 0]percent记录高频 key 的百分比 [默认 100]log高频 key 日志文件位置 [默认 STDOUT]deleteIdleStats不向 graphite 发送空闲计数器/集合/仪表/计时器的值而非发送 0对仪表而言是取消设置而非发送旧值。可被各 delete 项单独覆盖 [默认 false]deleteGauges不发送空闲仪表值默认发送旧值[默认 false]gaugesMaxTTL仪表被标记为空闲前等待的 flush 周期数与deleteGauges配合使用 [默认 1]deleteTimers/deleteSets/deleteCounters不发送空闲计时器/集合/计数器默认发送 0[默认 false]prefixStats本实例统计数据的命名前缀 [默认statsd]对 legacy 与新命名空间均生效keyNameSanitize入口处净化所有指标名 [默认 true]若关闭则由后端按自身存储要求净化对应 stats.js 中sanitizeKeyName的空格转_、/转-、非法字符剔除逻辑calculatedTimerMetrics要发送的计时器指标列表默认发送全部按百分位过滤时在指标名后追加_percent如[count, median, upper_percent, histogram]console.prettyprint是否美化 console 后端输出 [默认 true]log日志设置 [默认 undefined]backendstdout或syslog[默认stdout]applicationsyslog 应用名 [默认statsd]level日志级别 [默认LOG_INFO]graphite.legacyNamespace / globalPrefix / prefixCounter / prefixTimer / prefixGauge / prefixSet见上文命名空间一节graphite.globalSuffix发送给 graphite 的全局后缀 [默认 ]适合按主机区分统计例如设为require(os).hostname().split(.)[0]repeater数组元素为{ host, port }指明收到的数据包要重复复制发送到的其他 statsd 服务器如[ { host: 10.10.10.10, port: 8125 }, { host: observer, port: 88125 } ]repeaterProtocolrepeater 使用的协议udp4、udp6或tcp[默认udp4]histogram见上文直方图一节默认[]automaticConfigReload是否监听配置文件并在变更时重载 [默认 true]设 false 关闭。最小可用配置示例即 exampleConfig.js 底部实际给出的默认值{ graphitePort: 2003 , graphiteHost: graphite.example.com , port: 8125 , backends: [ ./backends/graphite ] }调试与排障README 明确给出的调试配置变量debug记录异常并输出更多诊断信息dumpMessages打印收到的每条消息的调试信息。两者在 stats.js 中均有对应逻辑debug模式下加载服务器/后端时会输出 DEBUG 日志dumpMessages开启时每条消息会被记录。更多细节见 exampleConfig.js。另外docs/admin_interface.md 提到可用health命令配合监控health单独执行查看当前状态health up|down改变状态healthStatus配置项设置启动默认值——这些组合可以很方便地接入外部健康检查。运行测试项目使用 nodeunit 框架并配有自定义的启动/操控 StatsD 的测试代码。任何新功能或 bug 修复都应在 test/ 目录下补充测试。README 提醒实时服务器的测试较为微妙已尽力消除竞态条件但仍可能偶发卡死开发时可用killall statsd清理后台残留的测试服务器切勿在生产机器上执行。执行测试的方式以仓库实际内容为准node run_tests.js或通过 package.json 的脚本执行npm test内部同样是node run_tests.js。测试框架入口见 run_tests.js它会加载 nodeunit 并运行test/目录下的全部用例失败时以非零码退出。测试覆盖范围可从 test/ 目录窥见一斑例如graphite_tests.js、graphite_legacy_tests.js、process_metrics_tests.js、server_tests.js、set_tests.js等分别对应 Graphite 后端、指标处理、服务器与集合等核心模块。历史与灵感StatsD 最初由Etsy开发并随一篇详细讲解其工作原理与诞生缘由的博客文章一同发布。它的设计严重地受启发于 Flickr 的同名项目后者由 Cal Henderson 撰写深度介绍并开源了 Perl 版实现。这些背景解释了 StatsD 为何选择极简行协议 服务器端聚合 可插拔后端这一架构让客户端发送开销降到最低把聚合与存储的复杂度收敛到服务端。【免费下载链接】statsdDaemon for easy but powerful stats aggregation项目地址: https://gitcode.com/gh_mirrors/st/statsd创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考