Sentry for Laravel

https://docs.sentry.io/platforms/php/guides/laravel/
Admin
Documentation for integrating Sentry, an error tracking and performance monitoring platform, with...
Tokens:50,864
Snippets:440
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example SDK logger output

Source: https://docs.sentry.io/platforms/php/guides/laravel/troubleshooting

Example output from the SDK logger when enabled. It shows debug, info, and warning messages about installed integrations, transaction sampling, profiling, and sending transactions to Sentry.

```bash
sentry/sentry: [debug] The "Sentry\Integration\ExceptionListenerIntegration, Sentry\Integration\ErrorListenerIntegration, Sentry\Integration\FatalErrorListenerIntegration, Sentry\Integration\RequestIntegration, Sentry\Integration\TransactionIntegration, Sentry\Integration\FrameContextifierIntegration, Sentry\Integration\EnvironmentIntegration, Sentry\Integration\ModulesIntegration" integration(s) have been installed.
sentry/sentry: [info] Transaction [e2919a7b0f954478b6994c7282b060de] was started and sampled, decided by config:traces_sample_rate.
sentry/sentry: [info] Transaction [e2919a7b0f954478b6994c7282b060de] started profiling because it was sampled.
sentry/sentry: [info] Sending transaction [59390dc9dd934c0290d8cdc7a589da82] to o1.ingest.sentry.io [project:1].
sentry/sentry: [warning] The profile does not contain enough samples, the profile will be discarded.
sentry/sentry: [info] Sent transaction [59390dc9dd934c0290d8cdc7a589da82] to o1.ingest.sentry.io [project:1]. Result: "success" (status: 200).
```

--------------------------------

### Install Excimer via PECL

Source: https://docs.sentry.io/platforms/php/guides/laravel/profiling

Install the Excimer PHP extension using PECL. This is an alternative installation method.

```bash
pecl install excimer
```

--------------------------------

### Install OpenTelemetry packages via Composer

Source: https://docs.sentry.io/platforms/php/guides/laravel/integrations/otlp

Run this command to install the required OpenTelemetry packages (open-telemetry/sdk and open-telemetry/exporter-otlp) via Composer.

```bash
composer require \
  open-telemetry/sdk \
  open-telemetry/exporter-otlp
```

--------------------------------

### Install Excimer via Linux Package Manager

Source: https://docs.sentry.io/platforms/php/guides/laravel/profiling

Install the Excimer PHP extension using apt-get. This is one of the installation methods for the profiling extension.

```bash
apt-get install php-excimer
```

--------------------------------

### Install sentry/sentry-laravel with Composer

Source: https://docs.sentry.io/platforms/php/guides/laravel

Installs the Sentry Laravel package via Composer. Run this in your Laravel project root.

```bash
composer require sentry/sentry-laravel
```

--------------------------------

### Create a transaction and span for an expensive operation

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/custom-instrumentation

Use this snippet to instrument a specific region of code by creating a transaction and a child span. It sets up the transaction context, starts the transaction, sets it as the current span, then starts a child span for the expensive operation, finishes the span, and finally finishes the transaction to submit it to Sentry.

```php
// Setup context for the full transaction
$transactionContext = \Sentry\Tracing\TransactionContext::make()
    ->setName('Example Transaction')
    ->setOp('http.server');

// Start the transaction
$transaction = \Sentry\startTransaction($transactionContext);

// Set the current transaction as the current span so we can retrieve it later
\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);

// Setup the context for the expensive operation span
$spanContext = \Sentry\Tracing\SpanContext::make()
    ->setOp('expensive_operation');

// Start the span
$span1 = $transaction->startChild($spanContext);

// Set the current span to the span we just started
\Sentry\SentrySdk::getCurrentHub()->setSpan($span1);

// Calling expensive_operation()
expensive_operation();

// Finish the span
$span1->finish();

// Set the current span back to the transaction since we just finished the previous span
\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);

// Finish the transaction, this submits the transaction and it's span to Sentry
$transaction->finish();
```

--------------------------------

### Configure traces_sampler with class method reference

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/sampling

Set the `traces_sampler` option to a closure or callable that accepts a `\Sentry\Tracing\SamplingContext` object and returns a sample rate between 0 and 1. This example references a static method `tracesSampler` on the `App\Exceptions\Sentry` class.

```php
'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'],
```

--------------------------------

### Enable Tracing with SENTRY_TRACES_SAMPLE_RATE

Source: https://docs.sentry.io/platforms/php/guides/laravel

