Sentry PHP

https://docs.sentry.io/platforms/php/
Admin
Sentry PHP is an SDK that allows developers to integrate Sentry's error monitoring, performance...
Tokens:102,082
Snippets:905
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example SDK debug log output

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

Shows the output produced when the logger option is enabled. It includes messages about installed integrations, transaction start and sampling, profiling, sending transactions, and profile warnings.

```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).
```

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

### Set agent runtime options with --name=value

Source: https://docs.sentry.io/platforms/php/agent

Starts the agent with additional runtime settings using the --name=value form. Example sets upstream-timeout and queue-limit.

```bash
vendor/bin/sentry-agent --upstream-timeout=2.0 --queue-limit=1000
```

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

### Debug logger output example

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

Example output produced by the SDK's debug logger when the logger option is enabled. Shows installed integrations and transaction IDs.

```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]
```

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

### 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.

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

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

### Start the Sentry Agent

Source: https://docs.sentry.io/platforms/php/agent

Starts the agent binary on the host. The agent listens on 127.0.0.1:5148 by default.

```bash
vendor/bin/sentry-agent
```

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

### 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
```

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

### Initialize Sentry PHP SDK with options

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

Passes options to the \Sentry\init() method as an array. The example sets the DSN and max_breadcrumbs.

```php
\Sentry\init([
    'dsn' => 'https://<key>@o<orgId>.ingest.sentry.io/<projectId>',
    'max_breadcrumbs' => 50,
]);
```

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

### Build Excimer from Source

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

Build and install the Excimer PHP extension from source. After installation, 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
```

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

### 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 dependency.

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

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

### Install Sentry PHP SDK with Composer

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

Installs the Sentry PHP SDK via Composer. Requires PHP 7.2 or later and Composer.

```bash
composer require sentry/sentry
```

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

### Install Excimer via PECL

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

Install the Excimer PHP extension using PECL. See the PECL package page for more information.

```bash
pecl install excimer
```

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

### Install sentry/sentry-symfony with Composer

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

Installs the Sentry Symfony bundle via Composer. Requires PHP 7.2 or later and a Sentry account with a project.

```bash
composer require sentry/sentry-symfony
```

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

### Enable Tracing with Sentry PHP SDK

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

Initialize the Sentry PHP SDK with tracing enabled. Profiling requires tracing to be enabled and a transaction to be started.

```php
\Sentry\init([
    'dsn' => 'https://<key>@o<orgId>.ingest.sentry.io/<projectId>',
    'traces_sample_rate' => 1.0,
]);
```

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

