直接用 composer require datadog/php-datadogstatsd 安装后，必须配置 Datadog Agent 监听 UDP 8125 端口、确保 PHP 进程可连通 Agent、初始化客户端时显式指定 host/port/use_socket、每次发指标都手动传 service/env 标签，否则数据将静默丢失。
直接用 composer require datadog/php-datadogstatsd 就能装上，但装完不配置或乱配，StatsD 客户端根本发不出数据——Datadog Agent 默认不监听 UDP 8125，PHP 进程也未必能连通本地 Agent。
确认 Datadog Agent 是否已就绪并开放 StatsD 端口
PHP 的 php-datadogstatsd 库本质是 StatsD 协议客户端，它只负责发 UDP 包，不处理转发、采样或上报逻辑。所有指标最终必须由运行在同机（或网络可达）的 Datadog Agent 接收并转给 Datadog 后端。
- 检查 Agent 配置文件（通常为
/etc/datadog-agent/datadog.yaml），确认statsd_port: 8125未被注释且值为8125 - 运行
sudo datadog-agent status，查看输出中statsd项是否显示Running - 手动测试连通性：
echo -n "test.metric:1|c" | nc -u -w1 127.0.0.1 8125，再查 Agent 日志（/var/log/datadog/agent.log）是否有收到该 metric 的记录 - 若 PHP 运行在 Docker 容器里，Agent 不在同容器时，不能写
127.0.0.1——得用宿主机 IP 或host.docker.internal（Docker Desktop/macOS/Windows）或自定义网络网关 IP
安装 php-datadogstatsd 并初始化客户端
该库不依赖扩展，纯 PHP 实现，但默认使用 UDP，无重试、无队列，发包失败即丢弃——这是设计使然，不是 bug。
- 执行
composer require datadog/php-datadogstatsd，会安装v1.6.0（截至 2024 年主流版本），注意它不支持 PHP 8.3+ 的某些弃用语法，若报错需锁版本或等更新 - 初始化时建议显式传参，避免依赖默认值：
$client = new \DataDog\StatsD( ['host' => '127.0.0.1', 'port' => 8125, 'use_socket' => true] ); -
use_socket => true强制使用 socket 扩展（而非 stream），提升小包发送稳定性；若服务器没开ext-sockets，会退化为 stream，但部分环境（如某些 Alpine 容器）需额外apk add php82-sockets - 不要在长生命周期脚本（如 Swoole Worker）里反复 new 客户端——复用一个实例即可，它本身是无状态的
发指标前必须加 service 和 env 标签
Datadog 后台靠 service 和 env 标签做维度聚合与过滤。库本身不自动注入，全靠你在每个 increment()、gauge() 调用里手动传 ['tags' => [...]]。
立即学习“PHP免费学习笔记（深入）”；
- 漏传
service标签，指标在 Datadog UI 里会归到unnamed-service，无法和 APM 追踪对齐 - 典型写法：
$client->increment('app.login.attempt', 1, ['tags' => [ 'service:my-web-app', 'env:prod', 'region:us-east-1' ]]); - 标签值不能含空格或冒号，否则会被截断；推荐统一用
kebab-case格式，比如user-type:guest而非user type:guest - 高频打点（如每请求都记）建议批量调用
batch()方法减少 socket 调用次数，但要注意 batch 有长度限制（默认 50 条），超限会自动 flush
最常被忽略的是：Agent 配置改了不重启、PHP 进程缓存了旧的 StatsD 实例、标签格式非法导致整条 metric 被 Agent 静默丢弃——这些都不会抛异常，只会让你在 Datadog 控制台里等半天看不到数据。
