README

Sentry integration for Flow 8.x and 9.x

This Flow package allows you to automate reporting of errors to Sentry

Key Features

This package makes sure that exceptions and errors logged by the Flow framework also end up in Sentry. This client takes some extra care to clean up paths and filenames of stacktraces so you get good overview while looking at an issue in the Sentry UI.

Installation

The Sentry integration is installed as a regular Flow package via Composer. For your existing project, simply include flownative/sentry into the dependencies of your Flow or Neos distribution:

$ composer require flownative/sentry

Configuration

You need to at least specify a DSN to be used as a logging target. Apart from that, you can configure the Sentry environment and release. These options can either be set in the Flow settings or, more conveniently, by setting the respective environment variables.

Flownative:
  Sentry:
    dsn: "%env:SENTRY_DSN%"
    environment: "%env:SENTRY_ENVIRONMENT%"
    release: "%env:SENTRY_RELEASE%"

The error sample rate of Sentry can be set using

Flownative:
  Sentry:
    sampleRate: 1

The default is 1 – 100% percent of all errors are sampled.

Throwables (that includes exceptions and runtime errors) are logged as Sentry events. You may specify a list of exceptions which should not be recorded. If such an exception is thrown, it will only be logged as a "notice".

Flownative:
  Sentry:
    capture:
      excludeExceptionTypes:
        - 'Neos\Flow\Mvc\Controller\Exception\InvalidControllerException'

If an ignored exception is handled by this Sentry client, it is logged similar to the following message:

… NOTICE Exception 12345: The exception message (Ref: 202004161706040c28ae | Sentry: ignored)

Additional Data

Exceptions declared in an application can optionally implement WithAdditionalDataInterface provided by this package. If they do, the array returned by getAdditionalData() will be visible in the "additional data" section in Sentry.

Note that the array must only contain values of simple types, such as strings, booleans or integers.

Testing the Client

This package provides a command controller which allows you to log a test message and a test exception.

Run the following command in your terminal to test your configuration:

./flow sentry:test
Testing Sentry setup …
Using the following configuration:
+-------------+------------------------------------------------------------+
| Option      | Value                                                      |
+-------------+------------------------------------------------------------+
| DSN         | https://abc123456789abcdef1234567890ab@sentry.io/1234567 |
| Environment | development                                                |
| Release     | dev                                                        |
| Server Name | test_container                                             |
| Sample Rate | 1                                                          |
+-------------+------------------------------------------------------------+
An informational message was sent to Sentry Event ID: #587abc123457abcd8f873b4212345678

This command will now throw an exception for testing purposes.

Test exception in SentryCommandController

  Type: Flownative\Sentry\Exception\SentryClientTestException
  Code: 1614759519
  File: Data/Temporary/Development/SubContextBeach/SubContextInstance/Cache/Code/Fl
        ow_Object_Classes/Flownative_Sentry_Command_SentryCommandController.php
  Line: 79

Nested exception:
Test "previous" exception thrown by the SentryCommandController

  Type: RuntimeException
  Code: 1614759554
  File: Data/Temporary/Development/SubContextBeach/SubContextInstance/Cache/Code/Fl
        ow_Object_Classes/Flownative_Sentry_Command_SentryCommandController.php
  Line: 78

Open Data/Logs/Exceptions/2021030308325919ecbf.txt for a full stack trace.

flownative / sentry

Maintainers

Details