Set the traces sample rate in your .env file to enable Tracing. A value greater than 0.0 enables Tracing; null (the default) disables it. The example transmits 100% of captured traces, so lower it in production to avoid quota issues.

```shell
# Be sure to lower this value in production otherwise you could burn through your quota quickly.
SENTRY_TRACES_SAMPLE_RATE=1.0
```

--------------------------------

### Emit wide events with full context

Source: https://docs.sentry.io/platforms/php/guides/laravel/logs

Shows the recommended pattern of emitting one comprehensive log per operation with all relevant context instead of many thin logs. The example contrasts scattered info logs with a single wide event that includes order, user, cart, and timing attributes.

```php
// ❌ Scattered thin logs
\Sentry\logger()->info('Starting checkout');
\Sentry\logger()->info('Validating cart');
\Sentry\logger()->info('Processing payment');
\Sentry\logger()->info('Checkout complete');

// ✅ One wide event with full context
\Sentry\logger()->info('Checkout completed', attributes: [
    'order_id' => $order->id,
    'user_id' => $user->id,
    'user_tier' => $user->subscription,
    'cart_value' => $cart->total,
    'item_count' => count($cart->items),
    'payment_method' => 'stripe',
    'duration_ms' => (microtime(true) - $startTime) * 1000,
]);
```

--------------------------------

### Set uniform sample rate with traces_sample_rate

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/sampling

Set the `traces_sample_rate` option to a number between 0 and 1 to send a percentage of transactions. For example, 0.2 sends approximately 20% of transactions.

```php
'traces_sample_rate' => 0.2,
```

--------------------------------

### Set Current Transaction with startTransaction

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/custom-instrumentation

Starts a new transaction and sets it as the current span on the hub. Use this to set the current transaction after starting one.

```php
$transactionContext = \Sentry\Tracing\TransactionContext::make()
    ->setName('Example Transaction');
    ->setOp('http.server');

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

// A transaction is a span so we set it using `setSpan`
\Sentry\SentrySdk::getCurrentHub()->setSpan($transaction);
```

--------------------------------

### Enable filesystem spans for select disks with configureDisk()

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/automatic-instrumentation

Use Sentry\Laravel\Features\Storage\Integration::configureDisk() on individual disk entries to enable spans and breadcrumbs only for those disks. The example shows enabling for the 's3' disk while leaving 'local' unchanged.

```php
'disks' => [
    'local' => [
        'driver' => 'local',
        'root' => storage_path('app'),
        'throw' => false,
    ],

    's3' => Sentry\Laravel\Features\Storage\Integration::configureDisk('s3', [
        // ...
    ], /* enableSpans: */ true, /* enableBreadcrumbs: */ true),
],
```

--------------------------------

### Log to all channels and directly to Sentry channel

Source: https://docs.sentry.io/platforms/php/guides/laravel/logs

Use Laravel's Log facade to send messages to all configured channels (including Sentry) or directly to the 'sentry_logs' channel. The example shows info, warning, and error levels, with structured data for the warning.

```php
use Illuminate\Support\Facades\Log;

// Log to all channels in the stack (including Sentry)
Log::info('This is an info message');
Log::warning('User {id} failed to login.', ['id' => $user->id]);
Log::error('This is an error message');

// Log directly to the Sentry channel
Log::channel('sentry_logs')->error('This will only go to Sentry');
```

--------------------------------

### Ignore transactions by string with ignore_transactions in Laravel

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/filtering

Filter out transactions that match a certain string using the `ignore_transactions` option. The example ignores transactions with the string 'GET /health'.

```php
'ignore_transactions' => [
    'GET /health',
],
```

--------------------------------

### Build Excimer from Source

Source: https://docs.sentry.io/platforms/php/guides/laravel/profiling

Clone the Excimer repository and build the extension from source. After building, you may need to enable the extension with phpenmod.

```bash
git clone https://github.com/wikimedia/mediawiki-php-excimer.git

cd excimer/
phpize && ./configure && make && sudo make install
```

```bash
phpenmod -s fpm excimer
# or
phpenmod -s apache2 excimer
```

--------------------------------

### Enable Tracing with traces_sample_rate

Source: https://docs.sentry.io/platforms/php/guides/laravel/profiling

Set the traces_sample_rate configuration to enable tracing, which is required for profiling to work.

```php
'traces_sample_rate' => 1.0,
```

--------------------------------

### Assign data attributes when starting a transaction or span

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/custom-instrumentation

Use this to assign data attributes when starting a transaction or span. The transaction context uses setName, setOp, and setData; the span context uses setOp and setData. Note that the span is started with $transaction->startChild($context).

