各位 PHP 开发者，大家好！
想象一下这样一个场景：你的应用在生产环境上高歌猛进，流量如潮水般涌来，但在此时此刻，某个核心接口突然卡顿了。你站在服务器前，盯着灰屏的终端，只能祈祷：“上帝啊，别崩，别崩。”
这就是我们——光荣的 PHP 开发者——每天面临的“黑暗料理”：我们就像是在暴风雨中蒙着眼睛做菜，不知道锅里的水开了没有，也不知道盐放多了没有，只知道最后端上来一盘“500 Internal Server Error”。
今天，我们不聊怎么把代码写得优雅，也不聊怎么优化 SQL，我们来聊聊如何给你的 PHP 应用装上“透视眼”。我们将要探讨的是：OpenTelemetry —— 这可是近年来云原生时代的“瑞士军刀”，以及如何利用它结合 Prometheus 和 Jaeger，把你的 PHP 应用变成一个全链路透明、数据可视化的“大白”。
准备好了吗？我们要开始“可观测性”的修炼之旅了。
第一章：如果你看不见，就不存在
首先，我们要纠正一个经典的误区：Debug（调试） 和 Observability（可观测性） 是两码事。
Debug 是当你知道哪里出了问题，试图去修复它；Observability 是当你不知道哪里出了问题，试图通过外部信号来推断它。
以前我们写 PHP，最常用的手段就是 var_dump、echo，或者写日志。但那就像是给病人做体检，你只看到病人说“我头有点疼”，但不知道是感冒还是脑震荡。真正的可观测性需要三个维度：
- Logs（日志）： 就像病人的病历，记录发生了什么。
- Metrics（指标）： 就像体温计、血压计，记录数值变化（如 QPS、错误率）。
- Traces（追踪）： 就像监控探头，记录事情发生的时间线和路径。
今天，我们要重点解决的是 Traces（全链路追踪）和 Metrics（指标监控）这两块硬骨头。而连接这三者的标准桥梁，就是 OpenTelemetry。
第二章：OpenTelemetry —— 编程界的 HTTP 协议
你可能听说过 OpenTelemetry（简称 OTel）。如果你听到有人把它吹捧成“宇宙最强监控库”，千万别信。它其实更像是一种协议，或者更确切地说，是监控领域的 HTTP。
以前，Java 有 Zipkin，Python 有 Jaeger，Go 有 SkyWalking，PHP 呢？PHP 以前是没有统一标准的，各家厂商各自为战，搞得你换一个框架就像换了一个世界。这太糟糕了。
OpenTelemetry 的伟大之处在于：它不管你用什么语言，也不管你用什么数据库。它只负责把你的调用关系变成一种通用的数据格式（通常是 TraceContext），然后扔给 Collector，或者直接扔给监控后台。
它就像是给所有的微服务都装上了一个统一的身份证系统。我们在 PHP 里引入 OpenTelemetry，就像是给每一个 HTTP 请求都挂了一个 GPS 定位器。
第三章：搭建舞台 —— Composer 与基础配置
好，废话不多说，开始动手。我们要用 Composer 安装 OpenTelemetry 的 PHP SDK。在 composer.json 中，我们需要引入几个核心包：
{
"require": {
"open-telemetry/opentelemetry-php-autoconfigure": "^1.0",
"open-telemetry/opentelemetry-php-sdk": "^1.0",
"open-telemetry/exporter-jaeger": "^1.0",
"open-telemetry/exporter-prometheus": "^1.0"
}
}autoconfigure：这是官方提供的一个懒人包，它会自动帮你配置大部分环境，不需要你从头去写那个让人头大的Resource和TracerProvider初始化代码。exporter-jaeger：用来把链路追踪数据发给 Jaeger（可视化工具）。exporter-prometheus：这是我们要的关键，直接把指标数据暴露给 Prometheus 抓取。
安装完之后，你不需要在代码里做太多复杂的配置。因为 SDK 里有智能的自动发现机制。它会自动抓取 OTEL_SERVICE_NAME 环境变量，如果你的代码里没有显式设置，它甚至会尝试读取 composer.json 里的 name 字段。
第四章：全链路追踪 —— 让每个请求都有“身份证”
这是最酷的部分。我们要实现的效果是：用户发起一个请求，经过 PHP 后端，调用 MySQL，再调用 Redis，最后返回给用户。在这个过程中，每一个步骤都有一个唯一的 ID（Trace ID）和父 ID，形成一棵树状结构。
1. 自动追踪中间件
在 PHP 世界里，我们很少在业务代码里手写 startSpan（虽然官方 SDK 支持这样做），因为那样会导致代码极其丑陋。最优雅的方式是利用 Middleware（中间件）。
假设你用的是 Laravel 或者 Symfony，或者是自定义的 PSR-7 ServerMiddleware，我们可以这样写：
use OpenTelemetrySdkTraceTracerProvider;
use OpenTelemetryContribJaegerExporter as JaegerExporter;
use OpenTelemetryContribPrometheusExporter as PrometheusExporter;
use PsrHttpMessageResponseInterface;
use PsrHttpMessageServerRequestInterface;
use PsrHttpServerRequestHandlerInterface;
// 1. 全局初始化 Provider（通常放在 bootstrap 里，只运行一次）
$tracerProvider = new TracerProvider();
$tracer = $tracerProvider->getTracer('my-awesome-php-service');
// 2. 初始化 Jaeger 导出器（用于链路可视化）
$jaegerExporter = new JaegerExporter(['endpoint' => 'http://localhost:14268/api/traces']);
$tracerProvider->addSpanProcessor(new OpenTelemetrySdkTraceProcessorSimpleSpanProcessor($jaegerExporter));
// 3. 初始化 Prometheus 导出器（用于指标抓取）
// 注意：这里我们直接把 HTTP 端点暴露出来，Prometheus 会定时抓它
$prometheusExporter = new PrometheusExporter();
$tracerProvider->addSpanProcessor(new OpenTelemetrySdkTraceProcessorSimpleSpanProcessor($prometheusExporter));
// 4. 这就是我们的中间件核心逻辑
$opentelemetryMiddleware = function (ServerRequestInterface $request, RequestHandlerInterface $handler) use ($tracer) {
// 获取当前 URL 作为 Span 名称
$uri = $request->getUri()->getPath();
// 开始一个新的 Span
// 注意：这个 Span 会自动成为请求的 Root Span
$span = $tracer->startSpan($uri);
// 开始事务，当代码块结束时，span 会自动关闭
// withSpan 会自动处理上下文的传播（把 Trace ID 带到 DB 查询里）
withSpan($uri, function() use ($request, $handler, $span) {
try {
// 原始处理逻辑
$response = $handler->handle($request);
$span->setStatus(OpenTelemetrySemConvStatusCodes::OK);
return $response;
} catch (Exception $e) {
$span->setStatus(OpenTelemetrySemConvStatusCodes::ERROR, $e->getMessage());
throw $e;
}
});
};看到 withSpan 了吗？这行代码就是魔术的根源。它不仅创建了一个 Span，还把当前的 Trace ID 注入到了上下文中。
2. 数据库层面的自动追踪
你可能会问：“如果我直接用 PDO 去查数据库，Trace ID 会传过去吗？”
默认情况下，PHP 的 SDK 是不知道你调用了 MySQL 的。除非你显式地把 Trace ID 放到 PDO 的连接字符串或者属性里。但是，OpenTelemetry 官方有一个著名的库叫 open-telemetry/opentelemetry-autumn（其实是 php-amqp/opentelemetry），它提供了自动注入功能。
你只需要安装这个包，然后在你的 DB 连接工厂里加上这一行：
// 获取当前的 Span Context
$spanContext = OpenTelemetryContextstoragegetContext();
// 注入到 DB 连接中
// 这会让你的所有 DB 查询自动带上 "db.system=mysql" 和 "db.statement" 属性
$pdo->setAttribute(PDO::ATTR_STATEMENT_CLASS, [
'OpenTelemetry\Instrumentation\PDO\Statement',
[$pdo, $spanContext]
]);这样，当你打开 Jaeger 看图时，你会看到这样的树状结构：
[Root] POST /api/user/login
|-- Child: SELECT * FROM users WHERE id=1 (Database)
|-- Child: GET https://api.some-third-party.com/verify (HTTP)
|-- Child: SELECT * FROM ip_blacklist (Database)这时候，如果用户投诉慢，你点开 Root Span，顺藤摸瓜，立刻就能发现是那个第三方的接口卡住了，而不是你的 PHP 代码写得烂。
第五章：Prometheus 监控 —— 数据的量化分析
如果说链路追踪是显微镜，那 Prometheus 就是计算器。
在上一节的代码中，我们已经把 PrometheusExporter 添加到了 TracerProvider 中。这意味着，我们的 PHP 服务现在不仅是一个 Web 服务器，还是一个 Metrics 服务器。
当 Prometheus 抓取我们服务器的 /metrics 端点时，它会得到什么？它不会得到“错误了”，它得到的是数字。
1. 自动生成的核心指标
OpenTelemetry SDK 非常智能，它会自动从你现有的 TracerProvider 里提取数据，并生成 Prometheus 兼容的指标。你不需要写一行代码来计算“当前在线用户数”。
它会自动生成类似这样的指标：
otel_http_server_requests_duration_seconds_bucket：记录每个接口的响应时间分布。otel_http_server_requests_total：记录每个接口的总请求数。otel_http_server_requests_duration_seconds_count：记录总请求数。
2. 自定义业务指标
有时候 SDK 自动生成的太笼统，我们需要自定义。比如，我们要监控“当前活跃的订单数量”。
use OpenTelemetrySdkMetricsMeterProvider;
use OpenTelemetrySdkMetricsMetricReaderPushMetricReader;
use OpenTelemetrySdkMetricsView;
// 获取 Meter
$meter = $meterProvider->getMeter("my-app-metrics");
// 1. 定义 Gauge（仪表）：数值可以变化，比如订单数
$activeOrders = $meter->createGauge(
"active_orders_count",
["description" => "Number of orders currently being processed"]
);
// 2. 定义 Counter（计数器）：只能增加，比如成功订单数
$successOrders = $meter->createCounter(
"success_orders_total",
["description" => "Total number of successful orders"]
);
// 在业务逻辑里：
// 订单开始处理
$activeOrders->set(100);
// 订单处理完成
$successOrders->add(1);有了这些代码，Prometheus 就能抓取到 active_orders_count 这个值，并在 Grafana 上画出一条曲线。
第六章：可视化大屏 —— Grafana 上的视觉盛宴
光有数据不行，数据必须要有形状。我们要把 Prometheus 的数据喂给 Grafana。
第一步：配置 Prometheus
在你的 prometheus.yml 文件里，添加 PHP 应用的抓取任务。因为我们刚才在 PHP 里开启了 /metrics 端点，所以这里非常简单：
scrape_configs:
- job_name: 'php_opentelemetry'
scrape_interval: 5s # 每5秒抓一次
static_configs:
- targets: ['localhost:8888'] # 假设你的 PHP 服务跑在这个端口
labels:
service: 'my-awesome-service'第二步：写一个漂亮的查询
打开 Grafana，新建 Panel，在 Query Editor 里输入：
sum(rate(otel_http_server_requests_duration_seconds_sum[5m])) by (uri)这行代码的意思是：计算过去 5 分钟内，所有接口的响应时间总和，并按 URL 分组。
你会看到一张图，上面横轴是时间，纵轴是时间（秒）。你会清楚地看到下午 3 点那个红色的尖峰是什么接口导致的，是不是某个全屏搜索接口被老板的狗皮膏药广告搞挂了。
第七章：进阶篇 —— 采样与性能
现在，你已经拥有了透视眼。但作为一个资深的工程专家，我必须给你泼一盆冷水。
采样（Sampling）。
如果你的应用一天有 1000 万次请求，你要把每一次请求都记录下来发给 Jaeger，那你的服务器会瞬间 CPU 飙升到 100%，而且 Jaeger 的数据库会瞬间爆炸。
OpenTelemetry 的核心理念是：只记录有代表性的数据。
默认情况下，SDK 会使用 父级采样策略（Parent-Based）。意思是：
- 如果根请求（用户发起的）被采样了，那么它的所有子请求（数据库查询、第三方 API）都会被记录。
- 如果根请求没被采样，那么所有子请求也不会被记录。
- 默认情况下，根请求的采样率通常是 1%（记录全部）或者 0.1%（随机采样）。
你可以通过环境变量或者代码来调整采样率：
use OpenTelemetrySdkTraceSampler;
use OpenTelemetrySdkTraceSamplingResult;
// 这是一个自定义的采样器：只要 URL 包含 "admin"，就 100% 记录
$sampler = new class implements Sampler {
public function parentBased($parentDecision): SamplingResult { return $parentDecision; }
public function shouldSample(
$parentContext,
$traceId,
$spanName,
$spanKind,
$attributes,
$links
): SamplingResult {
// 这里可以写你的逻辑
if (isset($attributes['http.route']) && strpos($attributes['http.route'], '/admin') !== false) {
return new SamplingResult(SamplingResult::RECORD_AND_SAMPLED);
}
return new SamplingResult(SamplingResult::NOT_RECORD);
}
public function getDescription(): string { return "admin_only_sampler"; }
};
$tracerProvider = new TracerProvider();
$tracerProvider->addSpanProcessor(new OpenTelemetrySdkTraceProcessorBatchSpanProcessor($jaegerExporter));
// 将采样器加进去
$tracerProvider->getSampler()->parentBased($sampler); // 具体实现取决于 SDK 版本，原理类似记住，采样率不是越低越好，也不是越高越好。 采样率低，你可能找不到 Bug；采样率高，你会变成数据库管理员。要找到平衡点。
第八章：性能开销 —— 别让你的应用变慢
在讲完高大上的概念后，我们要回归现实。PHP 是解释型语言，性能是它的生命线。OpenTelemetry 是基于上下文传播和元数据记录的，它是有开销的。
通常情况下，开启 OpenTelemetry 对性能的影响在 5% 到 15% 之间。这意味着你的 QPS 可能会从 1000 降到 850。
如何优化？
-
使用 Batch Processor（批处理器）：
不要让每个 Span 关闭时立即发送数据。使用BatchSpanProcessor，攒一批数据再发。这能极大减少网络 I/O 开销。$tracerProvider->addSpanProcessor(new OpenTelemetrySdkTraceProcessorBatchSpanProcessor($jaegerExporter, [ 'export_timeout' => 5000, // 5秒攒一次 'max_export_batch_size' => 512 ])); -
过滤不必要的属性：
不要把用户密码、信用卡号记录在 Span 的属性里。在记录之前做数据清洗。 -
关闭不必要的服务：
如果你在开发环境，把采样率调低，甚至直接关闭，别让开发机器也跑满指标。
第九章：终极实战 —— 一个完整的示例
让我们把所有东西串起来。在一个真实的 PHP Web 项目（假设是 Slim 框架）中，index.php 的样子可能是这样的：
require __DIR__ . '/vendor/autoload.php';
// 1. 初始化 OpenTelemetry
$tracerProvider = OpenTelemetrySDKConfigure::getDefault();
$tracer = $tracerProvider->getTracer('app.v1');
// 2. 注册中间件到 Slim App
$app = new SlimApp();
$app->add(function ($request, $handler) use ($tracer) {
// 开始 HTTP Server Span
$span = $tracer->startSpan("http_server_request");
// 将 span 放入上下文，让后续的 DB、RPC 调用自动继承
return withSpan("http_server_request", function() use ($request, $handler, $span) {
$response = $handler->handle($request);
// 设置 HTTP 状态码
$span->setAttribute("http.status_code", $response->getStatusCode());
return $response;
});
});
// 业务路由
$app->get('/orders/{id}', function ($request, $response, $args) {
$id = $args['id'];
// 这里我们手动开启一个子 Span，代表“查询订单详情”
withSpan("db.query_order", function() use ($id) {
// 模拟数据库查询
$data = ['id' => $id, 'status' => 'pending'];
return json_encode($data);
});
return $response->withJson(['message' => 'Order found']);
});
// 3. 启动应用
$app->run();当你启动这个服务，并访问 /orders/123 时：
- Jaeger 会收到一条 Trace，ID 为
abc123。 - 你会看到它包含一个 Root Span
GET /orders/{id}。 - Root Span 下面挂了一个 Child Span
db.query_order。 - Prometheus 会抓取到
otel_http_server_requests_duration_seconds_count，告诉你这个接口请求了 1 次。
这就是全链路追踪的闭环。
结语：告别“猜谜游戏”
各位，PHP 应用开发从来都不是一件容易的事。我们在复杂的业务逻辑、松散的代码结构、随时可能出现的数据库死锁中挣扎。
但在今天，通过 OpenTelemetry 和 Prometheus，我们手中多了一件神器。它不再是冷冰冰的监控面板，而是我们在混乱系统中导航的地图。
当你下次再遇到 500 错误，或者响应突然变慢时，不要再去数日志行数，不要再去猜哪个文件出了问题。打开 Jaeger，看看那条蜿蜒曲折的路径；打开 Grafana，看看那个刺破天际的指标尖峰。
数据不会撒谎，而 OpenTelemetry 会告诉你真相。
现在，去给你的 PHP 项目装上这双“透视眼”吧。这不仅是为了监控，更是为了当你能看清一切的时候，那种掌控全局的快感。祝你的服务永远在线，QPS 永远爆表！
（全场掌声……如果有的话）