Sentry Php Sdk

All Skills > SDK Setup > PHP SDK

Sentry PHP SDK

Opinionated wizard that scans your PHP project and guides you through complete Sentry setup.

Invoke This Skill When

• User asks to "add Sentry to PHP" or "setup Sentry" in a PHP app
• User wants error monitoring, tracing, profiling, logging, metrics, or crons in PHP
• User mentions sentry/sentry, sentry/sentry-laravel, sentry/sentry-symfony, or Sentry + any PHP framework
• User wants to monitor Laravel routes, Symfony controllers, queues, scheduled tasks, or plain PHP scripts

Note: SDK versions and APIs below reflect Sentry docs at time of writing (sentry/sentry 4.x, sentry/sentry-laravel 4.x, sentry/sentry-symfony 5.x).

Always verify against docs.sentry.io/platforms/php/ before implementing.

---

Phase 1: Detect

Run these commands to understand the project before making recommendations:

# 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 '"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"'

What to note:

• Is sentry/sentry (or -laravel / -symfony) already in composer.json? If yes, check if the init call exists — may just need feature config.
• Framework detected? Laravel (has artisan + laravel/framework in composer.json), Symfony (has bin/console + symfony/framework-bundle), or plain PHP.
• Queue system? (Laravel Queue / Horizon, Symfony Messenger need queue worker configuration.)
• AI libraries? (No PHP AI auto-instrumentation yet — document manually if needed.)
• Companion frontend? (Triggers Phase 4 cross-link.)

---

Phase 2: Recommend

Based on what you found, present a concrete proposal. Don't ask open-ended questions — lead with a recommendation:

Always recommended (core coverage):

• ✅ Error Monitoring — captures unhandled exceptions and PHP errors
• ✅ Logging — Monolog integration (Laravel/Symfony auto-configure; plain PHP uses MonologHandler)

Recommend when detected:

• ✅ Tracing — web framework detected (Laravel/Symfony auto-instrument HTTP, DB, Twig/Blade, cache)
• ⚡ Profiling — production apps where performance matters (requires excimer PHP extension, Linux/macOS only)
• ⚡ Crons — scheduler patterns detected (Laravel Scheduler, Symfony Scheduler, custom cron jobs)
• ⚡ Metrics — business KPIs or SLO tracking (uses TraceMetrics API)

Recommendation matrix:

Propose: "I recommend Error Monitoring + Tracing [+ Logging]. Want Profiling, Crons, or Metrics too?"

---

Phase 3: Guide

Install

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

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

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

System requirements:

• PHP 7.2 or later
• Extensions: ext-json, ext-mbstring, ext-curl (all required)
• excimer PECL extension (Linux/macOS only — required for profiling)

Framework-Specific Initialization

Plain PHP

Place \Sentry\init() at the top of your entry point (index.php, bootstrap.php, or equivalent), before any application code:

<?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

Step 1 — Register exception handler in bootstrap/app.php:

use Sentry\Laravel\Integration;

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

Step 2 — Publish config and set DSN:

php artisan sentry:publish --dsn=YOUR_DSN

This creates config/sentry.php and adds SENTRY_LARAVEL_DSN to .env.

Step 3 — Configure `.env`:

SENTRY_LARAVEL_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_PROFILES_SAMPLE_RATE=1.0

For full Laravel configuration options, read ${SKILL_ROOT}/references/laravel.md.

Symfony

Step 1 — Register the bundle in config/bundles.php (auto-done by Symfony Flex):

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

