sentry-php-sdk

所有技能 > SDK 设置 > PHP SDK

Sentry PHP SDK

提供明确指导的向导，可扫描你的 PHP 项目，并引导你完成完整的 Sentry 设置。

在以下情况下调用此技能

• 用户要求在 PHP 应用中“添加 Sentry”或“设置 Sentry”
• 用户想在 PHP 中使用错误监控、追踪、性能分析、日志记录、指标或定时任务
• 用户提到 sentry/sentry、sentry/sentry-laravel、sentry/sentry-symfony，或 Sentry 与任何 PHP 框架的组合
• 用户想监控 Laravel 路由、Symfony 控制器、队列、计划任务或纯 PHP 脚本

**注意：**以下 SDK 版本和 API 以撰写本文时的 Sentry 文档为准（sentry/sentry 4.x、sentry/sentry-laravel 4.x、sentry/sentry-symfony 5.x）。 实施前，请务必对照 docs.sentry.io/platforms/php/ 进行确认。

---

阶段 1：检测

在提出建议前，运行以下命令了解项目：

# Check existing Sentry
grep -i sentry composer.json composer.lock 2>/dev/null

# Detect framework
cat composer.json | grep -E '"laravel/framework"|"symfony/framework-bundle"|"illuminate/'

# Confirm framework via filesystem markers
ls artisan 2>/dev/null && echo "Laravel detected"
ls bin/console 2>/dev/null && echo "Symfony detected"

# Detect queue systems
grep -E '"laravel/horizon"|"symfony/messenger"' composer.json 2>/dev/null

# Detect AI libraries
grep -E '"(laravel/ai|openai-php|openai/|anthropic|llm)' composer.json 2>/dev/null

# Check for companion frontend
ls frontend/ resources/js/ assets/ 2>/dev/null
cat package.json 2>/dev/null | grep -E '"react"|"svelte"|"vue"|"next"'

需要留意的内容：

• composer.json 中是否已有 sentry/sentry（或 -laravel / -symfony）？如果有，请检查是否存在初始化调用——可能只需要配置功能。
• 检测到哪个框架？Laravel（存在 artisan，且 composer.json 中包含 laravel/framework）、Symfony（存在 bin/console，且包含 symfony/framework-bundle），还是纯 PHP。
• 队列系统？（Laravel Queue / Horizon、Symfony Messenger 需要配置队列工作进程。）
• AI 库？（启用追踪后，sentry/sentry-laravel >= 4.27.0 会自动对 laravel/ai 进行插桩；其他 PHP AI 库需要手动创建 span。）
• 是否有配套的前端？（触发阶段 4 的交叉链接。）

---

阶段 2：推荐

根据检测结果，提出具体方案。不要提出开放式问题——直接给出建议：

始终推荐（核心覆盖）：

• ✅ 错误监控 — 捕获未处理的异常和 PHP 错误
• ✅ 日志记录 — Monolog 集成（Laravel/Symfony 会自动配置；纯 PHP 使用 MonologHandler）

检测到以下情况时推荐：

• ✅ 追踪 — 检测到 Web 框架（Laravel/Symfony 会自动对 HTTP、DB、Twig/Blade、缓存进行插桩）
• ⚡ 性能分析 — 适用于重视性能的生产应用（需要 excimer PHP 扩展，仅限 Linux/macOS）
• ⚡ 定时任务 — 检测到调度器模式（Laravel Scheduler、Symfony Scheduler、自定义 cron 任务）
• ⚡ 指标 — 用于业务 KPI 或 SLO 跟踪（使用 TraceMetrics API）
• ✅ AI 监控 — 在 Laravel 应用中检测到 laravel/ai（sentry/sentry-laravel >= 4.27.0 会自动进行插桩）

推荐矩阵：

