动态与公告

产品动态

产品简介

产品概述

产品优势

基本功能

基本概念

应用场景

使用限制

购买指南

云产品监控

应用性能监控

终端性能监控

前端性能监控

云拨测

Prometheus 监控服务

Grafana 服务

事件总线

云压测

快速入门

监控概览

实例分组

云产品监控

应用性能监控

云拨测

云压测

Prometheus 监控服务

Grafana 服务

创建 Dashboard

事件总线

告警服务

云产品监控

云产品监控指标

控制台操作指南

云服务器监控组件

云产品监控对接 Grafana

故障处理

实践教程

应用性能监控

应用性能监控简介

接入指南

控制台操作指南

实践教程

参考信息

常见问题

终端性能监控

终端性能监控概述

控制台操作指南

接入指南

实践教程

前端性能监控

前端性能监控简介

控制台操作指南

接入指南

常见问题

云拨测

产品简介

控制台操作指南

常见问题

云压测

云压测概述

控制台操作指南

实践教程

JavaScript API 列表

常见问题

Prometheus 监控

Prometheus 监控简介

接入指南

控制台操作指南

实践教程

Terraform

常见问题

Grafana 服务

产品简介

控制台操作指南

Grafana 平台常用功能指引

常见问题

Dashboard

什么是 Dashboard

控制台操作指南

告警管理

控制台操作指南

故障处理

常见问题

事件总线

事件总线简介

控制台操作指南

实践教程

常见问题

报表管理

常见问题

腾讯云可观测平台常见问题

告警服务相关

一般性问题

监控图表相关

云服务器监控组件相关

动态阈值告警相关

云监控对接 Grafana 相关

文档阅读指南

通过 OpenTelemetry-PHP 接入 PHP 应用（推荐）

PDF

聚焦模式

字号

最后更新时间： 2025-10-13 19:10:50

说明：
OpenTelemetry 是工具、API 和 SDK 的集合，用来检测、生成、收集和导出遥测数据（指标、日志和跟踪），帮助用户分析软件的性能和行为。关于 OpenTelemetry 的更多信息请参考 OpenTelemetry 官方网站。
OpenTelemetry 社区活跃，技术更迭迅速，广泛兼容主流编程语言、组件与框架，为云原生微服务以及容器架构的链路追踪能力广受欢迎。
﻿本文将通过相关操作介绍如何通过社区的 OpenTelemetry-PHP 方案接入 PHP 应用。
OpenTelemetry-PHP 方案对于 PHP 系的常用依赖库和框架，例如 Slim 等，提供了自动埋点，在不需要修改代码的情况下就能实现链路信息的上报。其他支持自动埋点的依赖库和框架请参考 OpenTelemetry 社区提供的 完整列表。
前提条件
安装如下工具：
﻿PECL﻿
﻿composer﻿
并确保 shell 中可以运行以下命令：
php -v
composer -v
自动接入
PHP 8.0+
目前自动埋点支持的框架列表详情请参见 OpenTelemetry 官方文档。
手动接入
PHP 7.4+
Demo 应用
示例代码 index.php 是一个 HTTP Server 使用 PDO 连接 MySQL 数据库操作，对应的 MySQL 服务请自行搭建，或直接购买云产品。
1. 初始化应用。
mkdir <project-name> && cd <project-name>
﻿
composer init \\
 --no-interaction \\
 --stability beta \\
 --require slim/slim:"^4" \\
 --require slim/psr7:"^1"
