Laravel Options

Learn about Sentry's integration with Laravel and its options for logs, breadcrumbs, and tracing.

Most configuration for Laravel is done in your .env file. You can also add additional config options to your config/sentry.php file.

To send Laravel logs to Sentry, enable logs in your .env file or in config/sentry.php. If a single request, command, or job can produce a high volume of logs, SENTRY_LOG_FLUSH_THRESHOLD lets the SDK send partial log batches before it finishes.

For setup and usage details, see the Laravel logs docs.

This configures the base SDK enable_logs option.

.env
Copied
SENTRY_LOG_FLUSH_THRESHOLD=5

When this is unset, the SDK does not auto flush buffered logs. Set it to a positive integer to flush as soon as that many logs have been buffered.

The Laravel SDK will create breadcrumbs for certain events occurring in the framework, the capture of this information can be configured using the following environment variables:

config/sentry.php
Copied
'breadcrumbs' => [
    // Capture Laravel logs as breadcrumbs
    'logs' => env('SENTRY_BREADCRUMBS_LOGS_ENABLED', true),

    // Capture Laravel cache events (hits, writes etc.) as breadcrumbs
    'cache' => env('SENTRY_BREADCRUMBS_CACHE_ENABLED', true),

    // Capture Livewire components like routes as breadcrumbs
    'livewire' => env('SENTRY_BREADCRUMBS_LIVEWIRE_ENABLED', true),

    // Capture SQL queries as breadcrumbs
    'sql_queries' => env('SENTRY_BREADCRUMBS_SQL_QUERIES_ENABLED', true),

    // Capture SQL query bindings (parameters) in SQL query breadcrumbs
    'sql_bindings' => env('SENTRY_BREADCRUMBS_SQL_BINDINGS_ENABLED', false),

    // Capture queue job information as breadcrumbs
    'queue_info' => env('SENTRY_BREADCRUMBS_QUEUE_INFO_ENABLED', true),

    // Capture command information as breadcrumbs
    'command_info' => env('SENTRY_BREADCRUMBS_COMMAND_JOBS_ENABLED', true),

    // Capture HTTP client request information as breadcrumbs
    'http_client_requests' => env('SENTRY_BREADCRUMBS_HTTP_CLIENT_REQUESTS_ENABLED', true),

    // Capture send notifications as breadcrumbs
    'notifications' => env('SENTRY_BREADCRUMBS_NOTIFICATIONS_ENABLED', true),
],

To enable tracing, set SENTRY_TRACES_SAMPLE_RATE to a value greater than 0.0:

.env
Copied
# You may need to adjust this value in your production environment to prevent quota issues
SENTRY_TRACES_SAMPLE_RATE=1.0

If you want more control over which requests are monitored, use the traces_sampler option as a callable:

config/sentry.php
Copied
'traces_sampler' => [App\Exceptions\Sentry::class, 'tracesSampler'],

Then implement the sampler:

app/Exceptions/Sentry.php
Copied
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;
    }
}

If your application processes a large number of queued jobs, tracing every job at the same rate as your HTTP requests can create more transaction volume than you need. Use the Sentry\Laravel\Jobs\Middleware\SentryTracesSampleRate job middleware to keep fewer traces for specific jobs while leaving your global tracing configuration unchanged.

This middleware only affects queue job transactions, so tracing.queue_job_transactions must stay enabled. It can only lower the sample rate for jobs that were already sampled by your global traces_sample_rate or traces_sampler; it does not upsample jobs that were excluded earlier.

app/Jobs/ProcessPodcast.php
Copied
<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Sentry\Laravel\Jobs\Middleware\SentryTracesSampleRate;

class ProcessPodcast implements ShouldQueue
{
    public function middleware(): array
    {
        return [
            new SentryTracesSampleRate(0.1), // Keep 10% of already-sampled traces for this job
        ];
    }
}

This is useful for high-volume or lower-priority background work, such as imports, notifications, fan-out jobs, or other queue consumers where you still want representative performance data without sending every transaction.