```php
// Create a transaction and assign data attributes...
$transactionContext = \Sentry\Tracing\TransactionContext::make()
    ->setName('Example Transaction')
    ->setOp('http.server')
    ->setData([
        'data_attribute_1' => 42,
        'data_attribute_2' => true,
    ]);
$transaction = \Sentry\startTransaction($transactionContext);

// ... or create a span and assign data attributes

$spanContext = \Sentry\Tracing\SpanContext::make()
    ->setOp('http.client')
    ->setData([
        'data_attribute_1' => 42,
        'data_attribute_2' => true,
    ]);
$transaction->startChild($context);
```

--------------------------------

### Enable Profiling with profiles_sample_rate

Source: https://docs.sentry.io/platforms/php/guides/laravel/profiling

Set both traces_sample_rate and profiles_sample_rate to enable profiling. The profiles_sample_rate is relative to traces_sample_rate.

```php
'traces_sample_rate' => 1.0,
// Set a sampling rate for profiling - this is relative to traces_sample_rate
'profiles_sample_rate' => 1.0,
```

--------------------------------

### Configure logger option in config/sentry.php

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/options

Configures the logger option to enable debug output. The first example logs to a file, the second to stdout. Not recommended for production.

```php
// This logs messages to the provided file path
'logger' => new \Sentry\Logger\DebugFileLogger(filePath: storage_path('logs/sentry.log')),

// This logs messages to stdout
'logger' => new \Sentry\Logger\DebugStdOutLogger(),
```

--------------------------------

### Add Facade to config/app.php

Source: https://docs.sentry.io/platforms/php/guides/laravel/usage

Add the custom facade to the 'aliases' array in config/app.php.

```php
'aliases' => array(
    // ...
    'SentryLaravel' => App\Support\SentryLaravelFacade::class,
)

```

--------------------------------

### Emit a Distribution with \Sentry\traceMetrics()->distribution()

Source: https://docs.sentry.io/platforms/php/guides/laravel/metrics

Use this to emit a distribution metric, which supports aggregations like p90, min, max, and avg. The fourth argument specifies the unit, here milliseconds.

```php
use \Sentry\Metrics\Unit;

// Add '15.0' to a distribution used for tracking the loading times per page.
\Sentry\traceMetrics()->distribution('page-load', 15.0, ['page' => '/home'], Unit::millisecond());
```

--------------------------------

### Remove user from Sentry scope in Laravel

Source: https://docs.sentry.io/platforms/php/guides/laravel/enriching-events/identify-user

Clear the currently set user from the Sentry scope. Useful when you need to remove user context, for example after logout.

```php
\Sentry\Laravel\Integration::configureScope(static function (\Sentry\State\Scope $scope): void {
    $scope->removeUser();
});
```

--------------------------------

### Wrap HTTP Requests in a Span

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/requests-module

Manually wrap an HTTP request in a Sentry span using SpanContext and SpanStatus. Requires a running transaction; the example uses Cake\Http\Client but can be adapted to other clients.

```php
$parentSpan = \Sentry\SentrySdk::getCurrentHub()->getSpan();

if ($parentSpan !== null) {
    $context = \Sentry\Tracing\SpanContext::make()
        ->setOp('http.client');
    $span = $parentSpan->startChild($context);

    // Set the span we just started as the current span
    \Sentry\SentrySdk::getCurrentHub()->setSpan($span);
    
    $client = new \Cake\Http\Client();
    $response = $client->get('https://example.com/');
    
    $span
        ->setDescription('GET https://example.com/')
        ->setStatus(\Sentry\Tracing\SpanStatus::createFromHttpStatusCode($response->getStatusCode()))
        ->setData([
            'http.request.method' => 'GET',
            'http.response.body.size' => $response->getBody()->getSize(),
            'http.response.status_code' => $response->getStatusCode(),
        ])
        ->finish();

    // Restore the span back to the parent span
    \Sentry\SentrySdk::getCurrentHub()->setSpan($parentSpan);
}
```

--------------------------------

### Check logging.php configuration for environment variables

Source: https://docs.sentry.io/platforms/php/guides/laravel/logs

Ensure the default log channel and stack channel allow configuration using environment variables. The snippet shows the relevant parts of config/logging.php.

```php
    // ...
    'default' => env('LOG_CHANNEL', 'stack'),
    // ...
    'channels' => [
        'stack' => [
            'driver' => 'stack',
            'channels' => explode(',', (string) env('LOG_STACK', 'single')),
            'ignore_exceptions' => false,
        ],
    // ...
```

--------------------------------

### Log with additional attributes for Sentry