composer update
2. 编写业务代码。
在<project-name>目录下创建一个index.php文件，添加如下内容。
以下内容将使用一个 HTTP Server 接口模拟使用 PDO 连接 MySQL 进行一次搜索操作。
<?php
use Psr\\Http\\Message\\ResponseInterface as Response;
use Psr\\Http\\Message\\ServerRequestInterface as Request;
use Slim\\Factory\\AppFactory;
﻿
require __DIR__ . '/vendor/autoload.php';
﻿
$app = AppFactory::create();
﻿
$app->get('/getID', function (Request $request, Response $response) {
﻿
    $dbms = 'mysql';         // 数据库类型
    $host = 'localhost';     // 数据库主机名
    $dbName = 'Mydb';        // 使用的数据库
    $user = 'root';          // 数据库连接用户名
    $pass = '';              // 对应的密码
    $dsn = "$dbms:host=$host;dbname=$dbName";
﻿
    try {
        $dbh = new PDO($dsn, $user, $pass); // 初始化一个PDO对象
        echo "连接成功<br/>";
﻿
        foreach ($dbh->query('SELECT id from userInfo') as $row) {
            $response->getBody()->write($row[0] . "<br/>");
        }
﻿
        $dbh = null;
    } catch (PDOException $e) {
        die ("Error!: " . $e->getMessage() . "<br/>");
    }
﻿
    return $response;
});
﻿
$app->run();
获取接入点和 Token
1. 登录 腾讯云可观测平台 控制台。
2. 在左侧菜单栏中选择应用性能监控，单击应用列表 > 接入应用。
3. 在右侧弹出的接入应用抽屉框中，单击 PHP 语言。
4. 在接入 PHP 应用页面，选择您所要接入的地域以及业务系统。
5. 选择接入协议类型为 OpenTelemetry。
6. 上报方式选择您所想要的上报方式，获取您的接入点和 Token。
说明：
内网上报：使用此上报方式，您的服务需运行在腾讯云 VPC。通过 VPC 直接连通，在避免外网通信的安全风险同时，可以节省上报流量开销。
外网上报：当您的服务部署在本地或非腾讯云 VPC 内，可以通过此方式上报数据。请注意外网通信存在安全风险，同时也会造成一定上报流量费用。
自动接入方案 （推荐）
步骤1：构建 OpenTelemetry PHP Extension
说明：
如果已经构建过 OpenTelemetry PHP extension，可跳过当前步骤。
1. 下载构建 OpenTelemetry PHP extension 所需要的工具。
macOS
brew install gcc make autoconf
Linux（apt）
sudo apt-get install gcc make autoconf
2. 使用 PECL 构建 OpenTelemetry PHP 扩展。
pecl install opentelemetry
注意：
构建成功时输出内容的最后几行如下（路径可能不完全一致）。
Build process completed successfully
Installing '/opt/homebrew/Cellar/php/8.2.8/pecl/2020829/opentelemetry.so'
install ok: channel://pecl.php.net/opentelemetry-1.0.3
Extension opentelemetry enabled in php.ini
3. 启用 OpenTelemetry PHP 扩展。
说明：
如果上一步输出了Extension opentelemetry enabled in php.ini，表明已经启用，请跳过当前步骤。
在php.ini文件中添加如下内容。
[opentelemetry]
extension=opentelemetry.so
php.ini文件可能存在的位置。
OS
PATH
Linux	
/etc/php.ini
/usr/bin/php5/bin/php.ini
/etc/php/php.ini
/etc/php5/apache2/php.ini
Mac OSX
/private/etc/php.ini
Windows (with XAMPP installed)
C:/xampp/php/php.ini
4. 验证是否构建并启用成功。
方法一：
php -m | grep opentelemetry
预期输出：
opentelemetry
方法二：
php --ri opentelemetry
预期输出：
opentelemetry
opentelemetry support => enabled
extension version => 1.0.3
5. 为应用添加 OpenTelemetry PHP 自动埋点需要的额外依赖。
pecl install grpc # 这一步构建时间较长
﻿
composer config allow-plugins.php-http/discovery false
composer require \\
  open-telemetry/sdk \\
  open-telemetry/exporter-otlp \\
  open-telemetry/transport-grpc \\
  php-http/guzzle7-adapter \\
  open-telemetry/opentelemetry-auto-slim \\
  open-telemetry/opentelemetry-auto-pdo