### 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
```

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

### Install Excimer via Linux Package Manager

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

Install the Excimer PHP extension using a Linux package manager. See the MediaWiki Excimer page for additional distributions.

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

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

### Basic fingerprint example

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

Sets a static fingerprint for an exception using \Sentry\withScope and $scope->setFingerprint. This overrides the default grouping with a custom string.

```php
try {
    // Run code that possibly throws an exception
} catch (\Throwable $e) {
    \Sentry\withScope(function (\Sentry\State\Scope $scope) use ($e) {
        $scope->setFingerprint(['example-exception-group']);
        \Sentry\captureException($e);
    });
}
```

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

### Configure traces_sampler callable

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 example references a static method on the App\Exceptions\Sentry class.

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

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

### Change agent listen address with --listen

Source: https://docs.sentry.io/platforms/php/agent

Starts the agent with a custom listen address or port by passing the full address to the --listen option.

```bash
vendor/bin/sentry-agent --listen=127.0.0.1:5148
```

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

### Enable tracing with SENTRY_TRACES_SAMPLE_RATE

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

Set the SENTRY_TRACES_SAMPLE_RATE environment variable to a value greater than 0.0 to enable tracing. The example uses 1.0, but you may need to adjust this value in production to prevent quota issues.

```bash
# You may need to adjust this value in your production environment to prevent quota issues
SENTRY_TRACES_SAMPLE_RATE=1.0
```

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

### Retrieve current span, start child, and restore parent

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

Get the current span with `getSpan()`. If it exists, start a child span, set it as current, finish it, and then restore the parent span using `setSpan()`.

```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);
}
```

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

### Retrieve current transaction and start child span

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

Use `getTransaction()` on the current hub to get the active transaction. If it exists, create a child span with `SpanContext::make()` and `setOp('some_operation')`, then start and finish it.

```php
$transaction = \Sentry\SentrySdk::getCurrentHub()->getTransaction();

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

    // ...

    $span->finish();
}
```

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

### Initialize Sentry PHP SDK with DSN and Sampling Rates

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

Initializes the Sentry PHP SDK as early as possible to capture all errors, including startup errors. Includes options for sending default PII, setting a traces sample rate, and setting a profiles sample rate relative to traces_sample_rate. To receive stack trace arguments, set zend.exception_ignore_args: Off in php.ini.

```php
\Sentry\init([
  'dsn' => 'https://<key>@o<orgId>.ingest.sentry.io/<projectId>',
  // Add request headers, cookies and IP address,
  // see https://docs.sentry.io/platforms/php/data-management/data-collected/ for more info
  'send_default_pii' => true,
  // ___PRODUCT_OPTION_START___ performance
  // Specify a fixed sample rate
  'traces_sample_rate' => 1.0,
  // ___PRODUCT_OPTION_END___ performance
  // ___PRODUCT_OPTION_START___ profiling
  // Set a sampling rate for profiling - this is relative to traces_sample_rate
  'profiles_sample_rate' => 1.0,
  // ___PRODUCT_OPTION_END___ profiling
]);
```

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

### Install sentry/sentry-agent with Composer

Source: https://docs.sentry.io/platforms/php/agent

Installs the sentry/sentry-agent package, which is used to install and run the agent binary. This package can be installed independently of your PHP application.

```bash
composer require sentry/sentry-agent
```

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

### Add Span When Retrieving Data From the Cache

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

Use this snippet to manually instrument cache get operations when auto instrumentation is not supported. It creates a child span with op 'cache.get', sets cache-related data including key and hit status, and finishes the span. Ensure the parent span is not null before starting the child span.

```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);
}
```

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

### Implement the traces_sampler service in PHP

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

The service class must provide a `getTracesSampler()` method returning a callable that accepts a `\Sentry\Tracing\SamplingContext` and returns a sample rate between 0 and 1. The example shows how to inherit parent sampling, drop transactions, and set a default rate.

```php
<?php

namespace App\Service;

class Sentry
{
    public function getTracesSampler(): callable
    {
        return function (\Sentry\Tracing\SamplingContext $context): float {
            if ($context->getParentSampled()) {
                // If the parent transaction (for example a JavaScript front-end)
                // is sampled, also sample the current transaction
                return 1.0;
            }

            if (some_condition()) {
                // Drop this transaction, by setting its sample rate to 0
                return 0;
            }

            // Default sample rate for all other transactions (replaces `traces_sample_rate`)
            return 0.25;
        };
    }
}
```

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

### Configure tracing with traces_sample_rate and traces_sampler in PHP

Source: https://docs.sentry.io/platforms/php/tracing

Enable tracing by setting the 'traces_sample_rate' option to a number between 0 and 1, or provide a custom 'traces_sampler' function. These options are mutually exclusive; if both are set, 'traces_sampler' takes precedence.

```php
\Sentry\init([
    'dsn' => 'https://<key>@o<orgId>.ingest.sentry.io/<projectId>',
    // Specify a fixed sample rate:
    'traces_sample_rate' => 0.2,
    // Or provide a custom sampler:
    'traces_sampler' => function (\Sentry\Tracing\SamplingContext $context): float {
        // return a number between 0 and 1
    },
]);
```

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

### Send metric data with \Sentry\traceMetrics()

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

Use \Sentry\traceMetrics() as the entry point for recording counts, gauges, and distributions after the SDK is initialized. The SDK buffers up to 1000 metric entries at a time and keeps only the most recent 1000 once that limit is reached.

```php
\Sentry\traceMetrics()
```

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

### Wrap a job with withMonitor() for automatic check-ins

Source: https://docs.sentry.io/platforms/php/crons

Use `withMonitor()` to automatically send an in-progress check-in at the start and an ok or error check-in at the end of the callback. Pass a monitor configuration to create or update the monitor from code; the configuration is optional if the monitor already exists.

```php
\Sentry\withMonitor(
    slug: '<monitor-slug>',
    callback: fn () => doSomething(),
    monitorConfig: new \Sentry\MonitorConfig(\Sentry\MonitorSchedule::crontab('0 * * * *')),
);
```

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

### 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,
```

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

