在现代后端系统中，监控与可观测性已经成为必不可少的基础能力。我们不仅需要知道服务是否“挂掉”，还需要实时了解服务的“健康程度”，例如接口耗时、请求量、错误率、队列长度、系统资源使用等。这些指标帮助我们快速定位问题、优化性能、以及构建更智能的告警系统。

在这些场景中，一个非常常见的基础组件就是 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 会是一个非常值得尝试的指标上报基础设施。