PHP 可观测性实战：日志、指标、链路追踪与 APM

一条慢请求 → Trace 揭示"DB 查询慢" → 关联 Log 看具体 SQL → Metrics 显示"DB 连接池饱和"
三支柱互补：Trace 带 Span ID / Trace ID → Log 带相同 ID → Metrics 按标签聚合 → 三条线索串成完整故障图

Logger：记录消息的入口
Handler：决定怎么处理/发往哪（文件/数据库/远程/邮件）
Formatter：格式化输出（LineFormatter/JsonFormatter/HtmlFormatter）
Processor：添加额外上下文（WebProcessor/IntrospectionProcessor）

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Formatter\JsonFormatter;

$logger = new Logger('app');
$logger->pushHandler(
    new RotatingFileHandler(__DIR__.'/logs/app.log', 7, Logger::INFO)
);

// 错误级别单独文件
$errorHandler = new StreamHandler(__DIR__.'/logs/error.log', Logger::WARNING);
$logger->pushHandler($errorHandler);

// JSON 格式化
$logger->getHandlers()[0]->setFormatter(new JsonFormatter());

非结构化："User admin logged in from 192.168.1.1 at 2024-01-15 10:00"
结构化：{"@timestamp":"2024-01-15T10:00:00Z","event.action":"login","user.name":"admin","source.ip":"192.168.1.1"}
# 结构化 = 可查询、可聚合、可索引；搜索引擎和 SIEM 的基石

# Elastic 定义的标准字段命名
@timestamp      时间
message         原始消息
event.action    事件动作（login/logout/create）
user.name       用户名
source.ip       来源 IP
http.request.method   HTTP 方法
service.name    服务名

// config/logging.php 自定义 channel
'elastic' => [
    'driver' => 'custom',
    'via' => App\Logging\ElasticLoggerFactory::class,
    'tap' => [App\Logging\AddEcsMetadata::class],
],

// Processor 添加上下文
$logger->pushProcessor(function ($record) {
    $record['extra']['request_id'] = request()->header('X-Request-ID');
    $record['extra']['user_id'] = auth()->id();
    return $record;
});

Trace：一次请求的完整链路（如 API 调用）
Span：链路中的一个操作（如 DB 查询、HTTP 调用）
SpanContext：Trace ID + Span ID + Flags（传递上下文）
Baggage：跨 Span 传递的键值对（用户 ID、租户 ID）

composer require open-telemetry/sdk
composer require open-telemetry/exporter-otlp

# 初始化 Tracer
$tracerProvider = (new TracerProviderBuilder())
    ->addSpanProcessor(new BatchSpanProcessor(
        new OTLPExporter(new Client(), StreamFactory::create(), new HttpTransport())
    ))
    ->build();

# 创建 Trace
$span = $tracerProvider->getTracer('app')->spanBuilder('process-order')->startSpan();
$span->setAttribute('order.id', $orderId);

# 嵌套 Span
$childSpan = $tracerProvider->getTracer('app')
    ->spanBuilder('db-query')
    ->setParent($span->storeInContext($context))
    ->startSpan();
$childSpan->end();
$span->end();

# Laravel 用 open-telemetry/opentelemetry-auto-laravel
# 自动追踪 Controller、DB 查询、Queue Job、Cache 操作
# 配置 OTEL_EXPORTER_OTLP_ENDPOINT → Jaeger/Tempo/Datadog Agent

composer require laravel/telescope --dev
php artisan telescope:install

# 自动记录：请求、异常、日志、数据库查询、队列、邮件、通知、缓存、调度
# 生产环境：telescope:prune 定期清理，或 filter 只记慢查询/异常
# 不适合：高流量生产环境的实时APM

# 安装 PHP Agent → 修改 php.ini
newrelic.appname = "MyApp"
newrelic.license = "..."

# 自动追踪：Web Transctions、DB、外部调用、错误
# Dashboard：Apdex、吞吐量、错误率、慢事务追踪
# 成本：按主机数计费，小团队偏贵

# 安装 dd-trace-php
DD_AGENT_HOST=localhost ddtrace-php