open-telemetry/sdk：OpenTelemetry PHP SDK。
open-telemetry/exporter-otlp：OpenTelemetry PHP OTLP 协议数据上报所需的依赖。
open-telemetry/opentelemetry-auto-slim：OpenTelemetry PHP 针对 Slim 框架实现的自动埋点包。
open-telemetry/opentelemetry-auto-pdo：OpenTelemetry PHP 针对 PHP DataObject 实现的自动埋点包。
说明：
这里导入 open-telemetry/opentelemetry-auto-slim 和 open-telemetry/opentelemetry-auto-pdo 包是因为示例 demo 中使用了 PDO 和 Slim 框架，可以根据具体业务进行调整。如果业务中组件需要 OpenTelemetry 自动埋点，需要在项目中导入对应的自动埋点包，自动埋点包导入方式具体详情请参见 OpenTelemetry 官方文档。
步骤2：运行应用
1. 执行以下命令。
env OTEL_PHP_AUTOLOAD_ENABLED=true \\
 OTEL_TRACES_EXPORTER=otlp \\
 OTEL_METRICS_EXPORTER=none \\
 OTEL_LOGS_EXPORTER=none \\
 OTEL_EXPORTER_OTLP_PROTOCOL=grpc \\
 OTEL_EXPORTER_OTLP_ENDPOINT=<endpoint> \\ # 此处替换成步骤1中获得的接入点
 OTEL_RESOURCE_ATTRIBUTES="service.name=<service-name>,token=<token>" \\ # 此处<service-name>改为自定义服务名，<token>替换成步骤1中获得的token
 OTEL_PROPAGATORS=baggage,tracecontext \\
 php -S localhost:8080
说明：
上面指令启动 PHP 应用使用的是原生的 PHP 指令。
如果使用其他方式启动 PHP 应用，请确保环境变量注入成功。
2. 在浏览器中访问以下链接。
http://localhost:8080/getID
 每次进入该页面，OpenTelemetry 都会自动创建 Trace，并将链路数据上报至 APM。
接入验证
启动 PHP 应用后，通过8080端口访问对应的接口，例如 https://localhost:8080/getID。在有正常流量的情况下，应用性能监控 > 应用列表 中将展示接入的应用。单击应用名称/ID 进入应用详情页，再选择实例分析，即可看到接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待30秒左右。
自定义埋点（可选）
当自动埋点不满足您的场景或者需要增加业务层埋点时，您可参照下述内容，使用 OpenTelemetry PHP SDK 添加自定义埋点。本文仅展示最基本的自定义埋点方式，OpenTelemetry 社区提供了更多灵活的自定义埋点方式，具体使用方法可参考 OpenTelemetry 社区提供的 PHP 自定义埋点文档。
<?php
﻿
use OpenTelemetry\\API\\Globals; // 必须的包
﻿
require __DIR__ . '/vendor/autoload.php';
function wait(): void
{
    // 通过Globals包获取当前已经配置的providers
    $tracerProvider = Globals::tracerProvider();
    $tracer = $tracerProvider->getTracer(
        'instrumentation-scope-name', //name (required)
        'instrumentation-scope-version', //version
        'http://example.com/my-schema', //schema url
        ['foo' => 'bar'] //attributes
    );
    
    // 自定义埋点
    $span = $tracer->spanBuilder("wait")->startSpan();
    
    // 业务代码
    sleep(5)；
    
    // 自定义埋点结束
    $span->end();
}
﻿
wait();
自动接入常见问题
如果自动接入后，但是控制台上依然没有看到监控数据，请以下面流程排查。
排查网络问题
登录业务 Pod ，使用 telnet 工具测试与步骤1中获得的接入点网络的连通性。连接成功如下图所示：
﻿
若未成功，可尝试外网上报，或尝试解决网络连通问题。
排查版本问题
自动接入需要 PHP 8.0+。
排查埋点问题
自查环境变量
在 PHP 项目的启动目录输入以下命令，检查在 PHP 启动目录下各环境变量是否设置成功。
echo -e "\\nOTEL_PHP_AUTOLOAD_ENABLED=$OTEL_PHP_AUTOLOAD_ENABLED
OTEL_TRACES_EXPORTER=$OTEL_TRACES_EXPORTER
OTEL_METRICS_EXPORTER=$OTEL_METRICS_EXPORTER
OTEL_LOGS_EXPORTER=$OTEL_LOGS_EXPORTER
OTEL_EXPORTER_OTLP_PROTOCOL=$OTEL_EXPORTER_OTLP_PROTOCOL
OTEL_EXPORTER_OTLP_ENDPOINT=$OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_RESOURCE_ATTRIBUTES=$OTEL_RESOURCE_ATTRIBUTES
OTEL_PROPAGATORS=$OTEL_PROPAGATORS"
若未成功，请保证环境变量的成功设置。
自查埋点问题
若上面问题都检查无误，但依然没有数据上报到 APM 控制台。尝试把埋点信息打印到本地控制台，检查下探针埋点是否正常。
设置环境变量OTEL_TRACES_EXPORTER=console ，重启 PHP 项目，发送请求到该 PHP 服务。
该环境变量会将埋点的信息（如 TraceID、SpanID 等）打印到本地控制台。埋点成功下图所示：
﻿
若未成功，请检查项目中是否导入了需要埋点的库和框架的自动埋点包。
自查 PHP 依赖库和框架
目前自动埋点支持的框架列表详情请参见 OpenTelemetry 官方文档。
如果业务中组件需要 OpenTelemetry 自动埋点，需要在项目中导入对应的自动埋点包。具体操作如下图所示：
﻿
若以上问题都已解决，但依然在页面上没有看到数据，或业务中的组件不支持自动接入，请使用 手动接入方案。
手动接入方案
若 PHP 应用版本不能满足8.0+，但能满足7.4+，可以选择手动埋点上报。本文仅展示最基本的手动埋点方式，OpenTelemetry 社区提供了更多灵活的手动埋点方式，具体使用方法可参考 OpenTelemetry 社区提供的 PHP 手动接入文档。
导入 OpenTelemetry PHP SDK 以及 OpenTelemetry gRPC Explorer 所需依赖
1. 下载 PHP HTTP 客户端库，用于链路数据上报。
composer require guzzlehttp/guzzle
2. 下载 OpenTelemetry PHP SDK。
composer require \\
 open-telemetry/sdk \\
 open-telemetry/exporter-otlp