Source: https://docs.sentry.io/platforms/php/guides/laravel/logs

Pass additional attributes to the logging function; these properties are sent to Sentry and can be searched in the Logs UI or added as columns. The example logs an error with user_id, action, and additional_data.

```php
use Illuminate\Support\Facades\Log;

Log::error('Something went wrong', [
    'user_id' => auth()->id(),
    'action' => 'update_profile',
    'additional_data' => $data,
]);
```

--------------------------------

### Extract Incoming Tracing Information with \Sentry\continueTrace()

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/trace-propagation/custom-instrumentation

Extracts the 'sentry-trace' and 'baggage' headers from the incoming request and stores them in memory for later use. Use this at the start of your request handling to capture tracing context from upstream services.

```php
$sentryTraceHeader = $request->getHeaderLine('sentry-trace');
$baggageHeader = $request->getHeaderLine('baggage');

\Sentry\continueTrace($sentryTraceHeader, $baggageHeader);
```

--------------------------------

### Emit a Counter with \Sentry\traceMetrics()->count()

Source: https://docs.sentry.io/platforms/php/guides/laravel/metrics

Use this to emit a counter metric. The first argument is the metric key, the second is the value to add, and the third is an optional array of tags. The SDK buffers up to 1000 metric entries at a time.

```php
// Record five total button clicks
\Sentry\traceMetrics()->count('button-click', 5, ['browser' => 'Firefox', 'app_version' => '1.0.0']);
```

--------------------------------

### Configure traces_sampler callable and implement tracesSampler

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/laravel-options

Use the traces_sampler option as a callable to control which requests are monitored. The first block configures the callable in the Sentry configuration, and the second block implements the sampler method, which returns a sample rate between 0.0 and 1.0 based on the sampling context.

```php
'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'],
```

```php
class Sentry
{
    public static function tracesSampler(\Sentry\Tracing\SamplingContext $context): float
    {
        // Keep front-end and back-end traces connected.
        if ($context->getParentSampled()) {
            return 1.0;
        }

        if (some_condition()) {
            // Drop this transaction.
            return 0.0;
        }

        // Default sample rate for all other transactions.
        return 0.25;
    }
}
```

--------------------------------

### Add custom sampling context data with startTransaction in PHP

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/sampling

Passes a custom sampling context as the second argument to startTransaction. Use this to provide sensitive or large data to the sampler without attaching it to the transaction as tags or data.

```php
\Sentry\startTransaction(
    new \Sentry\Tracing\TransactionContext(
        $name = 'Search from navbar',
        $parentSampled = false
    ),
    $customSamplingContext = [
        // PII
        'userId' => '12312012',
        // too big to send
        'resultsFromLastSearch' => [ ... ]
    ]
);
```

--------------------------------

### Create a span with the trace function

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/custom-instrumentation

Use the `trace` function to create a new span and set it as the current span, reducing boilerplate. Configure the span with `SpanContext::make()` and set `op` and `description` values.

```php
function expensive_operation(): void
{
    $spanContext = \Sentry\Tracing\SpanContext::make()
        ->setOp('some_operation')
        ->setDescription('This is a description');

    \Sentry\trace(function () {
        // Do the expensive operation...
    }, $spanContext);
}
```

--------------------------------

### Set a tag with configureScope

Source: https://docs.sentry.io/platforms/php/guides/laravel/enriching-events/tags

Use \Sentry\configureScope to set a tag on the current scope. The example sets the tag 'page.locale' to 'de-at'. Tag keys and values have a maximum length of 200 characters; values cannot contain newline characters.

```php
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setTag('page.locale', 'de-at');
});
```

--------------------------------

### Manually create and manage a span

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/custom-instrumentation

Manually create a child span for more control. Checks for a parent span, starts a child span, sets it as current, and restores the parent after finishing. Use this when you need explicit control over span lifecycle.

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

    // Check if we have a parent span (this is the case if we started a transaction earlier)
    if ($parent !== null) {
        $context = \Sentry\Tracing\SpanContext::make()
            ->setOp('some_operation')
            ->setDescription('This is a description');
        $span = $parent->startChild($context);

        // Set the current span to the span we just started
        \Sentry\SentrySdk::getCurrentHub()->setSpan($span);
    }

    try {
        // Do the expensive operation...
    } finally {
        // We only have a span if we started a span earlier
        if ($span !== null) {
            $span->finish();

            // Restore the current span back to the parent span
            \Sentry\SentrySdk::getCurrentHub()->setSpan($parent);
        }
    }
}
```

--------------------------------

### Add Span When Retrieving Data From the Cache (PHP)

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/caches-module

Wrap a cache get operation in a Sentry span. Set op to 'cache.get' and include cache.hit and optionally cache.item_size. Requires a parent span; if none exists, the operation is not instrumented.

```php
$key = 'cache_key';
$value = null;

