PHP 全链路追踪实践：trace_id 生成与透传

2. 透传 trace_id（调用下游）

Redis 客户端（需支持）：

// Predis 不直接支持，但可记录日志
Log::info('Redis GET', ['trace_id' => $traceId, 'key' => $key]);

cURL 调用第三方 API：

$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-Request-ID: ' . ($traceId ?? ''))];

3. 日志注入 trace_id（关键！）

输出 JSON 日志：

{"message":"User login","context":{"user_id":123,"trace_id":"a1b2c3d4"}}

Monolog 示例：

use Monolog\Processor\ProcessorInterface;

class TraceIdProcessor implements ProcessorInterface
{
    public function __invoke(array $record): array
    {
        $record['context']['trace_id'] = $_SERVER['HTTP_X_REQUEST_ID'] ?? null;
        return $record;
    }
}

$logger->pushProcessor(new TraceIdProcessor());

三、工具集成：与 APM 系统联动

1. Datadog APM（自动集成）

• 自动注入 trace_id：
  • 所有日志自动包含 dd.trace_id、dd.span_id；
  • 无需手动透传（扩展自动处理 cURL、Redis、DB）；
• 效果：
  • 点击 Trace → 查看 SQL → 查看日志 → 查看主机指标；

安装 dd-trace 扩展：

sudo apt-get install datadog-php-tracer

2. Jaeger / Zipkin（开源方案）

使用 OpenTelemetry PHP SDK：

use OpenTelemetry\API\Trace\TracerProvider;
use OpenTelemetry\SDK\Trace\TracerProvider as SdkTracerProvider;

$tracer = (new SdkTracerProvider())->getTracer('my-app');
$span = $tracer->spanBuilder('http-request')->startSpan();
$span->setAttribute('http.method', $_SERVER['REQUEST_METHOD']);

// 透传到下游
$propagator = new TraceContextPropagator();
$propagator->inject($span->getContext(), new RequestHeadersSetter($_SERVER));

3. 自建 ELK（日志关联）

Kibana 中用 trace_id 聚合日志：

trace_id: "a1b2c3d4" → 显示全链路日志

Filebeat 解析 trace_id：

# filebeat.yml
processors:
  - dissect:
      tokenizer: '{"trace_id":"%{trace_id}}'
      field: "message"
      target_prefix: "log"

四、工程实践：全链路追踪的黄金准则

1. 统一透传标准

• 强制所有服务使用 X-Request-ID；
• 内部调用必须透传（中间件自动处理）；

2. 日志必须含 trace_id

• 无 trace_id 的日志 = 无效日志；
• JSON 格式 + 结构化字段；

3. 监控与告警

错误率告警：

rate(trace.php.request.errors{service:api}) / rate(trace.php.request.hits{service:api}) > 0.01

慢请求告警：

avg(last_5m):trace.php.request.duration{service:api} > 1000

4. 故障复盘

• 用 trace_id 复现问题：
  • '用户 ID 123 投诉支付失败' →
  • 查日志 user_id:123 → 找到 trace_id → 查全链路；

五、高危误区

1. 误区：'手动拼接 trace_id 就够了'

• 真相：
  • cURL、Redis、DB 调用需自动透传；
  • 手动易遗漏，必须用 APM 扩展；

2. 误区：'日志有 trace_id 就能关联'

• 真相：
  • APM 系统需统一 trace_id 格式（如 Datadog 用 dd.trace_id）；
  • 自建系统需确保日志解析正确；

3. 误区：'全链路追踪只用于故障排查'

• 真相：
  • 核心价值在'预防'：
    • 发现慢 SQL 趋势；
    • 监控服务依赖健康度；
    • 量化功能上线影响；

六、实施步骤

1. 生成 trace_id：Nginx 或 PHP 入口生成 X-Request-ID
2. 日志注入：Monolog 添加 TraceIdProcessor
3. 透传下游：cURL 调用添加 X-Request-ID 头
4. 集成 APM：安装 dd-trace 或 OpenTelemetry SDK
5. 验证穿透：模拟请求 → 用 trace_id 查全链路日志