3. 下载使用 gRPC 上报数据时所需依赖。
pecl install grpc # 如果之前已经下载过grpc，可以跳过这一步
composer require open-telemetry/transport-grpc
编写 OpenTelemetry 初始化工具类
在index.php文件所在目录中创建opentelemetry_util.php文件。并在文件中添加如下代码。
<?php
// 包含设置应用名、Trace导出方式、Trace上报接入点，并创建全局TraceProvide
﻿
use OpenTelemetry\\API\\Globals;
use OpenTelemetry\\API\\Trace\\Propagation\\TraceContextPropagator;
use OpenTelemetry\\Contrib\\Otlp\\SpanExporter;
use OpenTelemetry\\SDK\\Common\\Attribute\\Attributes;
use OpenTelemetry\\SDK\\Common\\Export\\Stream\\StreamTransportFactory;
use OpenTelemetry\\SDK\\Resource\\ResourceInfo;
use OpenTelemetry\\SDK\\Resource\\ResourceInfoFactory;
use OpenTelemetry\\SDK\\Sdk;
use OpenTelemetry\\SDK\\Trace\\Sampler\\AlwaysOnSampler;
use OpenTelemetry\\SDK\\Trace\\Sampler\\ParentBased;
use OpenTelemetry\\SDK\\Trace\\SpanProcessor\\SimpleSpanProcessor;
use OpenTelemetry\\SDK\\Trace\\SpanProcessor\\BatchSpanProcessorBuilder;
use OpenTelemetry\\SDK\\Trace\\TracerProvider;
use OpenTelemetry\\SemConv\\ResourceAttributes;
use OpenTelemetry\\Contrib\\Grpc\\GrpcTransportFactory;
use OpenTelemetry\\Contrib\\Otlp\\OtlpUtil;
use OpenTelemetry\\API\\Signals;
﻿
// OpenTelemetry 初始化配置（需要在PHP应用初始化时就进行OpenTelemetry初始化配置）
function initOpenTelemetry()
{ 
  // 1. 设置 OpenTelemetry 资源信息
  $resource = ResourceInfoFactory::emptyResource()->merge(ResourceInfo::create(Attributes::create([
  ResourceAttributes::SERVICE_NAME => '<your-service-name>', // 应用名，必填，如php-opentelemetry-demo
  ResourceAttributes::HOST_NAME => '<your-host-name>' // 主机名，选填
  'token' => '<your-token>' // 替换成步骤1中获得的 Token
  ])));
  
  
  // 2. 创建将 Span 输出到控制台的 SpanExplorer
  // $spanExporter = new SpanExporter(
  // (new StreamTransportFactory())->create('php://stdout', 'application/json')
  // );
  
  // 2. 创建通过 gRPC 上报 Span 的 SpanExplorer
  $transport = (new GrpcTransportFactory())->create('<grpc-endpoint>' . OtlpUtil::method(Signals::TRACE)); # 替换成步骤1中获得的接入点信息
  $spanExporter = new SpanExporter($transport);
  
  
  // 3. 创建全局的 TraceProvider，用于创建 tracer
  $tracerProvider = TracerProvider::builder()
  ->addSpanProcessor(
  (new BatchSpanProcessorBuilder($spanExporter))->build()
  )
  ->setResource($resource)
  ->setSampler(new ParentBased(new AlwaysOnSampler()))
  ->build();
  
  Sdk::builder()
  ->setTracerProvider($tracerProvider)
  ->setPropagator(TraceContextPropagator::getInstance())
  ->setAutoShutdown(true) // PHP 程序退出后自动关闭 tracerProvider，保证链路数据都被上报
  ->buildAndRegisterGlobal(); // 将 tracerProvider 添加到全局
﻿
}
?>
修改应用代码，使用 OpenTelemetry API 创建 Span
1. 在index.php文件中导入所需包。
<?php
﻿
use OpenTelemetry\\API\\Globals;
use OpenTelemetry\\API\\Trace\\StatusCode;
use OpenTelemetry\\API\\Trace\\SpanKind;
use OpenTelemetry\\SDK\\Common\\Attribute\\Attributes;
use OpenTelemetry\\SDK\\Trace\\TracerProvider;
﻿
use Psr\\Http\\Message\\ResponseInterface as Response;
use Psr\\Http\\Message\\ServerRequestInterface as Request;
use Slim\\Factory\\AppFactory;
﻿
require __DIR__ . '/opentelemetry_util.php';
2. 调用initOpenTelemetry方法完成初始化，需要在 PHP 应用初始化时就进行 OpenTelemetry 初始化配置。
// OpenTelemetry 初始化，包含设置应用名、Trace导出方式、Trace上报接入点，并创建全局TraceProvider
initOpenTelemetry();
3. 在rolldice接口中创建 Span。
/**
 * 1. 接口功能：模拟扔骰子，返回一个1-6之间的随机正整数
 * 并演示如何创建Span、设置属性、事件、带有属性的事件
 */