功能	推荐条件	参考
错误监控	始终 — 不可或缺的基线配置	${SKILL_ROOT}/references/error-monitoring.md
追踪	检测到 Laravel/Symfony，或需要手动创建 span	${SKILL_ROOT}/references/tracing.md
性能分析	生产环境 + 可用的 excimer 扩展	${SKILL_ROOT}/references/profiling.md
日志记录	始终；Laravel/Symfony 使用 Monolog	${SKILL_ROOT}/references/logging.md
指标	需要跟踪业务事件或 SLO	${SKILL_ROOT}/references/metrics.md
定时任务	检测到调度器或 cron 模式	${SKILL_ROOT}/references/crons.md
AI 监控	在 Laravel 应用中检测到 laravel/ai，或需要手动创建 PHP AI span	${SKILL_ROOT}/references/ai-monitoring.md

建议：“我推荐错误监控 + 追踪 [+ 日志记录]。还需要性能分析、定时任务、指标或 AI 监控吗？”

---

阶段 3：引导

安装

# Plain PHP
composer require sentry/sentry "^4.0"

# Laravel
composer require sentry/sentry-laravel "^4.0"

# Laravel with Laravel AI monitoring
composer require sentry/sentry-laravel "^4.27.0"

# Symfony
composer require sentry/sentry-symfony "^5.0"

系统要求：

• PHP 7.2 或更高版本
• 扩展：ext-json、ext-mbstring、ext-curl（均为必需）
• excimer PECL 扩展（仅限 Linux/macOS——性能分析所必需）

框架专属初始化

纯 PHP

将 \Sentry\init() 放在入口文件（index.php、bootstrap.php 或同类文件）的顶部，在任何应用代码之前：

<?php

require_once 'vendor/autoload.php';

\Sentry\init([
    'dsn'                  => $_SERVER['SENTRY_DSN'] ?? '',
    'environment'          => $_SERVER['SENTRY_ENVIRONMENT'] ?? 'production',
    'release'              => $_SERVER['SENTRY_RELEASE'] ?? null,
    'send_default_pii'     => true,
    'traces_sample_rate'   => 1.0,
    'profiles_sample_rate' => 1.0,
    'enable_logs'          => true,
]);

// rest of application...

Laravel

步骤 1 — 在 bootstrap/app.php 中注册异常处理器：

use Sentry\Laravel\Integration;

return Application::configure(basePath: dirname(__DIR__))
    ->withExceptions(function (Exceptions $exceptions) {
        Integration::handles($exceptions);
    })->create();

步骤 2 — 发布配置并设置 DSN：

php artisan sentry:publish --dsn=YOUR_DSN

这会创建 config/sentry.php，并将 SENTRY_LARAVEL_DSN 添加到 .env。

步骤 3 — 配置 .env：

SENTRY_LARAVEL_DSN=https://[email protected]/0
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_PROFILES_SAMPLE_RATE=1.0

如需了解 Laravel 的完整配置选项，请阅读 ${SKILL_ROOT}/references/laravel.md。

Symfony

步骤 1 — 在 config/bundles.php 中注册 bundle（Symfony Flex 会自动完成）：

Sentry\SentryBundle\SentryBundle::class => ['all' => true],

步骤 2 — 创建 config/packages/sentry.yaml：

sentry:
    dsn: '%env(SENTRY_DSN)%'
    options:
        environment: '%env(APP_ENV)%'
        release: '%env(SENTRY_RELEASE)%'
        send_default_pii: true
        traces_sample_rate: 1.0
        profiles_sample_rate: 1.0
        enable_logs: true

步骤 3 — 在 .env 中设置 DSN：

SENTRY_DSN=https://[email protected]/0

如需了解 Symfony 的完整配置选项，请阅读 ${SKILL_ROOT}/references/symfony.md。

快速开始 — 推荐的初始化方式（纯 PHP）

启用大多数功能并采用合理默认值的完整初始化：