### 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
```

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

### Set data attributes when creating a transaction or span

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

Use TransactionContext and SpanContext to set data attributes at creation time. The transaction is started with Sentry\startTransaction, and the span is started as a child of the transaction.

```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);
```

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

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

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

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

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

Use this PHP code to instrument a specific region of your 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 creates and starts a child span for an expensive operation. After the operation, it finishes the span and transaction, which submits the data 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();
```

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

### Set current transaction after starting one

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

Create a transaction with `TransactionContext::make()` and `startTransaction()`, then set it as the current span using `setSpan()` on the hub.

```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 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,
```

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

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

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

Shows how to pass custom data to the sampling context as the second argument to start_transaction. Useful for sensitive or large data not sent with the transaction.

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

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

### Configure agent host and port with setHost and setPort

Source: https://docs.sentry.io/platforms/php/agent

Configures the SDK to use a custom agent address by passing host and port to the builder. Use this when the agent listens on a different address or port.

```php
use Sentry\Agent\Transport\AgentClientBuilder;

\Sentry\init([
    'dsn' => 'https://<key>@o<orgId>.ingest.sentry.io/<projectId>',
    'http_client' => AgentClientBuilder::create()
        ->setHost('127.0.0.1')
        ->setPort(5148)
        ->getClient(),
]);
```

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

### Filter events using EventHint in before_send

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

Use the hint parameter to access the original exception. In this example, the event is dropped when the exception is an instance of MyException.

```php
'before_send' => [App\Exceptions\Sentry::class, 'beforeSend'],
```

```php
class Sentry
{
    public static function beforeSend(\Sentry\Event $event, ?\Sentry\EventHint $hint): ?\Sentry\Event
    {
        // Ignore the event if the original exception is an instance of MyException.
        if ($hint !== null && $hint->exception instanceof MyException) {
            return null;
        }

        return $event;
    }
}
```

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

### Implement the traces_sampler service in PHP

Source: https://docs.sentry.io/platforms/php/guides/symfony/tracing

The service needed for the `traces_sampler` option can be implemented as shown. The `getTracesSampler` method returns a callable that receives a `SamplingContext` and must return a float between 0 and 1.

```php
<?php

namespace App\Service;

class Sentry
{
    public function getTracesSampler(): callable
    {
        return function(\Sentry\Tracing\SamplingContext $context): float {
            // return a number between 0 and 1
        };
    }
}
```

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

### Group errors more aggressively

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

Overwrites Sentry's grouping entirely by omitting {{ default }} from the fingerprint array. This example groups all PDOExceptions under a single fingerprint 'database-connection-error'.

```php
try {
    // Run code that for example throws a PDOException
} catch (\PDOException $e) {
    \Sentry\withScope(function (\Sentry\State\Scope $scope) use ($e) {
        $scope->setFingerprint(['database-connection-error']);
        \Sentry\captureException($e);
    });
}
```

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

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

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

Adds a value of 15.0 to a distribution for page-load times, using a millisecond unit. Distributions support aggregations like p90, min, max, and avg.

```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());
```
Tokens:
Raw