Step 2 — Create `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

Step 3 — Set the DSN in `.env`:

SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0

For full Symfony configuration options, read ${SKILL_ROOT}/references/symfony.md.

Quick Start — Recommended Init (Plain PHP)

Full init enabling the most features with sensible defaults:

\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,
]);

For Each Agreed Feature

Walk through features one at a time. Load the reference, follow its steps, verify before moving on:

For each feature: Read ${SKILL_ROOT}/references/<feature>.md, follow steps exactly, verify it works.

---

Configuration Reference

Key \Sentry\init() Options (Plain PHP)

Environment Variables

Laravel note: Uses SENTRY_LARAVEL_DSN (falls back to SENTRY_DSN). Other options follow SENTRY_TRACES_SAMPLE_RATE, SENTRY_PROFILES_SAMPLE_RATE, etc.

---

Verification

Test that Sentry is receiving events:

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

Or for a non-crashing check:

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

Laravel:

php artisan sentry:test

If nothing appears: 1. Enable debug output:

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

2. Verify the DSN is correct (format: https://<key>@o<org>.ingest.sentry.io/<project>) 3. Check SENTRY_DSN (or SENTRY_LARAVEL_DSN) env var is set in the running process 4. For queue workers: ensure Sentry is initialized inside the worker process, not just the web process

---

Phase 4: Cross-Link

After completing PHP setup, check for a companion frontend missing 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"'

If a frontend exists without Sentry, suggest the matching skill:

---

Troubleshooting

Crons — Sentry PHP SDK

Minimum SDK versions: sentry/sentry ≥ 3.16.0 · sentry/sentry-laravel ≥ 3.3.1

Overview

Sentry Crons monitors scheduled jobs by receiving check-ins at job start, success, and failure. Three approaches:

Code Examples

withMonitor() wrapper (simplest)

\Sentry\withMonitor(
    slug: 'my-cron-job',
    callback: fn() => doSomething(),
);
// Sends IN_PROGRESS before, OK on success, ERROR on exception

Manual check-ins with captureCheckIn()

use Sentry\CheckInStatus;

// 1. Signal job started
$checkInId = \Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::inProgress(),
);

try {
    // 2. Do work
    runScheduledTask();

    // 3a. Signal success
    \Sentry\captureCheckIn(
        slug: 'my-cron-job',
        status: CheckInStatus::ok(),
        checkInId: $checkInId,
    );
} catch (\Throwable $e) {
    // 3b. Signal failure
    \Sentry\captureCheckIn(
        slug: 'my-cron-job',
        status: CheckInStatus::error(),
        checkInId: $checkInId,
    );
    throw $e;
}

Heartbeat (single check-in)

Only notifies if the job didn't start when expected (missed). Does not detect max runtime exceeded.

// Success
\Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::ok(),
    duration: 10, // optional: seconds
);

// Failure
\Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::error(),
);

Upsert monitor config programmatically

Define monitor settings in code so Sentry creates/updates the monitor automatically on first check-in:

use Sentry\CheckInStatus;
use Sentry\MonitorConfig;
use Sentry\MonitorSchedule;
use Sentry\MonitorScheduleUnit;

// Crontab schedule
$monitorConfig = new MonitorConfig(
    MonitorSchedule::crontab('0 2 * * *'),  // every day at 2 AM
    checkinMargin: 5,                        // minutes late before MISSED alert
    maxRuntime: 15,                          // minutes before TIMEOUT alert
    timezone: 'Europe/Vienna',
    failureIssueThreshold: 2,               // consecutive failures before issue
    recoveryThreshold: 5,                   // consecutive successes to resolve
);

$checkInId = \Sentry\captureCheckIn(
    slug: 'daily-backup',
    status: CheckInStatus::inProgress(),
    monitorConfig: $monitorConfig,
);

runBackup();

\Sentry\captureCheckIn(
    slug: 'daily-backup',
    status: CheckInStatus::ok(),
    checkInId: $checkInId,
);

// Interval schedule
$monitorConfig = new MonitorConfig(
    MonitorSchedule::interval(10, MonitorScheduleUnit::minute()),
    checkinMargin: 5,
    maxRuntime: 8,
);

Laravel — sentryMonitor() macro

Add sentryMonitor() to any scheduled task in routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command(SendEmailsCommand::class)
    ->everyHour()
    ->sentryMonitor(); // that's it

With full configuration:

Schedule::command(SendEmailsCommand::class)
    ->everyHour()
    ->sentryMonitor(
        monitorSlug: null,              // auto-generated if null
        checkInMargin: 5,              // minutes before MISSED alert
        maxRuntime: 15,                // minutes before TIMEOUT alert
        failureIssueThreshold: 1,      // consecutive failures before issue
        recoveryThreshold: 1,          // consecutive successes to resolve
        updateMonitorConfig: true,     // set false to manage config in UI only
    );

Limitation: Tasks using between, unlessBetween, when, or skip are not supported. Use Laravel's cron() method for schedule frequency in those cases.

Symfony — same as base PHP SDK

The Symfony bundle has no dedicated cron integration. Use captureCheckIn() or withMonitor() directly:

use Sentry\CheckInStatus;

// In a Console command or service
$checkInId = \Sentry\captureCheckIn(
    slug: 'symfony-cron',
    status: CheckInStatus::inProgress(),
);

$this->doWork();

\Sentry\captureCheckIn(
    slug: 'symfony-cron',
    status: CheckInStatus::ok(),
    checkInId: $checkInId,
);

CheckInStatus Reference

use Sentry\CheckInStatus;

CheckInStatus::inProgress()  // job has started
CheckInStatus::ok()          // job completed successfully
CheckInStatus::error()       // job failed
// MISSED and TIMEOUT are generated server-side — not sent by SDK

MonitorScheduleUnit Reference

use Sentry\MonitorScheduleUnit;

MonitorScheduleUnit::minute()
MonitorScheduleUnit::hour()
MonitorScheduleUnit::day()
MonitorScheduleUnit::week()
MonitorScheduleUnit::month()
MonitorScheduleUnit::year()

MonitorConfig Parameters

Laravel sentryMonitor() Parameters

Rate Limits

6 check-ins per minute per monitor-environment. Excess check-ins are silently dropped.

Example:

• database-backup in production → up to 6/min
• database-backup in staging → up to 6/min (separate limit)

Verify dropped check-ins on the Sentry Usage Stats page.

Alerts Setup

When a job misses a check-in or reports failure, Sentry creates an error event tagged with monitor.slug:

1. Go to Alerts → Create Alert → select Issues under Errors 2. Filter: The event's tags match monitor.slug equals my-monitor-slug-here

Best Practices

• Use withMonitor() for simple jobs; use manual captureCheckIn() when you need error handling or heartbeats
• Provide MonitorConfig on the first check-in so Sentry creates the monitor automatically — no UI setup needed
• For jobs longer than maxRuntime, send periodic IN_PROGRESS check-ins as heartbeats to reset the timeout clock
• In Laravel, prefer sentryMonitor() macro over manual check-ins for scheduled tasks
• Set updateMonitorConfig: false in Laravel when the monitor schedule is managed in the Sentry UI

Troubleshooting

Error Monitoring — Sentry PHP SDK

Minimum SDK: sentry/sentry ^4.0 · sentry/sentry-laravel ^4.0 · sentry/sentry-symfony ^5.0

Configuration

Key \Sentry\init() options for error monitoring:

Code Examples

Basic setup

// Plain PHP
\Sentry\init([
    'dsn'              => 'https://<key>@<org>.ingest.sentry.io/<project>',
    'environment'      => 'production',
    'release'          => 'my-app@1.2.3',
    'sample_rate'      => 1.0,
    'send_default_pii' => false,
    'max_breadcrumbs'  => 100,
    'in_app_exclude'   => ['/var/www/html/vendor'],
]);

// Laravel — config/sentry.php (published by php artisan vendor:publish)
return [
    'dsn'         => env('SENTRY_LARAVEL_DSN', env('SENTRY_DSN')),
    'release'     => env('SENTRY_RELEASE'),
    'environment' => env('SENTRY_ENVIRONMENT'),   // defaults to APP_ENV
    'sample_rate' => (float) env('SENTRY_SAMPLE_RATE', 1.0),
    'send_default_pii' => env('SENTRY_SEND_DEFAULT_PII', false),
    'ignore_exceptions' => [],
];

# Symfony — config/packages/sentry.yaml
sentry:
    dsn: '%env(SENTRY_DSN)%'
    register_error_listener: true   # auto-captures on kernel.exception
    register_error_handler: true    # registers PHP error/exception handlers
    options:
        environment: '%kernel.environment%'
        release: '%env(default::SENTRY_RELEASE)%'
        sample_rate: 1.0
        send_default_pii: false
        max_breadcrumbs: 100
        in_app_exclude:
            - '%kernel.cache_dir%'
            - '%kernel.project_dir%/vendor'
        ignore_exceptions:
            - Symfony\Component\HttpKernel\Exception\NotFoundHttpException

Capture APIs

captureException()

// Signature: function captureException(\Throwable $exception, ?EventHint $hint = null): ?EventId

// Basic
try {
    riskyOperation();
} catch (\Throwable $e) {
    \Sentry\captureException($e);
}

// With extra data attached via hint
\Sentry\captureException($e, \Sentry\EventHint::fromArray([
    'extra' => ['sql' => $query, 'bindings' => $bindings],
]));

// Mark as unhandled (higher priority / inbox in Sentry UI)
\Sentry\captureException($e, \Sentry\EventHint::fromArray([
    'mechanism' => new \Sentry\ExceptionMechanism(
        \Sentry\ExceptionMechanism::TYPE_GENERIC,
        false  // $handled = false
    ),
]));

captureMessage()

// Signature: function captureMessage(string $message, ?Severity $level = null, ?EventHint $hint = null): ?EventId

\Sentry\captureMessage('Payment gateway timeout');
\Sentry\captureMessage('Low disk space', \Sentry\Severity::warning());
\Sentry\captureMessage('Critical failure', \Sentry\Severity::fatal());

// All Severity factory methods:
// Severity::debug()  Severity::info()  Severity::warning()
// Severity::error()  Severity::fatal()

captureEvent()

// Signature: function captureEvent(Event $event, ?EventHint $hint = null): ?EventId

$event = \Sentry\Event::createEvent();
$event->setMessage('Custom billing event');
$event->setLevel(\Sentry\Severity::info());
$event->setTags(['component' => 'payment', 'provider' => 'stripe']);
$event->setExtra(['order_id' => 42, 'retries' => 3]);
$event->setFingerprint(['{{ default }}', 'payment-module']);
$event->setTransaction('checkout.payment');

\Sentry\captureEvent($event);

captureLastError()

// Signature: function captureLastError(?EventHint $hint = null): ?EventId
// Reads the most recent error from error_get_last()

register_shutdown_function(function (): void {
    \Sentry\captureLastError();
    \Sentry\flush();   // required in CLI/shutdown contexts
});

// Note: installed automatically by FatalErrorListenerIntegration
// when default_integrations => true (the default).

Automatic capture by framework

// Plain PHP — default integrations auto-install PHP error handlers
\Sentry\init(['dsn' => '...']);
// ErrorListenerIntegration    → set_error_handler()
// ExceptionListenerIntegration → set_exception_handler()
// FatalErrorListenerIntegration → register_shutdown_function()

// Laravel 11+ (bootstrap/app.php)
use Sentry\Laravel\Integration;

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

// Laravel 10 and below (app/Exceptions/Handler.php)
public function register(): void
{
    $this->reportable(function (\Throwable $e) {
        \Sentry\Laravel\Integration::captureUnhandledException($e);
    });
}

// Symfony — register_error_listener: true in sentry.yaml (default)
// ErrorListener subscribes to kernel.exception and captures automatically

Scope management

Three scope types control where data persists:

// Persistent — modifies current scope, data appears on all subsequent events
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setTag('tenant', 'acme-corp');
    $scope->setUser(['id' => 42, 'email' => 'user@example.com']);
});

// Isolated — child scope discarded after callback; changes don't leak
\Sentry\withScope(function (\Sentry\State\Scope $scope): void {
    $scope->setTag('payment_flow', 'checkout');
    $scope->setExtra('cart_id', 'cart-123');
    \Sentry\captureException(new \RuntimeException('Payment failed'));
});
// ← tag and extra are gone after this line

// Long-running process isolation (prevents cross-request contamination)
$hub = \Sentry\SentrySdk::getCurrentHub();
$hub->pushScope();
try {
    \Sentry\configureScope(function (\Sentry\State\Scope $scope) use ($job): void {
        $scope->setTag('job.class', get_class($job));
    });
    $job->handle();
} finally {
    $hub->popScope();
}

// Manual push/pop (lower level)
$hub = \Sentry\SentrySdk::getCurrentHub();
$hub->pushScope();
try {
    // ... isolated work ...
} finally {
    $hub->popScope();
}

Context enrichment

Tags

Tags are indexed — searchable and filterable in the Sentry UI. Max key 32 chars, value 200 chars.

\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setTag('environment', 'production');
    $scope->setTags(['payment_provider' => 'stripe', 'checkout_version' => 'v3']);
    $scope->removeTag('debug_mode');
});

// Per-event only
\Sentry\withScope(function (\Sentry\State\Scope $scope): void {
    $scope->setTag('retry_attempt', '2');
    \Sentry\captureException(new \RuntimeException('Still failing'));
});

User context — UserDataBag

// Via array (Scope::setUser accepts array OR UserDataBag)
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setUser([
        'id'         => 42,
        'email'      => 'jane@example.com',
        'username'   => 'jane_doe',
        'ip_address' => '192.168.1.1',
        'plan'       => 'enterprise',   // extra keys become metadata
    ]);
});

// Via UserDataBag fluent API
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $user = \Sentry\UserDataBag::createFromUserIdentifier(42);
    $user->setEmail('jane@example.com');
    $user->setMetadata('plan', 'enterprise');
    $scope->setUser($user);
});

// Clear user (e.g., on logout)
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->removeUser();
});

Breadcrumbs — Breadcrumb constants

// Type constants (Breadcrumb::TYPE_*)
Breadcrumb::TYPE_DEFAULT    // 'default' — generic log entry
Breadcrumb::TYPE_HTTP       // 'http'    — outgoing HTTP request
Breadcrumb::TYPE_USER       // 'user'    — user interaction
Breadcrumb::TYPE_NAVIGATION // 'navigation' — URL/route change
Breadcrumb::TYPE_ERROR      // 'error'   — captured error

// Level constants (Breadcrumb::LEVEL_*)
Breadcrumb::LEVEL_DEBUG
Breadcrumb::LEVEL_INFO
Breadcrumb::LEVEL_WARNING
Breadcrumb::LEVEL_ERROR
Breadcrumb::LEVEL_FATAL

// Shorthand via global function (PHP 8 named args)
\Sentry\addBreadcrumb(
    category: 'auth',
    message:  'User authenticated',
    metadata: ['user_id' => 42, 'method' => 'oauth'],
    level:    \Sentry\Breadcrumb::LEVEL_INFO,
    type:     \Sentry\Breadcrumb::TYPE_DEFAULT,
);

// Explicit Breadcrumb object
\Sentry\addBreadcrumb(new \Sentry\Breadcrumb(
    \Sentry\Breadcrumb::LEVEL_INFO,
    \Sentry\Breadcrumb::TYPE_HTTP,
    'http.client',
    'POST https://api.stripe.com/v1/charges',
    ['status_code' => 200, 'duration_ms' => 243]
));

// Navigation crumb
\Sentry\addBreadcrumb(new \Sentry\Breadcrumb(
    \Sentry\Breadcrumb::LEVEL_INFO,
    \Sentry\Breadcrumb::TYPE_NAVIGATION,
    'navigation',
    null,
    ['from' => '/home', 'to' => '/checkout']
));

// Breadcrumb is immutable — modify via with*() methods (return clones)
$crumb = new \Sentry\Breadcrumb(
    \Sentry\Breadcrumb::LEVEL_INFO,
    \Sentry\Breadcrumb::TYPE_DEFAULT,
    'cache', 'Cache miss', ['key' => 'user:42:profile']
);
$crumb = $crumb->withLevel(\Sentry\Breadcrumb::LEVEL_WARNING)
               ->withMetadata('ttl', 300);
\Sentry\addBreadcrumb($crumb);

Structured named context

Named context blocks appear as collapsible panels in the Sentry event UI.

\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setContext('payment', [
        'provider' => 'stripe',
        'amount'   => 9900,
        'currency' => 'USD',
    ]);
});

// Per-event
\Sentry\withScope(function (\Sentry\State\Scope $scope) use ($exception): void {
    $scope->setContext('order', [
        'id'     => 'ord-999',
        'items'  => 3,
        'total'  => 59.99,
        'status' => 'pending',
    ]);
    \Sentry\captureException($exception);
});

// Reserved names with special UI rendering: os, runtime, app, browser, device, gpu, culture, trace

before_send hook — filtering and scrubbing

// Callback signature:
// callable(\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event
// Return null to DROP the event; return (modified) event to send.

\Sentry\init([
    'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
        // Drop health-check routes
        $request = $event->getRequest();
        if ($request?->getUrl() && str_contains($request->getUrl(), '/healthz')) {
            return null;
        }

        // Scrub sensitive extra data
        $extra = $event->getExtra();
        unset($extra['password'], $extra['credit_card']);
        $event->setExtra($extra);

        // Add tag based on exception type
        if ($hint?->exception instanceof \PDOException) {
            $event->setTag('db_error', 'true');
        }

        // Custom fingerprint based on message
        if ($hint?->exception && str_contains($hint->exception->getMessage(), 'timeout')) {
            $event->setFingerprint(['timeout', get_class($hint->exception)]);
        }

        return $event;
    },
]);

before_breadcrumb hook

// Callback signature:
// callable(\Sentry\Breadcrumb $breadcrumb): ?\Sentry\Breadcrumb
// Return null to DROP; return (modified) Breadcrumb to keep.

\Sentry\init([
    'before_breadcrumb' => function (\Sentry\Breadcrumb $breadcrumb): ?\Sentry\Breadcrumb {
        // Drop SQL queries containing sensitive data
        if ($breadcrumb->getCategory() === 'db.sql.query') {
            if (str_contains(strtolower($breadcrumb->getMessage() ?? ''), 'password')) {
                return null;
            }
        }

        // Redact API keys from URLs
        $metadata = $breadcrumb->getMetadata();
        if (isset($metadata['url']) && str_contains($metadata['url'], 'api_key=')) {
            return $breadcrumb->withMetadata(
                'url',
                preg_replace('/api_key=[^&]+/', 'api_key=[Filtered]', $metadata['url'])
            );
        }

        return $breadcrumb;
    },
]);

Additional hook variants

// Filter performance transactions (not error events)
'before_send_transaction' => function (\Sentry\Event $tx, ?\Sentry\EventHint $hint): ?\Sentry\Event {
    if (in_array($tx->getTransaction(), ['GET /up', 'GET /ping', 'GET /healthz'])) {
        return null;
    }
    return $tx;
},

// Filter cron monitor check-ins
'before_send_check_in' => function (\Sentry\Event $checkIn, ?\Sentry\EventHint $hint): ?\Sentry\Event {
    return $checkIn; // or null to drop
},

// NOTE: Symfony uses service IDs instead of closures:
// options: { before_send: 'App\Sentry\BeforeSendHandler' }

Error context — EventHint and ExceptionMechanism

// EventHint public properties:
// $exception  — original \Throwable
// $mechanism  — ExceptionMechanism (how it was caught)
// $stacktrace — custom Stacktrace override
// $extra      — array<string, mixed> passed to before_send but not in event body

// Handled vs unhandled — affects priority and inbox routing in Sentry
use Sentry\ExceptionMechanism;

$hint = \Sentry\EventHint::fromArray([
    'exception'  => $exception,
    'mechanism'  => new ExceptionMechanism(ExceptionMechanism::TYPE_GENERIC, false), // unhandled
]);
\Sentry\captureException($exception, $hint);

// Exception chaining — SDK auto-walks $e->getPrevious()
// All chained exceptions appear as exception.values[] in the event
try {
    try {
        $pdo->query($sql);           // throws PDOException
    } catch (\PDOException $dbEx) {
        throw new \DomainException('Payment failed', 0, $dbEx);
    }
} catch (\DomainException $e) {
    \Sentry\captureException($e);
    // Sentry event: exception.values[0] = DomainException
    //               exception.values[1] = PDOException ($previous)
}

// Pass data through hint to before_send without including it in the event body
$hint = \Sentry\EventHint::fromArray([
    'extra' => ['query' => $sql, 'duration_ms' => $ms],
]);
\Sentry\captureException($exception, $hint);

// Access in before_send
'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
    if ($hint !== null && ($hint->extra['duration_ms'] ?? 0) > 5000) {
        $event->setTag('slow_query', 'true');
    }
    return $event;
},

Fingerprinting (custom grouping)

Default fingerprint: ['{{ default }}'] — stack trace hash + exception type + message.

// Via scope — persistent
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setFingerprint(['payment-timeout', 'stripe-api']);
});

// Via withScope — per-event, combined with default
\Sentry\withScope(function (\Sentry\State\Scope $scope) use ($exception, $provider): void {
    $scope->setFingerprint(['{{ default }}', 'payment', $provider]);
    \Sentry\captureException($exception);
});

// Via before_send — dynamic
\Sentry\init([
    'before_send' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
        if ($hint?->exception instanceof \PDOException) {
            $msg = $hint->exception->getMessage();
            if (str_contains($msg, 'timed out')) {
                $event->setFingerprint(['db-timeout', 'pdo']);
            }
        }
        return $event;
    },
]);

// Via captureEvent — inline
$event = \Sentry\Event::createEvent();
$event->setFingerprint(['my-custom-group', '{{ default }}']);
$event->setMessage('Grouped event');
\Sentry\captureEvent($event);

// Scope fingerprints are APPENDED to any existing event fingerprints:
// array_merge($event->getFingerprint(), $scope->getFingerprint())

Framework-Specific Notes

Plain PHP

• default_integrations: true (default) auto-installs set_error_handler(), set_exception_handler(), and register_shutdown_function() — no manual handlers needed
• Always call \Sentry\flush() before process exit in CLI scripts
• In long-running workers (e.g., RoadRunner, Swoole), use pushScope()/popScope() per request to prevent cross-request scope contamination

Laravel

• Laravel 11+: use Integration::handles($exceptions) in bootstrap/app.php
• Laravel 10 and below: use Integration::captureUnhandledException($e) in Handler::register()
• Integration::captureUnhandledException() inspects the call stack to guess whether the exception was truly unhandled and sets the ExceptionMechanism::$handled flag accordingly
• Laravel auto-sets user context from Auth::user() on the Authenticated event (reads id, email, username)
• Octane: scope is automatically isolated per request via pushScope()/popScope() in the Octane event handlers — no manual action needed
• SENTRY_SEND_DEFAULT_PII=true is required to capture user email and IP
• Log levels map to breadcrumb levels: critical/alert/emergency → LEVEL_FATAL, warning → LEVEL_WARNING, error → LEVEL_ERROR, info/notice → LEVEL_INFO, debug → LEVEL_DEBUG

Symfony

• Errors are captured by ErrorListener on the kernel.exception event — controlled by register_error_listener: true (default)
• User context requires send_default_pii: true; populated by LoginListener on LoginSuccessEvent / AuthenticationSuccessEvent
• Inject HubInterface via DI rather than using global \Sentry\* functions in services
• before_send in Symfony must be a service ID, not a closure — closures cannot be serialized and break config caching:

// src/Sentry/BeforeSendHandler.php
namespace App\Sentry;

use Sentry\Event;
use Sentry\EventHint;

class BeforeSendHandler
{
    public function __invoke(Event $event, ?EventHint $hint): ?Event
    {
        // ... filter / scrub ...
        return $event;
    }
}

# config/packages/sentry.yaml
sentry:
    options:
        before_send: 'App\Sentry\BeforeSendHandler'

• MessengerListener captures exceptions from failed Messenger messages — inject it if using the Messenger component

Best Practices

• Set send_default_pii: false (default) — add explicit scrubbing in before_send for any sensitive fields
• Use configureScope() for per-request data (user identity) and withScope() for per-capture isolation
• Prefer setContext() for structured detail data; use setTag() only for fields you want to filter/search on
• Use ignore_exceptions: [...] for exceptions that should never be reported (e.g., NotFoundHttpException)
• In PHP-FPM (one process per request), global scope is safe. In long-running servers (Octane, RoadRunner), always isolate scope per request/task
• ignore_exceptions runs before before_send — matching classes are silently dropped and before_send is never called
• EventHint received in before_send is the same object passed to captureException() — use it to access the original Throwable and any extra context

Troubleshooting

Laravel — Sentry SDK Deep Dive

Package: sentry/sentry-laravel · Requires sentry/sentry ^4.21.0

Laravel versions: ^6.0 through ^12.0 (Lumen supported)

---

Installation & Setup

Requirements

• PHP ^7.2 | ^8.0
• Laravel ^6.0–^12.0
• zend.exception_ignore_args: Off in php.ini (required for stack trace arguments)

Install

composer require sentry/sentry-laravel

Auto-registration via Laravel Package Discovery — no manual config/app.php entry needed. Two service providers register automatically:

• Sentry\Laravel\ServiceProvider
• Sentry\Laravel\Tracing\ServiceProvider

Step 1 — Hook Exception Handler (Laravel 11+)

In bootstrap/app.php:

use Sentry\Laravel\Integration;

->withExceptions(function (Exceptions $exceptions) {
    Integration::handles($exceptions);
})

For Laravel 10 and earlier, add to app/Exceptions/Handler.php:

public function register(): void
{
    $this->reportable(function (\Throwable $e) {
        \Sentry\Laravel\Integration::captureUnhandledException($e);
    });
}

Step 2 — Publish Config & Set DSN

php artisan sentry:publish --dsn=___PUBLIC_DSN___

This creates config/sentry.php and writes SENTRY_LARAVEL_DSN=your_dsn to .env.

Step 3 — Verify

php artisan sentry:test

Or add a test route:

Route::get('/debug-sentry', function () {
    throw new Exception('My first Sentry error!');
});

---

Environment Variables

---

config/sentry.php — Complete Options

Root Options

Breadcrumb Options

All controlled per-feature in the breadcrumbs sub-array:

Tracing Options

---

Auto-Instrumented Operations

The Laravel SDK auto-instruments the following (via EventHandler + feature integrations):

Filesystem Disk Instrumentation (Opt-in)

// config/filesystems.php — wrap ALL disks
'disks' => Sentry\Laravel\Features\Storage\Integration::configureDisks([
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
    ],
    's3' => [
        'driver' => 's3',
        // ...
    ],
], /* enableSpans: */ true, /* enableBreadcrumbs: */ true),

// Or wrap a single disk
's3' => Sentry\Laravel\Features\Storage\Integration::configureDisk('s3', [
    // ... disk config ...
], /* enableSpans: */ true, /* enableBreadcrumbs: */ true),

---

Middleware

Three middleware are auto-registered — no manual setup needed:

The tracing middleware (Tracing\Middleware) is auto-prepended via $httpKernel->prependMiddleware() — it runs before all user middleware and records the full boot time.

FastCGI behavior: On FastCGI, the terminate phase runs after the response is sent to the client, so Sentry upload does not add user-visible latency. On non-FastCGI (built-in server, RoadRunner), the response is delayed by the Sentry upload — use a local Relay proxy in that case.

---

Log Channels

Laravel provides two separate Sentry log channel drivers:

sentry channel — Error Events/Breadcrumbs (classic)

Sends log messages as Sentry error events or breadcrumbs.

// config/logging.php
'channels' => [
    'sentry' => [
        'driver'  => 'sentry',
        'level'   => env('LOG_LEVEL', 'error'),
        'bubble'  => true,
    ],
],

sentry_logs channel — Structured Sentry Logs (≥ 4.15.0)

Sends structured logs to the Sentry Logs product (not as error events).

# .env
LOG_CHANNEL=stack
LOG_STACK=single,sentry_logs
SENTRY_ENABLE_LOGS=true
LOG_LEVEL=info
SENTRY_LOG_LEVEL=warning

// config/logging.php (required for SDK <= 4.16.0; auto-registered in > 4.16.0)
'sentry_logs' => [
    'driver' => 'sentry_logs',
    'level'  => env('LOG_LEVEL', 'info'),
],

// Usage
use Illuminate\Support\Facades\Log;

Log::info('User logged in', ['user_id' => $user->id]);
Log::warning('User {id} failed to login.', ['id' => $user->id]);
Log::error('Something went wrong', ['user_id' => auth()->id(), 'action' => 'update_profile']);

// Send only to Sentry (bypass other channels)
Log::channel('sentry_logs')->error('This goes only to Sentry');

Auto-flush: When enable_logs is true, the ServiceProvider registers a terminating callback that flushes pending logs automatically.

Troubleshooting Tinker: tinker doesn't trigger the normal request lifecycle — flush manually:

\Sentry\logger()->flush();

---

Queue Integration

The queue integration is the most complete in any framework. All of the following is automatic when traces_sample_rate is set:

Distributed Tracing Across Queue

Trace context is automatically injected into job payloads using these keys:

const QUEUE_PAYLOAD_BAGGAGE_DATA      = 'sentry_baggage_data';
const QUEUE_PAYLOAD_TRACE_PARENT_DATA = 'sentry_trace_parent_data';
const QUEUE_PAYLOAD_PUBLISH_TIME      = 'sentry_publish_time';

The worker side automatically reads these and calls continueTrace() — the queue job transaction is linked to the originating HTTP request transaction, giving you end-to-end distributed traces.

Transaction Attributes

Queue process transactions include OpenTelemetry-aligned attributes:

Config

// config/sentry.php
'tracing' => [
    'queue_job_transactions' => true,  // Full distributed transaction per job
    'queue_jobs'             => true,  // Child spans for jobs within a transaction
],
'breadcrumbs' => [
    'queue_info' => true,  // Job name/queue/attempts breadcrumbs
],

---

Cron Monitoring (Scheduled Tasks)

sentryMonitor() Macro

Add to scheduled tasks in routes/console.php (Laravel 9+) or app/Console/Kernel.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command(SendEmailsCommand::class)
    ->everyHour()
    ->sentryMonitor();

With full configuration:

Schedule::command(SendEmailsCommand::class)
    ->everyHour()
    ->sentryMonitor(
        monitorSlug: null,             // Auto-generated if null
        checkInMargin: 5,              // Minutes before check-in is considered missed
        maxRuntime: 15,                // Minutes before in-progress is marked timed out
        failureIssueThreshold: 1,      // Consecutive failures before creating issue
        recoveryThreshold: 1,          // Consecutive successes before resolving issue
        updateMonitorConfig: false,    // Set false to configure only in UI
    );

⚠️ Limitation: Tasks using between, unlessBetween, when, and skip methods are not supported. Use cron('...') for the schedule frequency instead.

Automatic Slug Generation

When no slug is provided:

• Commands: "scheduled_emails-send" (from command name)
• Jobs: "scheduled_send-email-job" (from reversed class name)

Automatic Transaction Tracing

ConsoleSchedulingIntegration also creates tracing transactions for scheduled tasks automatically (no additional config beyond traces_sample_rate):

• op: 'console.command.scheduled'
• source: TransactionSource::task()

---

Artisan Commands

---

User Context

\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setUser([
        'id'    => auth()->user()->id,
        'email' => auth()->user()->email,
    ]);
});

Requires 'send_default_pii' => true in config/sentry.php.

---

Closures and Config Caching

php artisan config:cache will fail if config/sentry.php contains PHP closures (e.g., inline before_send callbacks). Use a static class method callable instead:

// config/sentry.php — safe for config:cache
'before_send'         => [App\Sentry\Callbacks::class, 'beforeSend'],
'before_send_log'     => [App\Sentry\Callbacks::class, 'beforeSendLog'],
'before_send_metric'  => [App\Sentry\Callbacks::class, 'beforeSendMetric'],
'traces_sampler'      => [App\Sentry\Callbacks::class, 'tracesSampler'],

// app/Sentry/Callbacks.php
namespace App\Sentry;

use Sentry\Event;
use Sentry\EventHint;

class Callbacks
{
    public static function beforeSend(Event $event, ?EventHint $hint): ?Event
    {
        // return null to drop the event
        return $event;
    }

    public static function tracesSampler(\Sentry\Tracing\SamplingContext $context): float
    {
        return $context->getParentSampled() ? 1.0 : 0.25;
    }
}

---

Lumen Support

// bootstrap/app.php
$app->register(Sentry\Laravel\ServiceProvider::class);

Lumen does not auto-register service providers via Package Discovery. No artisan sentry:publish — create config/sentry.php manually and configure it as a Lumen config file:

$app->configure('sentry');

---

Laravel Octane (Long-Running Server)

When using Laravel Octane (Swoole/RoadRunner/FrankenPHP), requests are handled in long-lived workers. Sentry scope must be isolated per request:

// The SDK automatically handles this via context isolation
// when the Octane integration is active

⚠️ Important: If using withScope() / configureScope() for per-request context, ensure you're using withScope() (not configureScope()) in Octane environments — configureScope() persists across requests in long-running workers.

---

Feature Flags (Laravel Pennant)

The PennantIntegration auto-records Pennant feature flag evaluations:

use Laravel\Pennant\Feature;

// Checked features are automatically added as feature flags in Sentry
$value = Feature::value('billing-v2');
$active = Feature::active('new-onboarding');

No configuration needed — enabled automatically when laravel/pennant is installed.

---

Complete .env Reference

# Required
SENTRY_LARAVEL_DSN=https://examplePublicKey@o0.ingest.sentry.io/0

# Release & environment
SENTRY_RELEASE=1.0.0
SENTRY_ENVIRONMENT=production   # defaults to APP_ENV

# Performance
SENTRY_TRACES_SAMPLE_RATE=0.1   # 10% of transactions
SENTRY_PROFILES_SAMPLE_RATE=0.1 # 10% of traced transactions

# Logging
SENTRY_ENABLE_LOGS=true
LOG_CHANNEL=stack
LOG_STACK=single,sentry_logs
LOG_LEVEL=info
SENTRY_LOG_LEVEL=warning

# Privacy
SENTRY_SEND_DEFAULT_PII=false

# Breadcrumb toggles (all default true)
SENTRY_BREADCRUMBS_SQL_BINDINGS_ENABLED=false
SENTRY_BREADCRUMBS_CACHE_ENABLED=true

# Tracing toggles
SENTRY_TRACE_REDIS_COMMANDS=false
SENTRY_TRACE_MISSING_ROUTES_ENABLED=false

Logging — Sentry PHP SDK

Minimum SDK versions: sentry/sentry ≥ 4.12.0 · sentry/sentry-laravel ≥ 4.15.0 · sentry/sentry-symfony ≥ 5.4.0

Overview

Sentry PHP structured logs are separate from error reporting. They produce searchable log records in the Sentry Logs UI. The feature must be explicitly enabled with enable_logs: true.

Configuration

PHP (base SDK)

\Sentry\init([
    'dsn' => '___PUBLIC_DSN___',
    'enable_logs' => true,
]);

Laravel (.env)

LOG_CHANNEL=stack
LOG_STACK=single,sentry_logs
SENTRY_ENABLE_LOGS=true
LOG_LEVEL=info
SENTRY_LOG_LEVEL=warning    # optional: Sentry-specific threshold

config/sentry.php:

'enable_logs' => env('SENTRY_ENABLE_LOGS', false),
'logs_channel_level' => env('SENTRY_LOG_LEVEL', env('LOG_LEVEL', 'debug')),

For SDK versions ≤ 4.16.0, also add sentry_logs to config/logging.php channels manually. Versions > 4.16.0 auto-register it.

Symfony (config/packages/sentry.yaml + monolog.yaml)

# config/packages/sentry.yaml
sentry:
  options:
    enable_logs: true

# config/packages/monolog.yaml
monolog:
  handlers:
    sentry_logs:
      type: service
      id: Sentry\SentryBundle\Monolog\LogsHandler

# config/services.yaml
services:
  Sentry\SentryBundle\Monolog\LogsHandler:
    arguments:
      - !php/const Monolog\Logger::INFO

Code Examples

PHP — direct logger API

\Sentry\logger()->trace('Starting request processing');
\Sentry\logger()->debug('Cache lookup for key %s', values: ['user:42']);
\Sentry\logger()->info('User logged in');
\Sentry\logger()->warn('Rate limit approaching for %s', values: ['/api/v1/users']);
\Sentry\logger()->error('Payment failed for order %s', values: [$orderId]);
\Sentry\logger()->fatal('Database connection pool exhausted');

// Must flush at end of script (CLI) or long-running processes
\Sentry\logger()->flush();

PHP — with custom attributes

\Sentry\logger()->warn('This is a warning log with attributes.', attributes: [
    'attribute1' => 'string',
    'attribute2' => 1,
    'attribute3' => 1.0,
    'attribute4' => true,
]);

PHP — Monolog bridge

use Monolog\Level;
use Monolog\Logger;

\Sentry\init([
    'dsn' => '___PUBLIC_DSN___',
    'enable_logs' => true,
]);

$log = new Logger('app');
$log->pushHandler(new \Sentry\Monolog\LogsHandler(
    hub: \Sentry\SentrySdk::getCurrentHub(),
    level: Level::Info,
));

$log->info('Application started');
$log->error('Something went wrong', ['user_id' => 42]);

\Sentry\logger()->flush();

Laravel — Laravel Log facade

use Illuminate\Support\Facades\Log;

Log::info('This is an info message');
Log::warning('User {id} failed to login.', ['id' => $user->id]);
Log::error('Payment failed', [
    'user_id' => auth()->id(),
    'order_id' => $orderId,
]);

// Send only to Sentry (not to other channels)
Log::channel('sentry_logs')->error('Critical failure in payment module');

Symfony — via injected LoggerInterface

// Inject via constructor or autowiring
$this->logger->info('User {id} logged in', ['id' => $userId]);
$this->logger->warning('Slow query detected', ['duration_ms' => 850]);
$this->logger->error('Payment processing failed', [
    'user_id' => $userId,
    'action' => 'checkout',
]);

Filtering with before_send_log

PHP / Laravel:

\Sentry\init([
    'dsn' => '___PUBLIC_DSN___',
    'enable_logs' => true,
    'before_send_log' => function (\Sentry\Logs\Log $log): ?\Sentry\Logs\Log {
        if ($log->getLevel() === \Sentry\Logs\LogLevel::info()) {
            return null;  // drop info logs
        }
        return $log;
    },
]);

Symfony (uses service ID, not a closure):

sentry:
  options:
    before_send_log: "sentry.callback.before_send_log"

// App\Service\Sentry
public function getBeforeSendLog(): callable
{
    return function (\Sentry\Logs\Log $log): ?\Sentry\Logs\Log {
        if ($log->getLevel() === \Sentry\Logs\LogLevel::info()) {
            return null;
        }
        return $log;
    };
}

Two Log Channel Types in Laravel

These are independent — use sentry_logs for the structured logs feature.

Log Levels

Automatically Added Attributes

Every log record receives these automatically:

Flushing

Logs are buffered and must be flushed to be sent:

Long-running CLI tasks: Call \Sentry\logger()->flush() periodically to avoid memory buildup.

Troubleshooting

Metrics — Sentry PHP SDK

Minimum SDK versions: sentry/sentry ≥ 4.19.0 · sentry/sentry-laravel ≥ 4.20.0 · sentry/sentry-symfony ≥ 5.8.0

Overview

Custom metrics (counters, distributions, gauges) are enabled by default — no extra flag required. Use \Sentry\traceMetrics() as the entry point.

Note: The old \Sentry\metrics() API is fully deprecated — all methods are no-ops. Use \Sentry\traceMetrics() instead.

Metric Types

Code Examples

Counter — event occurrences

\Sentry\traceMetrics()->count('button-click', 5, [
    'browser' => 'Firefox',
    'app_version' => '1.0.0',
]);

Distribution — percentile analysis

Best for latencies, response sizes, durations where p90/p99 matter:

use \Sentry\Metrics\Unit;

\Sentry\traceMetrics()->distribution('page-load', 15.0, ['page' => '/home'], Unit::millisecond());

Gauge — space-efficient aggregates

Use when high cardinality is a concern; no percentile support:

use \Sentry\Metrics\Unit;

\Sentry\traceMetrics()->gauge('active-connections', 42.0, ['region' => 'eu-west'], Unit::none());

Flushing manually

Metrics are buffered (up to 1000 entries). Flush explicitly in CLI scripts or when emitting high volumes:

\Sentry\traceMetrics()->flush();

Filtering with before_send_metric

PHP / Laravel:

use \Sentry\Metrics\Types\Metric;

\Sentry\init([
    'dsn' => '___PUBLIC_DSN___',
    'before_send_metric' => static function (Metric $metric): ?Metric {
        if ($metric->getName() === 'removed-metric') {
            return null;  // drop this metric
        }
        return $metric;
    },
]);

Symfony (uses service ID, not a closure):

sentry:
  options:
    enable_metrics: true
    before_send_metric: 'App\Sentry\BeforeSendMetricCallback'

Units

use \Sentry\Metrics\Unit;

// Duration
Unit::nanosecond()    Unit::microsecond()   Unit::millisecond()
Unit::second()        Unit::minute()        Unit::hour()
Unit::day()           Unit::week()

// Information
Unit::bit()           Unit::byte()
Unit::kilobyte()      Unit::megabyte()      Unit::gigabyte()
Unit::terabyte()

// Fraction
Unit::ratio()         Unit::percent()

// Dimensionless
Unit::none()

Flushing

Metrics are buffered in a ring buffer (capacity: 1000 entries):

Buffer limit: When more than 1000 metrics are buffered, the oldest entries are dropped. Flush periodically in high-volume scripts.

Auto-Flush Threshold

Use metric_flush_threshold to automatically flush buffered metrics after N entries, without needing to call flush() manually:

PHP / Laravel:

\Sentry\init([
    'dsn' => '___PUBLIC_DSN___',
    'metric_flush_threshold' => 500,  // flush automatically after 500 metrics
]);

Symfony:

sentry:
  options:
    metric_flush_threshold: 500

This is useful in CLI scripts or workers that emit metrics continuously. The threshold triggers a flush mid-process so the buffer never fills to its 1000-entry cap.

Symfony Configuration

sentry:
  options:
    enable_metrics: true                      # default: true
    attach_metric_code_locations: true        # attach file/line info
    metric_flush_threshold: 500               # auto-flush after N metrics (optional)
    before_send_metric: 'App\Sentry\BeforeSendMetricCallback'

Automatically Added Attributes

Every metric receives these automatically:

Best Practices

• Keep attribute cardinality low — avoid user IDs, UUIDs, or timestamps as attribute values
• Use distribution over gauge when you need percentile analysis (p90, p99)
• Prefix metric names with your service: "payments.charge_time" not "charge_time"
• In high-throughput scripts, flush periodically to prevent the buffer from dropping old entries
• Laravel closures in config/sentry.php may cause issues with config:cache — see Laravel closures config docs

Troubleshooting

Profiling — Sentry PHP SDK

Requires the Excimer PHP extension (Linux/macOS only — Windows not supported)

Prerequisites

Excimer extension must be installed:

# Linux (recommended)
apt-get install php-excimer

# PECL
pecl install excimer

# Enable (if needed)
phpenmod -s fpm excimer

Excimer requires PHP 7.2+ and does not support Windows.

Version Requirements

Configuration

Profiling requires traces_sample_rate > 0. profiles_sample_rate is relative to traces_sample_rate.

PHP (base SDK)

\Sentry\init([
    'dsn' => '___PUBLIC_DSN___',
    'traces_sample_rate' => 1.0,
    'profiles_sample_rate' => 1.0,  // relative to traces_sample_rate
]);

Laravel (config/sentry.php)

return [
    'dsn' => env('SENTRY_LARAVEL_DSN', env('SENTRY_DSN')),
    'traces_sample_rate' => env('SENTRY_TRACES_SAMPLE_RATE') === null ? null : (float) env('SENTRY_TRACES_SAMPLE_RATE'),
    'profiles_sample_rate' => env('SENTRY_PROFILES_SAMPLE_RATE') === null ? null : (float) env('SENTRY_PROFILES_SAMPLE_RATE'),
];

.env:

SENTRY_TRACES_SAMPLE_RATE=1.0
SENTRY_PROFILES_SAMPLE_RATE=1.0

Symfony (config/packages/sentry.yaml)

sentry:
  options:
    traces_sample_rate: 1.0
    profiles_sample_rate: 1.0

How profiles_sample_rate Works

profiles_sample_rate is a fraction of already-sampled transactions, not of all requests:

Effective profiling rate = traces_sample_rate × profiles_sample_rate

Examples:
  traces_sample_rate: 1.0, profiles_sample_rate: 1.0  → 100% of requests profiled
  traces_sample_rate: 0.5, profiles_sample_rate: 0.5  → 25% of requests profiled
  traces_sample_rate: 0.1, profiles_sample_rate: 1.0  → 10% of requests profiled

Reducing Latency Impact

Profiling data is sent to Sentry after generating the response, not before:

• Laravel (FastCGI): Uses terminable middleware — data sent after response is dispatched
• Symfony (FastCGI): Uses kernel.terminate event — same behavior
• Non-FastCGI servers: Use a local Relay instance:

PHP App → local Relay (127.0.0.1) → Sentry Cloud

Best Practices

• Start with profiles_sample_rate: 1.0 in development to verify setup
• In production, reduce traces_sample_rate (e.g., 0.1) — profiling follows automatically
• Profiling has no meaningful overhead on Linux with Excimer; Relay is only needed to avoid latency on non-FastCGI servers
• Profiles are capped at 30 seconds per transaction

Troubleshooting

Symfony — Sentry SDK Deep Dive

Package: sentry/sentry-symfony · Requires sentry/sentry ^4.20.0

Symfony versions: ^4.4.20 through ^8.0

---

Installation & Setup

Requirements

• PHP ^7.2 | ^8.0
• Symfony ^4.4.20–^8.0
• zend.exception_ignore_args: Off in php.ini (required for stack trace arguments)

Install

composer require sentry/sentry-symfony

With Symfony Flex, this automatically:

• Registers the bundle in config/bundles.php
• Creates config/packages/sentry.yaml
• Adds SENTRY_DSN to .env

Without Flex, register manually:

// config/bundles.php
return [
    Sentry\SentryBundle\SentryBundle::class => ['all' => true],
];

Environment Variable Setup

###> sentry/sentry-symfony ###
SENTRY_DSN="___PUBLIC_DSN___"
###< sentry/sentry-symfony ###

Verify

php bin/console sentry:test

---

config/packages/sentry.yaml — Complete Schema

sentry:
    dsn: "%env(SENTRY_DSN)%"           # The ONLY mandatory option
    register_error_listener: true       # Register Symfony error event listener
    register_error_handler: true        # Register PHP error/exception handlers

    options:
        # Release & environment
        environment: "%kernel.environment%"  # Default: kernel env (not "production")
        release: "%env(default::SENTRY_RELEASE)%"
        server_name: "web-01"

        # Error monitoring
        sample_rate: 1.0
        ignore_exceptions:
            - "Symfony\\Component\\HttpKernel\\Exception\\NotFoundHttpException"
            - "Symfony\\Component\\HttpKernel\\Exception\\BadRequestHttpException"
        error_types: "E_ALL & ~E_NOTICE"
        before_send: "sentry.callback.before_send"   # DIC service ID

        # Tracing
        traces_sample_rate: 0.1
        traces_sampler: "sentry.callback.traces_sampler"
        ignore_transactions:
            - "GET /health"
        before_send_transaction: "sentry.callback.before_send_transaction"
        trace_propagation_targets:
            - "example.com"

        # Profiling
        profiles_sample_rate: 0.1

        # Logs
        enable_logs: true
        before_send_log: "sentry.callback.before_send_log"

        # Metrics
        enable_metrics: true
        before_send_metric: "sentry.callback.before_send_metric"

        # Breadcrumbs
        max_breadcrumbs: 100
        before_breadcrumb: "sentry.callback.before_breadcrumb"

        # Context
        context_lines: 5
        attach_stacktrace: false
        send_default_pii: false
        max_request_body_size: "medium"   # none|never|small|medium|always
        capture_silenced_errors: false
        max_value_length: 1024
        in_app_exclude:
            - "%kernel.cache_dir%"
            - "%kernel.project_dir%/vendor"
        in_app_include:
            - "%kernel.project_dir%/src"

        # Tags
        tags:
            server: "web-01"
            region: "us-east-1"

        # Transport
        http_proxy: "proxy.example.com:8080"
        http_connect_timeout: 2
        http_timeout: 5

        # Serialization
        class_serializers:
            App\User: "App\\Sentry\\Serializer\\UserSerializer"

    # Symfony Messenger integration
    messenger:
        enabled: true
        capture_soft_fails: true
        isolate_breadcrumbs_by_message: false

    # Symfony auto-instrumentation
    tracing:
        enabled: true
        dbal:
            enabled: true
            connections:
                - default
        twig:
            enabled: true
        cache:
            enabled: true
        http_client:
            enabled: true
        console:
            excluded_commands:
                - "messenger:consume"

---

Symfony-Specific Defaults

These differ from the plain PHP SDK:

---

Bundle-Level Options

---

Callable Options — DIC Service Pattern

Symfony's YAML configuration cannot hold inline PHP closures. All callable options must reference a DIC service ID whose factory method returns the callable.

# config/packages/sentry.yaml
sentry:
  options:
    before_send: "sentry.callback.before_send"
    traces_sampler: "sentry.callback.traces_sampler"
    before_send_log: "sentry.callback.before_send_log"

# config/services.yaml
services:
  sentry.callback.before_send:
    class: 'App\Service\SentryCallbacks'
    factory: ['@App\Service\SentryCallbacks', 'getBeforeSend']

  sentry.callback.traces_sampler:
    class: 'App\Service\SentryCallbacks'
    factory: ['@App\Service\SentryCallbacks', 'getTracesSampler']

  sentry.callback.before_send_log:
    class: 'App\Service\SentryCallbacks'
    factory: ['@App\Service\SentryCallbacks', 'getBeforeSendLog']

// src/Service/SentryCallbacks.php
namespace App\Service;

class SentryCallbacks
{
    public function getBeforeSend(): callable
    {
        return function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
            if ($hint?->exception instanceof MyIgnoredException) {
                return null;
            }
            return $event;
        };
    }

    public function getTracesSampler(): callable
    {
        return function (\Sentry\Tracing\SamplingContext $context): float {
            return $context->getParentSampled() ? 1.0 : 0.25;
        };
    }

    public function getBeforeSendLog(): callable
    {
        return function (\Sentry\Logs\Log $log): ?\Sentry\Logs\Log {
            if ($log->getLevel() === \Sentry\Logs\LogLevel::info()) {
                return null; // drop info logs
            }
            return $log;
        };
    }
}

This pattern applies to: before_send, before_send_transaction, before_send_check_in, before_send_log, before_send_metric, before_breadcrumb, traces_sampler, transport, http_client, logger, class_serializers values.

---

Auto-Instrumented Operations

Doctrine span data fields: db.system, db.user, db.name, server.address, server.port

⚠️ HTTP client tracing warning: "Using HTTP client tracing will not execute your requests concurrently." — tracing wraps each request synchronously.

Tracing Sub-Config

sentry:
  tracing:
    enabled: true
    dbal:
      enabled: true
      connections: [default]         # Specify which DB connections to trace
    twig:
      enabled: true
    cache:
      enabled: true
    http_client:
      enabled: true
    console:
      excluded_commands:
        - "messenger:consume"        # Always excluded by default
        - "app:my-command"

---

Structured Logs (≥ 5.4.0)

# config/packages/monolog.yaml
monolog:
  handlers:
    sentry_logs:
      type: service
      id: Sentry\SentryBundle\Monolog\LogsHandler

# config/services.yaml
services:
  Sentry\SentryBundle\Monolog\LogsHandler:
    arguments:
      - !php/const Monolog\Logger::INFO   # Minimum log level

# config/packages/sentry.yaml
sentry:
  options:
    enable_logs: true

// Usage — inject LoggerInterface via DI
class MyService
{
    public function __construct(private \Psr\Log\LoggerInterface $logger) {}

    public function doSomething(int $userId): void
    {
        $this->logger->info('User logged in');
        $this->logger->warning('User {id} failed to login.', ['id' => $userId]);
        $this->logger->error('Something went wrong', [
            'user_id' => $userId,
            'action'  => 'update_profile',
        ]);
    }
}

Auto-flush:

• HTTP requests: flushed on kernel.terminate
• Console commands: flushed on console.terminate

Traditional Monolog Handler (Error Events, Not Structured Logs)

For sending log messages as Sentry error events (not the Logs product):

# config/services.yaml
services:
  app.sentry.handler:
    class: Sentry\Monolog\Handler
    arguments:
      - '@Sentry\State\HubInterface'
      - !php/const Monolog\Logger::WARNING

  Sentry\Monolog\BreadcrumbHandler:
    arguments:
      - '@Sentry\State\HubInterface'
      - !php/const Monolog\Logger::WARNING

# config/packages/monolog.yaml
monolog:
  handlers:
    sentry:
      type: service
      id: app.sentry.handler
    sentry_buffer:
      type: buffer
      handler: sentry
      level: notice
      buffer_size: 50

The BufferFlushPass compiler pass auto-discovers BufferHandler instances and flushes them on kernel.terminate, console.command, console.terminate, and console.error.

---

Messenger Integration

The Messenger integration provides error capture for queue workers (not tracing spans):

sentry:
  messenger:
    enabled: true                         # Auto-enabled when MessageBusInterface exists
    capture_soft_fails: true              # Capture failures that will be retried
    isolate_breadcrumbs_by_message: false # Separate breadcrumb buffer per message

What it captures:

• Tags events with messenger.receiver_name, messenger.message_class, messenger.message_bus
• Unwraps nested exceptions from HandlerFailedException, DelayedMessageHandlingException, WrappedExceptionsInterface
• Sets ExceptionMechanism(isHandled: $willRetry) — retried failures are marked as handled
• Flushes the client after each failure (background workers have no shutdown hook)

⚠️ No tracing spans: There is no MessengerTracingMiddleware in the current SDK — Messenger integration is error-capture only. Use captureCheckIn() manually for cron-like queue monitoring.

---

Cron Monitoring

The Symfony SDK has no dedicated scheduled-task integration. Use the PHP SDK functions directly:

use Sentry\CheckInStatus;
use Sentry\MonitorConfig;
use Sentry\MonitorSchedule;

// Two-step check-in (recommended)
$checkInId = \Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::inProgress(),
);

// ... do work ...

\Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::ok(),
    checkInId: $checkInId,
);

// Wrapper approach
\Sentry\withMonitor(
    slug: 'my-cron-job',
    callback: fn () => $this->doWork(),
);

// With programmatic monitor config
$monitorConfig = new \Sentry\MonitorConfig(
    \Sentry\MonitorSchedule::crontab('*/10 * * * *'),
    checkinMargin: 5,
    maxRuntime: 15,
    timezone: 'Europe/Vienna',
    failureIssueThreshold: 2,
    recoveryThreshold: 5,
);

$checkInId = \Sentry\captureCheckIn(
    slug: 'my-cron-job',
    status: CheckInStatus::inProgress(),
    monitorConfig: $monitorConfig,
);

Filter check-ins:

sentry:
  options:
    before_send_check_in: "App\\Sentry\\BeforeSendCheckInCallback"

---

Console Command Tracing & Monitoring

Error Capture (ConsoleListener)

Auto-enabled. Tags every console command scope with:

• console.command — command name
• console.command.exit_code — exit code
• Full command — full command with arguments (extra context)

Flushes logs AND metrics on console.terminate.

Tracing (TracingConsoleListener)

sentry:
  tracing:
    console:
      excluded_commands:
        - "messenger:consume"   # Always excluded

Creates transactions with:

• op: 'console.command'
• origin: 'auto.console'
• source: TransactionSource::task()
• Status: ok() if exit code 0, internalError() otherwise

---

Event Listeners Auto-Registered

Distributed Tracing — Automatic Header Handling

The TracingRequestListener automatically reads incoming trace headers:

// Accepts both Sentry and W3C trace context formats:
$request->headers->get('sentry-trace')   // Sentry format
$request->headers->get('traceparent')    // W3C format
$request->headers->get('baggage')

The AbstractTraceableHttpClient decorator automatically injects outbound headers on all Symfony HTTP Client requests:

sentry-trace: <value>
baggage: <value>
traceparent: <value>   # W3C trace context

Respects trace_propagation_targets — only injects headers to matching hostnames.

---

Metrics (≥ 5.8.0)

use function Sentry\traceMetrics;

traceMetrics()->count('button-click', 5, ['browser' => 'Firefox']);
traceMetrics()->distribution('page-load', 15.0, ['page' => '/home'], \Sentry\Unit::millisecond());
traceMetrics()->gauge('memory-usage', memory_get_usage(), ['worker' => 'web-01']);

Config:

sentry:
  options:
    enable_metrics: true
    before_send_metric: "App\\Sentry\\BeforeSendMetricCallback"

Auto-flush: Flushed automatically on kernel.terminate and console.terminate — no manual flush needed in typical web/console contexts.

Tracing — Sentry PHP SDK

Minimum SDK: sentry/sentry ^4.0 · sentry/sentry-laravel ^4.0 · sentry/sentry-symfony ^5.0

Configuration

Code Examples

Enable tracing

// Plain PHP — uniform sample rate
\Sentry\init([
    'dsn'                => 'https://<key>@<org>.ingest.sentry.io/<project>',
    'traces_sample_rate' => 0.2,  // trace 20% of requests
]);

// Laravel — config/sentry.php
'traces_sample_rate' => env('SENTRY_TRACES_SAMPLE_RATE') === null
    ? null
    : (float) env('SENTRY_TRACES_SAMPLE_RATE'),

# Symfony — config/packages/sentry.yaml
sentry:
    options:
        traces_sample_rate: 0.2

Dynamic sampling with traces_sampler

// Plain PHP — closure directly in init()
\Sentry\init([
    'dsn' => '...',
    'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float {
        $transactionName = $context->getTransactionContext()->getName();

        // Drop health checks
        if (in_array($transactionName, ['/healthz', '/up', '/ping'])) {
            return 0.0;
        }

        // Honour parent sampling decision in distributed traces
        $parentSampled = $context->getParentSampled();
        if ($parentSampled !== null) {
            return (float) $parentSampled;
        }

        // 50% of HTTP requests, 10% of everything else
        return str_starts_with($transactionName, 'GET ') || str_starts_with($transactionName, 'POST ')
            ? 0.5
            : 0.1;
    },
]);

# Symfony — traces_sampler must be wired through the service container (closures can't be serialized)
sentry:
    options:
        traces_sampler: "sentry.callback.traces_sampler"

services:
    sentry.callback.traces_sampler:
        class: 'App\Service\Sentry'
        factory: ['@App\Service\Sentry', 'getTracesSampler']

// src/Service/Sentry.php
namespace App\Service;

class Sentry
{
    public function getTracesSampler(): callable
    {
        return function (\Sentry\Tracing\SamplingContext $context): float {
            return 0.5;
        };
    }
}

Custom span API — TransactionContext and SpanContext

use Sentry\Tracing\TransactionContext;
use Sentry\Tracing\SpanContext;

// 1. Build and start a root transaction
$transactionContext = TransactionContext::make()
    ->setName('process-order')
    ->setOp('task');

$transaction = \Sentry\startTransaction($transactionContext);

// 2. Register on the hub so child spans attach to it
\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);

// 3. Add a child span
$spanContext = SpanContext::make()
    ->setOp('db.query')
    ->setDescription('SELECT * FROM orders WHERE id = ?');

$span = $transaction->startChild($spanContext);
// ... do work ...
$span->finish();

// 4. Finish transaction — submits everything to Sentry
$transaction->finish();

\Sentry\trace() helper (recommended)

Removes boilerplate: starts the span, sets it as current, finishes it automatically.

$result = \Sentry\trace(
    function (\Sentry\State\Scope $scope): array {
        return fetchOrdersFromDatabase();
    },
    SpanContext::make()
        ->setOp('db.query')
        ->setDescription('fetch-orders')
);

Safe manual span pattern (handles no-transaction case)

function expensiveOperation(): void
{
    $parent = \Sentry\SentrySdk::getCurrentHub()->getSpan();
    $span = null;

    if ($parent !== null) {
        $context = SpanContext::make()
            ->setOp('some_operation')
            ->setDescription('This is a description');
        $span = $parent->startChild($context);
        \Sentry\SentrySdk::getCurrentHub()->setSpan($span);
    }

    try {
        // ... do work ...
    } finally {
        if ($span !== null) {
            $span->finish();
            \Sentry\SentrySdk::getCurrentHub()->setSpan($parent);
        }
    }
}

Span data attributes

// At creation time
$spanContext = SpanContext::make()
    ->setOp('http.client')
    ->setData([
        'http.request.method'       => 'GET',
        'http.response.status_code' => 200,
    ]);

// On an existing span
$span->setData(['db.system' => 'postgresql', 'db.table' => 'orders']);

// Read-modify-write
$span->setData([
    'counter' => $span->getData('counter', 0) + 1,
]);

Span status

$span->setStatus(\Sentry\Tracing\SpanStatus::createFromHttpStatusCode($response->getStatusCode()));
$transaction->setStatus(\Sentry\Tracing\SpanStatus::ok());
$transaction->setStatus(\Sentry\Tracing\SpanStatus::internalError());

Accessing the active span/transaction

$transaction = \Sentry\SentrySdk::getCurrentHub()->getTransaction();  // ?Transaction
$span        = \Sentry\SentrySdk::getCurrentHub()->getSpan();          // ?Span

if ($transaction !== null) {
    $transaction->setData(['order.type' => 'subscription']);
}

Mutating all spans via before_send_transaction

\Sentry\init([
    'before_send_transaction' => function (\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event {
        // Drop health-check transactions
        if (in_array($event->getTransaction(), ['GET /up', 'GET /healthz'])) {
            return null;
        }

        // Add data to every span in the transaction
        foreach ($event->getSpans() as $span) {
            $span->setData(['server' => 'web-01']);
        }

        return $event;
    },
]);

Auto-Instrumentation Matrix

Plain PHP — No automatic instrumentation

The plain PHP SDK provides zero automatic instrumentation. Every transaction and span must be created manually using the Custom Span API.

Laravel — Auto-instrumented operations

The Tracing\Middleware is auto-prepended and the Tracing\ServiceProvider wires all listeners automatically.

// Filesystem disk opt-in (config/filesystems.php)
'disks' => \Sentry\Laravel\Features\Storage\Integration::configureDisks([
    'local' => ['driver' => 'local', 'root' => storage_path('app'), 'throw' => false],
    's3'    => ['driver' => 's3', /* ... */],
], enableSpans: true, enableBreadcrumbs: true),

Symfony — Auto-instrumented operations

TracingRequestListener and other compiler-wired listeners activate automatically.

Distributed Tracing

Two headers carry trace context between services:

CORS note: Both headers must be in your CORS allowlist if browser requests are involved. Proxies and API gateways may strip unknown headers.

Extracting incoming trace context

$sentryTrace = $_SERVER['HTTP_SENTRY_TRACE'] ?? '';
$baggage     = $_SERVER['HTTP_BAGGAGE'] ?? '';

// continueTrace() returns a TransactionContext pre-populated with parent trace data
$ctx = \Sentry\continueTrace($sentryTrace, $baggage);
$ctx->setName('process-payment')->setOp('task');

$transaction = \Sentry\startTransaction($ctx);
\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);

Injecting outgoing trace headers

// Manual header injection (e.g., Guzzle, curl, any HTTP client)
$headers = [
    'sentry-trace' => \Sentry\getTraceparent(),
    'baggage'      => \Sentry\getBaggage(),
];

$client = new \GuzzleHttp\Client();
$response = $client->get('https://internal-api.example.com', [
    'headers' => $headers,
]);

Guzzle middleware (automatic header injection)

use Sentry\Tracing\GuzzleTracingMiddleware;

$stack = \GuzzleHttp\HandlerStack::create();
$stack->push(GuzzleTracingMiddleware::trace());

$client = new \GuzzleHttp\Client(['handler' => $stack]);
$response = $client->get('https://example.com/');
// sentry-trace + baggage headers injected automatically; span created for the request

continueTrace() full pattern (queue consumers, workers)

// Continue a distributed trace from a queue job payload
$context = \Sentry\continueTrace(
    $job->getMetadata('sentry_trace'),
    $job->getMetadata('baggage')
);
$context->setOp('queue.process')->setName('App\Jobs\ProcessPayment');

$transaction = \Sentry\startTransaction($context);
\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);

try {
    $job->handle();
} catch (\Throwable $e) {
    $transaction->setStatus(\Sentry\Tracing\SpanStatus::internalError());
    throw $e;
} finally {
    $transaction->finish();
}

HTML meta tag injection (frontend/backend trace stitching)

Inject these tags into your HTML <head> so the Sentry JavaScript SDK can continue the backend trace in the browser.

// Plain PHP
echo sprintf('<meta name="sentry-trace" content="%s"/>', \Sentry\getTraceparent());
echo sprintf('<meta name="baggage" content="%s"/>', \Sentry\getBaggage());

{{-- Laravel Blade template --}}
{!! \Sentry\Laravel\Integration::sentryMeta() !!}

{{-- Or individually: --}}
{!! \Sentry\Laravel\Integration::sentryTracingMeta() !!}
{!! \Sentry\Laravel\Integration::sentryBaggageMeta() !!}

{# Symfony Twig template — inject via a controller variable #}
{{ sentry_trace_meta | raw }}
{{ sentry_baggage_meta | raw }}

Framework-automatic propagation

Profiling

Requires the Excimer PHP extension (Wikimedia sampling profiler).

• Platform: Linux or macOS only — Windows is not supported
• PHP: 7.2+

# Install Excimer
apt-get install php-excimer      # Debian/Ubuntu
pecl install excimer             # PECL
phpenmod -s fpm excimer          # Enable

// Plain PHP — traces_sample_rate must be set; profiles_sample_rate is relative to it
\Sentry\init([
    'dsn'                  => '...',
    'traces_sample_rate'   => 1.0,
    'profiles_sample_rate' => 1.0,  // profile 100% of sampled transactions
]);

// Laravel — config/sentry.php
'traces_sample_rate'   => 1.0,
'profiles_sample_rate' => 1.0,

# Symfony — config/packages/sentry.yaml
sentry:
    options:
        traces_sample_rate: 1.0
        profiles_sample_rate: 1.0

profiles_sample_rate is a ratio of already-sampled transactions:

Effective profiling rate = traces_sample_rate × profiles_sample_rate

Examples:
  0.5 × 0.5 = 25% of all requests profiled
  1.0 × 1.0 = 100% of all requests profiled
  0.1 × 1.0 = 10% of all requests profiled

Framework-Specific Notes

Plain PHP

• Zero automatic instrumentation — create every transaction and span manually
• Call \Sentry\flush() before process exit in CLI scripts to ensure buffered data is sent
• For queue workers and long-running processes, start a transaction per job with continueTrace() to preserve distributed trace context

Laravel

• Tracing\Middleware is auto-prepended by Tracing\ServiceProvider — do not add it manually
• Transaction start time is backdated to Laravel boot via setBootedTimestamp() — captures full request duration including framework startup
• missing_routes: false (default) discards 404/unmatched route transactions; set to true to trace them
• config:cache breaks if traces_sampler is a closure — use a class/callable string or only set it at runtime
• Queue tracing: tracing.queue_jobs: true creates spans; tracing.queue_job_transactions: true creates standalone transactions with distributed trace propagation using payload keys sentry_trace_parent_data / sentry_baggage_data
• On Octane: FastCGI terminable middleware dispatches spans after response — no user-visible latency. Without FastCGI, use a local Relay proxy

Symfony

• TracingRequestListener accepts both sentry-trace (Sentry) and traceparent (W3C) headers for incoming distributed traces
• HTTP Client decorator injects three outgoing headers: sentry-trace, baggage, traceparent
• Console commands are auto-traced by TracingConsoleListener — creates a root transaction if none is active, otherwise creates a child span
• Messenger integration is error-capture only (via MessengerListener) — no tracing spans for queue messages
• FastCGI: spans are sent after response via kernel.terminate. Without FastCGI, use a local Relay proxy

Span Ops Reference

Troubleshooting