\Sentry\init([
    'dsn'                     => $_SERVER['SENTRY_DSN'] ?? '',
    'environment'             => $_SERVER['SENTRY_ENVIRONMENT'] ?? 'production',
    'release'                 => $_SERVER['SENTRY_RELEASE'] ?? null,
    'send_default_pii'        => true,

    // Tracing (lower to 0.1–0.2 in high-traffic production)
    'traces_sample_rate'      => 1.0,

    // Profiling — requires excimer extension (Linux/macOS only)
    'profiles_sample_rate'    => 1.0,

    // Structured logs (sentry/sentry >=4.12.0)
    'enable_logs'             => true,
]);

对每项已商定的功能

逐项处理功能。加载参考文档，按照步骤操作，并在继续之前进行验证：

功能	参考文件	在以下情况下加载……
错误监控	${SKILL_ROOT}/references/error-monitoring.md	始终（基线）
链路追踪	${SKILL_ROOT}/references/tracing.md	HTTP 处理器 / 分布式链路追踪
性能分析	${SKILL_ROOT}/references/profiling.md	对性能敏感的生产环境
日志记录	${SKILL_ROOT}/references/logging.md	始终；Laravel/Symfony 使用 Monolog
指标	${SKILL_ROOT}/references/metrics.md	业务 KPI / SLO 跟踪
定时任务	${SKILL_ROOT}/references/crons.md	检测到调度器 / cron 模式
AI 监控	${SKILL_ROOT}/references/ai-monitoring.md	在 Laravel 中检测到 laravel/ai，或需要手动 PHP AI span

对于每项功能：Read ${SKILL_ROOT}/references/<feature>.md，严格按照步骤操作，并验证其正常工作。

---

配置参考

\Sentry\init() 关键选项（纯 PHP）

选项	类型	默认值	用途
dsn	string|bool|null	$_SERVER['SENTRY_DSN']	值为空或为 false 时禁用 SDK
environment	string|null	$_SERVER['SENTRY_ENVIRONMENT']	例如，"staging"
release	string|null	$_SERVER['SENTRY_RELEASE']	例如，"[email protected]"
send_default_pii	bool	false	包含请求标头、Cookie 和 IP
sample_rate	float	1.0	错误事件采样率（0.0–1.0）
traces_sample_rate	float|null	null	事务采样率；null 表示禁用追踪
traces_sampler	callable|null	null	自定义逐事务采样（覆盖采样率）
profiles_sample_rate	float|null	null	相对于追踪的分析采样率；需要 excimer
enable_logs	bool	false	将结构化日志发送到 Sentry（>=4.12.0）
max_breadcrumbs	int	100	每个事件的面包屑上限
attach_stacktrace	bool	false	在 captureMessage() 中附加堆栈跟踪
in_app_include	string[]	[]	属于应用的路径前缀
in_app_exclude	string[]	[]	第三方代码的路径前缀（在追踪中隐藏）
ignore_exceptions	string[]	[]	永不报告的异常 FQCN
ignore_transactions	string[]	[]	永不报告的事务名称
error_types	int|null	error_reporting()	PHP 错误位掩码（例如，E_ALL & ~E_NOTICE）
capture_silenced_errors	bool	false	捕获被 @ 运算符抑制的错误
max_request_body_size	string	"medium"	"none" / "small" / "medium" / "always"
before_send	callable	identity	fn(Event $event, ?EventHint $hint): ?Event — 返回 null 以丢弃
before_breadcrumb	callable	identity	fn(Breadcrumb $b): ?Breadcrumb — 返回 null 以丢弃
trace_propagation_targets	string[]|null	null	要注入 sentry-trace 标头的下游主机；null = 全部，[] = 无
strict_trace_continuation	bool	false	仅当 sentry-org_id baggage 与 SDK 的组织 ID 匹配时，才继续传入的分布式追踪；可防止第三方 Sentry 插桩服务污染追踪（>=4.21.0）
debug	bool	false	SDK 详细输出（如需结构化输出，请改用 PSR-3 logger 选项）

环境变量