$parentSpan = \Sentry\SentrySdk::getCurrentHub()->getSpan();

if ($parentSpan !== null) {
    $context = \Sentry\Tracing\SpanContext::make()
        ->setOp('cache.get');

    $span = $parentSpan->startChild($context);

    \Sentry\SentrySdk::getCurrentHub()->setSpan($span);

    // Perform you cache operation
    $value = Cache::get($key);
    
    $span->setData([
        // Describe the cache server you are accessing
        'network.peer.address' => '127.0.0.1',
        'network.peer.port' => 9000,
        // Add the key you just retrieved from the cache
        'cache.key' => $key
    ]);

    if ($value !== null) {
        $span->setData([
            // If you retrieved a value, the cache was hit
            'cache.hit' => true,
            // Optionally, add the size of the value you retrieved
            'cache.item_size' => strlen($value),
        ]);
    } else {
        $span->setData([
            // If you could not retrieve a value, it was a miss
            'cache.hit' => false,
        ]);
    }

    $span->finish();

    \Sentry\SentrySdk::getCurrentHub()->setSpan($parentSpan);
}
```

--------------------------------

### Configure Sentry DSN for Laravel

Source: https://docs.sentry.io/platforms/php/guides/laravel

Run the artisan command to publish the Sentry configuration file and set the DSN in your .env file. The command creates config/sentry.php and adds the DSN to .env. Ensure zend.exception_ignore_args is set to Off in php.ini to receive stack trace arguments.

```shell
php artisan sentry:publish --dsn=https://<key>@o<orgId>.ingest.sentry.io/<projectId>
```

```shell
SENTRY_LARAVEL_DSN=https://<key>@o<orgId>.ingest.sentry.io/<projectId>
```

--------------------------------

### Configure prefixes option in Sentry init

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/options

Use this snippet to set the 'prefixes' option in the Sentry initialization. It strips the given prefixes from filenames in stack traces to normalize paths across environments. The example shows stripping '/var/www/' and '/home/user/projects/'.

```php
\Sentry\init([
    'dsn' => 'https://<key>@o<orgId>.ingest.sentry.io/<projectId>',
    'prefixes' => [
        '/var/www/',
        '/home/user/projects/',
    ],
]);
```

--------------------------------

### Implement beforeSend callback class

Source: https://docs.sentry.io/platforms/php/guides/laravel/data-management/sensitive-data

Defines the Sentry class with a static beforeSend method that receives an event and returns it, optionally modified or null to discard.

```php
class Sentry
{
    public static function beforeSend(\Sentry\Event $event): ?\Sentry\Event
    {
        return $event;
    }
}
```

--------------------------------

### Configure before_send_check_in callback in Laravel

Source: https://docs.sentry.io/platforms/php/guides/laravel/configuration/filtering

Configure the 'before_send_check_in' option in Laravel to reference a static callback, then implement that callback to modify or discard check-in events. Returning null discards the event; the example discards events whose environment is not 'production'.

```php
'before_send_check_in' => [App\Exceptions\Sentry::class, 'beforeSendCheckIn'],
```

```php
class Sentry
{
    public static function beforeSendCheckIn(\Sentry\Event $event): ?\Sentry\Event
    {
        $checkIn = $event->getCheckIn();
        $checkInEnvironment = $checkIn->getEnvironment();

        if ($checkInEnvironment !== 'production') {
            return null;
        }

        return $event;
    }
}
```

--------------------------------

### Retrieve Current Span and Manage Child Span

Source: https://docs.sentry.io/platforms/php/guides/laravel/tracing/instrumentation/custom-instrumentation

Retrieves the current span, starts a child span, sets it as the current span, and restores the parent span after finishing. Use this to attach spans to an ongoing span and manage the current span context.

```php
$parentSpan = \Sentry\SentrySdk::getCurrentHub()->getSpan();

if ($parentSpan !== null) {
    $context = \Sentry\Tracing\SpanContext::make()
        ->setOp('some_operation');
    $span = $parentSpan->startChild($context);

    // Set the span we just started as the current span
    \Sentry\SentrySdk::getCurrentHub()->setSpan($span);

    // ...

    $span->finish();

    // Restore the span back to the parent span
    \Sentry\SentrySdk::getCurrentHub()->setSpan($parentSpan);
}
```
Tokens:
Raw