$app->get('/rolldice', function (Request $request, Response $response) {
 // 获取 tracer
 $tracer = \\OpenTelemetry\\API\\Globals::tracerProvider()->getTracer('my-tracer');
 // 创建 Span; 设置span kind，不设置默认为KIND_INTERNAL
 $span = $tracer->spanBuilder("/rolldice")->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
 // 为 Span 设置属性
 $span->setAttribute("http.method", "GET");
 // 为 Span 设置事件
 $span->addEvent("Init");
 // 设置带有属性的事件
 $eventAttributes = Attributes::create([
 "key1" => "value",
 "key2" => 3.14159,
 ]);
﻿
 // 业务代码
 $result = random_int(1,6);
 $response->getBody()->write(strval($result));
﻿
 $span->addEvent("End");
 // 销毁 Span
 $span->end();
﻿
 return $response;
});
4. 创建嵌套 Span。
新建一个rolltwodices接口，模拟扔两个骰子，返回两个1 - 6之间的随机正整数。以下代码演示如何创建嵌套的 Span。
$app->get('/rolltwodices', function (Request $request, Response $response) {
 // 获取 tracer
 $tracer = \\OpenTelemetry\\API\\Globals::tracerProvider()->getTracer('my-tracer');
 // 创建 Span
 $parentSpan = $tracer->spanBuilder("/rolltwodices/parent")->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
 $scope = $parentSpan->activate();
﻿
 $value1 = random_int(1,6);
﻿
 $childSpan = $tracer->spanBuilder("/rolltwodices/parent/child")->startSpan();
 
 // 业务代码
 $value2 = random_int(1,6);
 $result = "dice1: " . $value1 . ", dice2: " . $value2; 
﻿
 // 销毁 Span
 $childSpan->end();
 $parentSpan->end();
 $scope->detach();
﻿
 $response->getBody()->write(strval($result));
 return $response;
});
5. 使用 Span 记录代码中发生的异常。
新建error接口，模拟接口发生异常。以下代码演示如何在代码发生异常时使用 Span 记录状态。
$app->get('/error', function (Request $request, Response $response) {
 // 获取 tracer
 $tracer = \\OpenTelemetry\\API\\Globals::tracerProvider()->getTracer('my-tracer');
 // 创建 Span
 $span3 = $tracer->spanBuilder("/error")->setSpanKind(SpanKind::KIND_SERVER)->startSpan();
 try {
 // 模拟代码发生异常
 throw new \\Exception('exception!');
 } catch (\\Throwable $t) {
 // 设置Span状态为error
 $span3->setStatus(\\OpenTelemetry\\API\\Trace\\StatusCode::STATUS_ERROR, "expcetion in span3!");
 // 记录异常栈轨迹
 $span3->recordException($t, ['exception.escaped' => true]);
 } finally {
 $span3->end();
 $response->getBody()->write("error");
 return $response;
 }
});
运行应用
1. 执行以下命令。
php -S localhost:8080
2. 在浏览器中访问以下链接。
http://localhost:8080/rolldice
http://localhost:8080/rolltwodices
http://localhost:8080/error
每次访问页面，OpenTelemetry 会创建链路数据，并将链路数据上报至 APM。
接入验证
启动 PHP 应用后，通过8080端口访问对应的接口，例如 https://localhost:8080/getID。在有正常流量的情况下，应用性能监控 > 应用列表 中将展示接入的应用，单击应用名称/ID 进入应用详情页。再选择实例分析，即可看到接入的应用实例。由于可观测数据的处理存在一定延时，如果接入后在控制台没有查询到应用或实例，请等待30秒左右。

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

