PHP 可观测性的庖丁解牛

PHP 可观测性（Observability）不是简单的“加日志”，而是通过结构化数据（Logs、Metrics、Traces）构建系统行为的可推理模型，使开发者能在不重启、不登录服务器的情况下，精准定位性能瓶颈与故障根因。

一、可观测性三大支柱

💡核心认知：
可观测性 = Logs（发生了什么） + Metrics（整体状态如何） + Traces（具体路径怎样）

二、PHP 原生能力与扩展支持

▶ 1.Logs：从 error_log 到结构化日志

• 原生日志：
  • error_log()→ 纯文本（难解析）
• 结构化日志：

  // Monolog + JsonFormatter$logger=newLogger('app');$logger->pushHandler(newStreamHandler('php://stderr'));$logger->pushProcessor(newWebProcessor);// 自动添加 request_id$logger->info('User login',['user_id'=>123]);

  • 输出：

    {"message":"User login","context":{"user_id":123},"extra":{"request_id":"abc123"}}

▶ 2.Metrics：暴露系统指标

• OPcache 指标：

  // /metrics 端点$stats=opcache_get_status();echo"opcache_memory_usage{state=\"used\"} ".$stats['memory_usage']['used_memory'];

• Prometheus 集成：

  usePrometheus\CollectorRegistry;$registry=newCollectorRegistry();$counter=$registry->registerCounter('http','requests_total','Total HTTP requests');$counter->inc();

▶ 3.Traces：分布式链路追踪

• OpenTelemetry PHP SDK：

  useOpenTelemetry\SDK\Trace\TracerProvider;$tracer=(newTracerProvider())->getTracer('app');$span=$tracer->spanBuilder('database.query')->startSpan();// 执行 SQL$span->end();

• 自动注入 TraceID：
  • 通过 Nginx 传递traceparent头
  • PHP 自动关联日志与链路

三、工程实践：生产级可观测性架构

▶ 1.日志：集中式收集

• 关键配置：
  • Laravel 日志驱动设为stderr+JsonFormatter
  • Dockerfile 重定向error_log = /proc/self/fd/2

▶ 2.指标：实时监控

• 暴露端点：

  # Nginx 配置 location /metrics { allow 10.0.0.0/8; # 仅内网访问 deny all; fastcgi_pass php-fpm; include fastcgi_params; fastcgi_param SCRIPT_FILENAME /app/metrics.php; }

• Grafana 面板：
  • QPS、错误率、OPcache 命中率、内存使用率

▶ 3.链路追踪：全链路分析

• Jaeger UI 展示：

  [HTTP Request] → [Laravel Middleware] → [MySQL Query] → [Redis Get] │ │ │ │ Duration: 120ms Duration: 50ms Duration: 30ms Duration: 10ms

• 关键字段：
  • trace_id：全局唯一标识
  • span_id：当前操作 ID
  • parent_span_id：父操作 ID

四、避坑指南

五、终极心法

**“可观测性不是工具，
而是推理的骨架——

• 当你结构化日志，
  你在记录事件；
• 当你暴露指标，
  你在量化状态；
• 当你追踪链路，
  你在还原路径。

真正的系统掌控，
始于对数据的敬畏，
成于对细节的精控。”

结语

从今天起：

1. 所有日志输出 JSON 格式到 stderr
2. 暴露/metrics端点（内网访问）
3. 集成 OpenTelemetry 实现链路追踪

因为最好的系统稳定性，
不是祈祷不崩，
而是让每一比特都可被推理。