You can also configure which parts of your application are traced automatically. These settings have no effect if SENTRY_TRACES_SAMPLE_RATE is set to 0.0 or if the environment variable is not set:

config/sentry.php
Copied
'tracing' => [
    // Trace queue jobs as their own transactions (this enables tracing for queue jobs)
    'queue_job_transactions' => env('SENTRY_TRACE_QUEUE_ENABLED', true),

    // Capture queue jobs as spans when executed on the sync driver
    'queue_jobs' => env('SENTRY_TRACE_QUEUE_JOBS_ENABLED', true),

    // Capture SQL queries as spans
    'sql_queries' => env('SENTRY_TRACE_SQL_QUERIES_ENABLED', true),

    // Capture SQL query bindings (parameters) in SQL query spans
    'sql_bindings' => env('SENTRY_TRACE_SQL_BINDINGS_ENABLED', false),

    // Capture where the SQL query originated from on the SQL query spans
    'sql_origin' => env('SENTRY_TRACE_SQL_ORIGIN_ENABLED', true),

    // Define a threshold in milliseconds for SQL queries to resolve their origin
    'sql_origin_threshold_ms' => env('SENTRY_TRACE_SQL_ORIGIN_THRESHOLD_MS', 100),

    // Capture views rendered as spans
    'views' => env('SENTRY_TRACE_VIEWS_ENABLED', true),

    // Capture Livewire components as spans
    'livewire' => env('SENTRY_TRACE_LIVEWIRE_ENABLED', true),

    // Capture HTTP client requests as spans
    'http_client_requests' => env('SENTRY_TRACE_HTTP_CLIENT_REQUESTS_ENABLED', true),

    // Capture Laravel cache events (hits, writes etc.) as spans
    'cache' => env('SENTRY_TRACE_CACHE_ENABLED', true),

    // Capture Redis operations as spans (this enables Redis events in Laravel)
    'redis_commands' => env('SENTRY_TRACE_REDIS_COMMANDS', false),

    // Capture where the Redis command originated from on the Redis command spans
    'redis_origin' => env('SENTRY_TRACE_REDIS_ORIGIN_ENABLED', true),

    // Capture send notifications as spans
    'notifications' => env('SENTRY_TRACE_NOTIFICATIONS_ENABLED', true),

    // Enable tracing for requests without a matching route (404's)
    'missing_routes' => env('SENTRY_TRACE_MISSING_ROUTES_ENABLED', false),

    // Configures if the performance trace should continue after the response has been sent to the user until the application terminates
    // This is required to capture any spans that are created after the response has been sent like queue jobs dispatched using `dispatch(...)->afterResponse()` for example
    'continue_after_response' => env('SENTRY_TRACE_CONTINUE_AFTER_RESPONSE', true),

    // Capture AI agent interactions as spans (requires laravel/ai)
    'gen_ai' => env('SENTRY_TRACE_GEN_AI_ENABLED', true),

    // Capture AI invoke_agent spans
    'gen_ai_invoke_agent' => env('SENTRY_TRACE_GEN_AI_INVOKE_AGENT_ENABLED', true),

    // Capture AI chat spans
    'gen_ai_chat' => env('SENTRY_TRACE_GEN_AI_CHAT_ENABLED', true),

    // Capture AI execute_tool spans
    'gen_ai_execute_tool' => env('SENTRY_TRACE_GEN_AI_EXECUTE_TOOL_ENABLED', true),

    // Capture AI embeddings spans
    'gen_ai_embeddings' => env('SENTRY_TRACE_GEN_AI_EMBEDDINGS_ENABLED', true),

    // Enable the tracing integrations supplied by Sentry (recommended)
    'default_integrations' => env('SENTRY_TRACE_DEFAULT_INTEGRATIONS_ENABLED', true),
],

The gen_ai option is the master switch for AI Agent Monitoring. The more specific gen_ai_* options let you disable individual AI span types while keeping the rest of AI monitoring enabled.

Previous
Configuration
Next
Options
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").