tencent cloud

腾讯云可观测平台

通过 OpenTelemetry-PHP 接入 PHP 应用（推荐）

前提条件

自动接入

手动接入

Demo 应用

获取接入点和 Token

自动接入方案（推荐）

步骤1：构建 OpenTelemetry PHP Extension

步骤2：运行应用

接入验证

自定义埋点（可选）

自动接入常见问题

排查网络问题

排查版本问题

排查埋点问题

自查环境变量

自查埋点问题

自查 PHP 依赖库和框架

手动接入方案

导入 OpenTelemetry PHP SDK 以及 OpenTelemetry gRPC Explorer 所需依赖

编写 OpenTelemetry 初始化工具类

修改应用代码，使用 OpenTelemetry API 创建 Span

运行应用

接入验证

帮助和支持

OS	PATH
Linux	/etc/php.ini /usr/bin/php5/bin/php.ini /etc/php/php.ini /etc/php5/apache2/php.ini
Mac OSX	/private/etc/php.ini
Windows (with XAMPP installed)	C:/xampp/php/php.ini

tencent cloud

腾讯云可观测平台

通过 OpenTelemetry-PHP 接入 PHP 应用（推荐）

前提条件

自动接入

手动接入

Demo 应用

获取接入点和 Token

自动接入方案 （推荐）

步骤1：构建 OpenTelemetry PHP Extension

步骤2：运行应用

接入验证

自定义埋点（可选）

自动接入常见问题

排查网络问题

排查版本问题

排查埋点问题

自查环境变量

自查埋点问题

自查 PHP 依赖库和框架

手动接入方案

导入 OpenTelemetry PHP SDK 以及 OpenTelemetry gRPC Explorer 所需依赖

编写 OpenTelemetry 初始化工具类

修改应用代码，使用 OpenTelemetry API 创建 Span

运行应用

接入验证

帮助和支持

自动接入方案（推荐）