PHP 应用 OpenTelemetry 实战：日志、链路与指标的统一观测

OpenTelemetry（OTel）是云原生可观测性的开放标准，把链路（Trace）、指标（Metric）、日志（Log）三支柱统一到一套协议（OTLP）与 SDK 之下。PHP 的 OTel 支持近年快速成熟——自动埋点扩展让 Laravel/Symfony 应用几乎零代码接入。本文讲解 PHP 应用接入 OpenTelemetry 的路径，以及与观测云平台的整合方案。

核心要点速览

• OpenTelemetry PHP = SDK + 自动埋点扩展：opentelemetry PECL 扩展 + 各框架 instrument 包，零代码采集 HTTP/数据库/缓存调用链。
• OTLP 是统一出口：traces/metrics/logs 三类数据走同一协议发往采集端。
• trace_id 是日志与链路的桥梁：日志记录带上 trace_id，观测云中日志 ↔ APM 双向跳转。
• 观测云 DataKit 原生支持 OTLP 接收：PHP 应用直推 DataKit 即可完成全量接入。

OpenTelemetry 给 PHP 带来什么？

传统 PHP 可观测性的痛点：FPM 无状态、进程模型特殊、社区方案碎片化。OTel 的解题思路：

1. 自动埋点：PECL 扩展在引擎层 hook 框架与扩展函数（PDO、Guzzle、Laravel 路由……），不用改业务代码即生成调用链；
2. 上下文传播：traceparent 头在服务间传递 trace_id，跨 PHP/Go/Java 服务的链路无缝串联；
3. 日志关联：Logger 上下文自动注入 trace_id/span_id，日志成为链路的证据。

接入步骤：自动埋点 + OTLP 导出

# 1. 安装 OTel 扩展（PECL）
pecl install opentelemetry

# 2. 安装 SDK 与自动埋点包
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp \
  open-telemetry/auto-laravel

环境变量配置（推荐，零代码）：

OTEL_PHP_AUTOLOAD_ENABLED=true
OTEL_SERVICE_NAME=order-api
OTEL_TRACES_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://datakit:4318
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_PROPAGATORS=tracecontext,baggage

启动后，每个进入 PHP-FPM 的 HTTP 请求自动生成 span，PDO/Guzzle 调用成为子 span，经 OTLP 发往 DataKit。

日志与 trace_id 关联

自动埋点把 trace 上下文放进当前协程/进程上下文，Monolog 侧用 Processor 注入：

use OpenTelemetry\API\Trace\Span;

$logger->pushProcessor(function ($record) {
    $span = Span::getCurrent();
    $ctx = $span->getContext();
    if ($ctx->isValid()) {
        $record->extra["trace_id"] = $ctx->getTraceId();
        $record->extra["span_id"] = $ctx->getSpanId();
    }
    return $record;
});

之后每条业务日志都带 trace_id——排障时从一条错误日志直达完整调用链。

观测云落地：DataKit 接收 OTLP

观测云 DataKit 内置 OpenTelemetry 接收器，PHP 应用的数据流：

1. DataKit 侧：开启 OTel 输入插件（默认 4317 gRPC / 4318 HTTP 端口），接收 traces/metrics；
2. 应用侧：OTEL_EXPORTER_OTLP_ENDPOINT 指向 DataKit 地址，数据直达；
3. 链路查看：观测云 APM 中按服务（order-api）查看调用链、耗时分布、错误 span；
4. 日志联动：带 trace_id 的日志由 DataKit 日志采集进入观测云，APM 详情页关联展示同链路日志，反向也可从日志跳链路；
5. 指标：OTel 自动埋点产生的请求数/延迟指标在观测云仪表板可视化，配合监控器告警（钉钉/企业微信/飞书）。

常见问题（FAQ）

PHP-FPM 短生命周期会不会导致链路数据丢失？

OTel PHP SDK 在请求结束时批量导出（BatchSpanProcessor），正常请求不会丢；FPM 异常终止时未导出的 span 会丢——配合 DataKit 就近部署（同机 DaemonSet）把网络风险降到最低。

性能开销大吗？

自动埋点带来约 5%-15% 的额外开销（视埋点密度）。可通过采样率（OTEL_TRACES_SAMPLER=traceidratio，如 0.2）控制——生产常规 10%-20% 采样即可兼顾成本与排障需求。

不用 OTel 扩展，纯 Composer 包能埋点吗？

可以但费力：需要手动在框架中间件/事件里创建 span。PECL 扩展 + auto-instrumentation 包是目前性价比最高的方式；无法装扩展的环境可用框架中间件做"半自动"埋点。

观测云还支持哪些 PHP 链路方案？

除 OpenTelemetry 外，观测云还支持 SkyWalking、Zipkin、Jaeger 等主流探针数据接入；但 OTel 是 CNCF 标准、生态最活跃，新接入一律推荐 OTel。

系列阅读

• 上一篇：PHP 日志库五款对比
• 下一篇：MySQL 日志详解
• 相关阅读：微服务日志最佳实践 ｜ 什么是日志监控

---