Sentry integration - Documentation

This package provides an advanced integration between Bref applications and Sentry monitoring (opens in a new tab):

  • Trace cold starts in performance tracing
  • Capture exceptions and trace event handlers using the function runtime (like EventBridge, SQS, S3…)
  • Trace AWS SDK calls in performance tracing

Check out the documentation below for screenshots and more details.


Before getting started, make sure you have set up Sentry in your application (documentation for PHP (opens in a new tab), for Laravel (opens in a new tab) or for Symfony (opens in a new tab)).

When configuring Sentry, you can set the Sentry "DSN" in a .env file (if you framework supports it) or in an environment variable in serverless.yml.

1. Enable

The bref/sentry-integration package is distributed via (opens in a new tab), the alternative to (opens in a new tab) for private packages (provided by the Composer team). To install the package, you will need:

  • a token
  • a sub-repository URL

You will receive both after purchasing a license on the Bref website.

Once you have your license, enable in your composer.json by adding the sub-repository URL:

    "repositories": [
        {"type": "composer", "url": "<your-org-name>/"}

Make sure to replace the URL with the one provided with the license you purchased.

Next, configure the token (provided with the license you purchased).

  • On developer machines, you can run the following command:

    composer config --global --auth token <your-token>
  • In CI/CD environments, you can set the COMPOSER_AUTH environment variable:

    COMPOSER_AUTH='{"http-basic": {"": {"username": "token", "password": "<token-here>"}}}'

The token is for your whole organization, you can share it with your team.

2. Install the package

You can now install the package via Composer:

composer require bref/sentry-integration

If you use Laravel, the Laravel integration will be automatically set up via a service provider.

If you use Symfony, you will need to manually register the bundle in config/bundles.php:

return [
    // ...
    Bref\Sentry\Symfony\BrefSentryBundle::class => ['all' => true],


Send me a Slack message or an email ( if you have any trouble, I can help you set it up!


Event-driven PHP runtime

When using the event-driven function runtime, event handlers will be automatically traced in Sentry:

  • Exceptions will be captured and reported to Sentry
  • Event handlers will be traced in performance tracing

This is done automatically and will work for all event handlers, for example EventBridge, SQS, S3, SNS, etc.

Here is an example of an EventBridge invocation captured in performance tracing:

EventBridge invocation in Sentry

Advanced metadata and tags will also be captured on each transaction, allowing to better debug any issue. For example:

Cold starts tracing

Cold starts are automatically traced when using Laravel or Symfony, there is nothing additional to set up.

Cold starts will appear in transactions in Sentry performance tracing (named lambda.cold-start), along with a sub-span for the Bref initialization (bref.startup). For example:

Cold start in Sentry

Note: because of technical limitation, the cold start span doesn't include the exact total time it takes for the AWS Lambda instance to boot (a few hundred milliseconds are missing).

Bref startup tracing

When using the event-driven PHP runtime, Bref might restart the PHP process between invocations (when not using BREF_LOOP_MAX). This is not a full Lambda cold start, but a Bref process restart. This is traced in Sentry (bref.startup), however it is not part of the main transaction. Indeed, the restart happens after the Lambda invocation has completed, so it is not part of the HTTP response time.

This is why it is tracked as a separate "sub-transaction" in Sentry, named bref.startup:

Bref re-initialization in Sentry

Since it is a child of the main transaction, they are part of the same distributed trace and can be viewed together:

Bref re-initialization in Sentry

Tracing AWS SDK calls

You can trace AWS SDK calls in Sentry performance tracing. This is useful to see which calls are slow and might be the cause of performance issues.

Trace AWS SDK calls by calling AwsSdkTracer::trace($client) after creating an AWS SDK client. For example:

use Aws\EventBridge\EventBridgeClient;
use Bref\Sentry\AwsSdk\AwsSdkTracer;
$client = new EventBridgeClient([
    // ...

This will add a span to the current transaction for each AWS SDK call. Here is an example where a SQS job handler sends a message to EventBridge:

AWS SDK call in Sentry