# 功能：APM + 基础设施监控 + 日志 + 安全检测
# 优势：一键关联「慢请求对应的日志和主机指标」
# 成本：按主机 + 按量计费

# 专用 PHP 性能分析工具
# CPU 时间、内存消耗、I/O 时间、函数调用图
# 集成：CLI、PHPUnit、Symfony/Laravel Profile
# 定位：代码级瓶颈（不是系统级 APM）

# Counter：只增（请求数、错误数）
# Gauge：可增可减（内存使用量、队列长度）
# Histogram：分布（响应时间分桶）
# Summary：分位数

// 用 Jimdo/prometheus_client_php
$registry = new CollectorRegistry(new RedisAdapter());

$counter = $registry->getOrRegisterCounter('app', 'requests_total', 'Total requests', ['method', 'endpoint']);
$counter->inc(['GET', '/api/users']);

$histogram = $registry->getOrRegisterHistogram('app', 'response_time', 'Response time', ['endpoint'], [0.01, 0.05, 0.1, 0.5, 1, 2, 5]);
$histogram->observe($duration, ['/api/users']);

// 暴露端点：/metrics → Prometheus 抓取

# 入口层：请求数、错误率、响应时间 P99
# 业务层：订单创建数、支付成功率、用户注册数
# 资源层：DB 连接数、Redis 命令/秒、队列积压长度
# 标签（Labels）： endpoint/method/status/service → 高基数标签会爆炸存储

Logstash/Filebeat → 收集日志
Elasticsearch → 索引存储
Kibana → 可视化查询

# Filebeat 轻量采集器 → Logstash 解析转换 → ES 索引 → Kibana 看板
# 成本：ES 内存要求不低，日志量大时存储成本高

# 只索引标签（不索引日志内容）→ 成本低、水平扩展
# Promtail 采集 → Loki 存储 → Grafana 查询
# 查询用 LogQL：{app="api", env="prod"} |= "error" | json | line_format "..."
# 与 Prometheus 共享标签体系 → 关联 Metrics + Logs

# Serverless：CloudWatch Logs（AWS）/Cloud Logging（GCP）/Azure Monitor
# SaaS：Logtail/Sematext（按量付费）
# 自建：rsyslog → 本地文件 → 定期压缩归档（冷数据）

// Laravel 健康检查
Route::get('/health', function () {
    $checks = [
        'db' => DB::connection()->getPdo() ? 'ok' : 'fail',
        'cache' => Cache::store()->get('health-check') !== false ? 'ok' : 'fail',
        'queue' => Queue::size() < 1000 ? 'ok' : 'warn',
    ];
    $status = in_array('fail', $checks) ? 503 : 200;
    return response()->json($checks, $status);
});

# Prometheus Alertmanager 规则
- alert: HighErrorRate
  expr: rate(app_requests_total{status=~"5.."}[5m]) > 0.05
  for: 5m
  labels: severity: critical
  annotations: summary: "错误率 > 5% 持续 5 分钟"

- alert: SlowResponse
  expr: histogram_quantile(0.99, rate(app_response_time_bucket[5m])) > 2
  for: 3m
  labels: severity: warning

# PHP-FPM 每个请求独立进程 → 内存态不共享
# 问题：Trace Context 不能存在内存变量，必须传 HTTP Header 或存外部（Redis）
# 解决：OpenTelemetry 的 Baggage 通过 Header 传递

# PHP 进程请求结束即销毁 → 内存缓冲（Buffer）易丢失
# 日志：必须用写文件/网络的方式缓冲，不能攒内存
# Trace Batch：Monolog BufferHandler 在外部维护，或每次请求后 flush

# 默认 PHP-FPM 同步 → 外部 API 调用阻塞进程
# Trace Spans 会显示「外部调用占 90% 时间」→ 这是架构问题不是代码问题
# 考虑：ReactPHP/Swoole 异步，或 Gateway 层聚合外部请求

# OpCache 缓存编译后字节码 → 代码更新后仍可能执行旧逻辑
# 问题：观测到「旧 Bug 还存在」，但文件已改
# 解决：部署后 reload PHP-FPM / 新进程自然淘汰旧进程