在现代后端系统中，监控与可观测性已经成为必不可少的基础能力。我们不仅需要知道服务是否“挂掉”，还需要实时了解服务的“健康程度”，例如接口耗时、请求量、错误率、队列长度、系统资源使用等。这些指标帮助我们快速定位问题、优化性能、以及构建更智能的告警系统。
在这些场景中，一个非常常见的基础组件就是 StatsD。今天我们就来讲讲 StatsD 是什么、有什么用、以及如何使用 PHP 的 league/statsd 客户端进行指标上报。
什么是 StatsD？
StatsD 最初由 Etsy 开发，是一个基于 UDP 的轻量级指标聚合服务，用来接收应用发送的实时指标。它不负责存储，也不负责可视化，而是将聚合后的数据发送给后端系统，如：
- Graphite
- Datadog
- Prometheus + StatsD exporter
- Telegraf
- InfluxDB
StatsD 的核心特点：
- 轻量级：基于 UDP，无阻塞
- 高性能：每秒处理百万级别的上报
- 聚合能力：支持计数、计时、gauge 等多种指标类型
- 通用性强：语言无关，任何系统都可以通过 UDP 上报
StatsD 能做什么？
StatsD 并不是性能监控的最终系统，但它承担着非常关键的角色——让应用“说话”。
你可以用它上报：
✔ 1. 接口请求吞吐量（QPS）
example.api.requests:1|c
````
### ✔ 2. 接口响应耗时
example.api.time:150|ms
### ✔ 3. 系统运行状态（Gauge）
memory.usage:512|g
queue.length:3|g
### ✔ 4. 业务指标
* 每分钟新增订单数量
* 活跃用户数量
* 缓存命中率
* 支付成功数
### ✔ 5. 告警场景
配合 Datadog、Grafana、Prometheus，你可以轻松设置阈值告警，例如：
* API 错误率 > 5%
* 接口耗时 P95 > 200ms
* 队列积压 > 1000
---
# `league/statsd` 是什么？
`league/statsd` 是 PHP 世界中早期较为流行的 StatsD 客户端之一，它提供了一套简单优雅的 API，使你能够方便地将指标从 PHP 应用发送到 StatsD 服务。
虽然它已经被归档（不再维护），但仍然可以正常使用。
---
# 使用场景
## 🔧 1. REST API 的性能监控
记录每个接口的 QPS 和耗时：
$client->increment('api.order.create.qps');
$client->timing('api.order.create.time', $duration);
## 🧮 2. 业务指标监控
如订单创建数、支付次数、活跃用户数：
$client->increment('business.order.create');
## 📊 3. 队列与后台任务监控
记录任务耗时、队列长度等：
$client->gauge('queue.email.length', $queueLength);
## 💡 4. 系统健康监控
例如内存使用率、缓存命中率：
$client->gauge('system.memory.usage', $memory);
---
# 如何使用 `league/statsd`
## 1. 安装
composer require league/statsd:^0.1@beta
## 2. 初始化
use League\StatsD\Client as StatsD;
$client = new StatsD();
$client->configure([
'host' => '127.0.0.1',
'port' => 8125,
'namespace' => 'app',]);
## 3. 上报指标
### 🔢 计数器（Counter）
$client->increment('order.created');
### 📏 计时（Timing）
$start = microtime(true);
// Some code...
$duration = (microtime(true) - $start) * 1000;
$client->timing('order.process.time', $duration);
### ⚖ Gauge
$client->gauge('redis.connections', 12);
---
# 为什么要用 StatsD？
| 特点 | 说明 |
| ---- | ---------------------------------------- |
| 性能极高 | UDP 上报，不会阻塞业务代码 |
| 使用简单 | 少量代码即可接入 |
| 通用性强 | 任何语言都可以发送 UDP 包 |
| 扩展性强 | 配合 Graphite/Prometheus/Datadog 实现强大的监控体系 |
对于中高并发的服务来说，StatsD 是一种 **成本极低、效果极高** 的指标上报方式。
---
# 总结
StatsD 是一个简单却非常强大的监控基础组件，它适合用于：
* 应用性能监控
* 业务指标统计
* 异步任务监控
* 系统状态监控
* 构建实时数据驱动的告警系统
`league/statsd` 虽然不再维护，但是仍然是 PHP 项目接入 StatsD 的一个轻量级解决方案。
如果你正在构建监控体系，StatsD 会是一个非常值得尝试的指标上报基础设施。