变量	映射到	备注
SENTRY_DSN	dsn	也读取 $_SERVER['SENTRY_DSN']
SENTRY_ENVIRONMENT	environment
SENTRY_RELEASE	release	也读取 $_SERVER['AWS_LAMBDA_FUNCTION_VERSION']
SENTRY_SPOTLIGHT	spotlight

Laravel 说明： 使用 SENTRY_LARAVEL_DSN（若未设置则回退到 SENTRY_DSN）。其他选项遵循 SENTRY_TRACES_SAMPLE_RATE、SENTRY_PROFILES_SAMPLE_RATE 等命名方式。

---

验证

测试 Sentry 是否正在接收事件：

// Trigger a real error event — check the Sentry dashboard within seconds
throw new \Exception('Sentry PHP SDK test');

或者进行不会导致程序崩溃的检查：

\Sentry\captureMessage('Sentry PHP SDK test');

Laravel：

php artisan sentry:test

如果没有任何内容显示：

1. 启用调试输出：

   \Sentry\init([
       'dsn' => '...',
       'logger' => new \Sentry\Logger\DebugStdOutLogger(),
   ]);
   

2. 验证 DSN 是否正确（格式：https://<key>@o<org>.ingest.sentry.io/<project>）
3. 检查运行中的进程是否设置了 SENTRY_DSN（或 SENTRY_LARAVEL_DSN）环境变量
4. 对于队列工作进程：确保在工作进程内部初始化 Sentry，而不只是 Web 进程

---

第 4 阶段：交叉链接

完成 PHP 设置后，检查是否存在缺少 Sentry 的配套前端：

ls frontend/ resources/js/ assets/ public/ 2>/dev/null
cat package.json frontend/package.json 2>/dev/null \
  | grep -E '"react"|"svelte"|"vue"|"next"|"nuxt"'

如果检测到的前端未配置 Sentry，请推荐相应的技能：

检测到的前端	推荐技能
React / Next.js	sentry-react-sdk
Svelte / SvelteKit	sentry-svelte-sdk
Vue / Nuxt	使用 @sentry/vue — 参见 docs.sentry.io/platforms/javascript/guides/vue/
其他 JS/TS	sentry-react-sdk（涵盖通用浏览器 JS 模式）

---

故障排查

问题	解决方案
未显示事件	启用 logger 选项（DebugStdOutLogger），验证 DSN，并检查运行进程中的环境变量
DSN 格式错误	格式：https://<key>@o<org>.ingest.sentry.io/<project>
未捕获 Laravel 异常	确保 Integration::handles($exceptions) 位于 bootstrap/app.php 中
未捕获 Symfony 异常	验证 SentryBundle 已在 config/bundles.php 中注册
未显示追踪	设置 traces_sample_rate（不能为 null）；确认已启用自动插桩
性能分析无法运行	需要 excimer 扩展（仅限 Linux/macOS；Windows 上不可用）；要求 traces_sample_rate > 0
enable_logs 无法运行	需要 sentry/sentry >= 4.12.0、sentry/sentry-laravel >= 4.15.0 或 sentry/sentry-symfony >= 5.4.0
缺少队列工作进程错误	在工作进程本身中初始化 Sentry，而不仅仅是在 Web 进程中；对于 Laravel，在工作进程的 .env 中使用 SENTRY_LARAVEL_DSN
事务过多	降低 traces_sample_rate，或使用 traces_sampler 丢弃健康检查路由
未捕获个人身份信息	设置 send_default_pii: true；对于 Laravel，在 config/sentry.php 中设置 send_default_pii: true
缺少被 @ 抑制的错误	设置 capture_silenced_errors: true
跨服务追踪中断	检查 trace_propagation_targets；确保下游服务已安装 Sentry
第三方服务导致追踪污染	设置 strict_trace_continuation: true，仅在传入的 sentry-org_id 行李数据与 SDK 的组织 ID 匹配时继续追踪（>=4.21.0）