sentry-php-sdk

すべてのスキル > SDK のセットアップ > PHP SDK

Sentry PHP SDK

PHP プロジェクトをスキャンし、Sentry の完全なセットアップを案内する、独自の見解を取り入れたウィザードです。

このスキルを使う場面

• ユーザーが PHP アプリへの「Sentry の追加」や「Sentry のセットアップ」を依頼した場合
• ユーザーが PHP でのエラー監視、トレーシング、プロファイリング、ロギング、メトリクス、または cron を希望している場合
• ユーザーが 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 ライブラリでは手動スパンが必要です。）
• フロントエンドも併用していますか？（フェーズ 4 の相互リンクが必要になります。）

---

フェーズ 2：推奨事項の提示

確認した内容に基づき、具体的な提案を提示してください。自由回答形式の質問はせず、推奨事項を示してください。

常に推奨（基本的なカバレッジ）：

• ✅ エラー監視 — 未処理の例外と PHP エラーをキャプチャします
• ✅ ロギング — Monolog との統合（Laravel／Symfony では自動設定され、通常の PHP では MonologHandler を使用します）

検出された場合に推奨：

• ✅ トレーシング — Web フレームワークが検出された場合（Laravel／Symfony では HTTP、DB、Twig／Blade、キャッシュを自動計装します）
• ⚡ プロファイリング — パフォーマンスが重要な本番アプリ（excimer PHP 拡張機能が必要です。Linux／macOS のみ）
• ⚡ cron — スケジューラーのパターンが検出された場合（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 が検出された場合、または手動スパンが必要な場合	${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	スケジューラーまたは cron のパターンが検出された場合	${SKILL_ROOT}/references/crons.md
AI 監視	Laravel アプリで laravel/ai が検出された場合、または PHP AI の手動スパンが必要な場合	${SKILL_ROOT}/references/ai-monitoring.md

次のように提案してください。「エラー監視とトレーシング［＋ロギング］をおすすめします。プロファイリング、cron、メトリクス、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

アプリケーションコードが実行される前に、エントリーポイント（index.php、bootstrap.php、または同等のファイル）の先頭に \Sentry\init() を配置してください。

<?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 が作成され、.env に SENTRY_LARAVEL_DSN が追加されます。

ステップ 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 内で設定します（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 の追跡
Cron	${SKILL_ROOT}/references/crons.md	スケジューラー／cron パターンが検出された場合
AI モニタリング	${SKILL_ROOT}/references/ai-monitoring.md	Laravel で laravel/ai が検出された場合、または PHP の AI スパンを手動で設定する必要がある場合

各機能について、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 の org 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 が必要です
キューワーカーのエラーが見つからない	Web プロセスだけでなく、ワーカープロセス自体で Sentry を初期化します。Laravel の場合は、ワーカーの .env で SENTRY_LARAVEL_DSN を使用します
トランザクションが多すぎる	traces_sample_rate を下げるか、traces_sampler を使用してヘルスチェックのルートを除外します
PII が記録されない	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 baggage が SDK の組織 ID と一致する場合にのみトレースを継続します（>=4.21.0）