networkteam/sentry-client

A Sentry client for TYPO3. It forwards errors and exceptions to Sentry - https://sentry.io/

5.2.0 2024-09-04 20:01 UTC

Requires

• php: ^8.0
• sentry/sentry: ^4.6
• typo3/cms-backend: ^11.0 || ^12.0 || ^13.0
• typo3/cms-core: ^11.0 || ^12.0 || ^13.0
• typo3/cms-frontend: ^11.0 || ^12.0 || ^13.0

Requires (Dev)

• saschaegerer/phpstan-typo3: ^1.1

GPL-2.0-or-later

• Christoph Lehmann

• extension
• monitoring
• sentry
• typo3

README

TYPO3 logs error messages and exceptions to logfiles and the backend log module. This extension sends them to Sentry, a SaaS/self-hosted application which aggregates them and informs you by mail. In Sentry you see a error messages with additional information like stacktrace, HTTP headers and submitted request/form data.

Technical decisions

Exceptions through database outages (imagine a mysql server restart) should not be reported, so the db connection is checked before. Exceptions may be excluded via regexp on their message (won't fix this error => exclude it). TYPO3 throws a lot of PHP Notices and they are not really interesting in production, they are excluded by default.

Installation

$ composer require networkteam/sentry-client

The TER version will not receive updates anymore. Feel free to send us a crate of beer and we will make a new TER release.

Configuration

File: system/settings.php or system/additional.php

Register the exception handlers.

$GLOBALS['TYPO3_CONF_VARS']['SYS']['productionExceptionHandler'] = Networkteam\SentryClient\ProductionExceptionHandler::class;
$GLOBALS['TYPO3_CONF_VARS']['SYS']['debugExceptionHandler'] = Networkteam\SentryClient\DebugExceptionHandler::class;

The DebugExceptionHandler is also used in production environment when SYS/displayErrors is enabled and your IP matches SYS/devIPmask.

Optional: Forward non-exceptional errors to Sentry, that normally are logged only. Consider using LogLevel::WARN

$GLOBALS['TYPO3_CONF_VARS']['LOG']['writerConfiguration'] = [
    \TYPO3\CMS\Core\Log\LogLevel::ERROR => [
        \Networkteam\SentryClient\SentryLogWriter::class => [],
    ],
];

Optional: Set sentry/sentry options (https://docs.sentry.io/platforms/php/configuration/options/)

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['sentry_client']['options']['server_name'] = 'web3';

Environment variables

Since Sentry SDK 2.x there are environment variables which can be used, for example in a .htaccess file:

SetEnv SENTRY_DSN http://[e-mail]/project-id
SetEnv SENTRY_RELEASE 1.0.7
SetEnv SENTRY_ENVIRONMENT Staging

Feature Toggles

• Ignore database connection errors (they should better be handled by a monitoring system)
• Report user information: Select one of none | userid
• Ignore exception message regular expression
• Ignore LogWriter Components

How to test if the extension works?

page = PAGE
page.20 = USER
page.20 {
  userFunc = Networkteam\SentryClient\Client->captureException
}

This triggers an error that will be reported.

Request ID

If the web server has set a request ID header X-Request-Id, this is transmitted as a tag to trace errors to logs.

Issue tracker

This extension is managed on GitHub. Feel free to get in touch at https://github.com/networkteam/sentry_client

Help

There is a Slack channel #ext-sentry_client

Changelog

5.1.0

• Use sentry/sentry ^4.6

5.0.0

• New option "disableDatabaseLogging": When enabled, exceptions are not written to database table sys_log
• Introduce Sentry Integrations
• Allow passing sentry/sentry options via EXTCONF
• Ignore exceptions, that are ignore in TYPO3 core
• Use sentry/sentry instead of sentry/sdk (Thanks to @derhansen)
• !!! Option "logWriterLogLevel" removed. LogWriter needs to be configured in system/additional.php
• !!! Option "messageBlacklistRegex" renamed to "ignoreMessageRegex"
• !!! Option "logWriterComponentBlacklist" renamed to "logWriterComponentIgnorelist"
• !!! The old option names still work
• !!! Drop support for TYPO3 v10
• !!! Drop support for non-composer usage

4.2.0

• Add log message interpolation (Thanks to @sascha-egerer)
• Add Fingerprint to log messages
• Deprecated: Usage of DebugExceptionHandler

4.1.0

• Client IP is anonymized with IpAnonymizationUtility::anonymizeIp(). Thanks to @extcode
• Add X-Request-Id as tag. Thanks to @bergo
• Small code optimizations. Thanks to @tlueder and @LeoniePhiline

4.0.0

• Add stacktrace to LogWriter messages for message grouping in Sentry
• Add LogWriter component ignorelist
• Add v11.5 support
• Drop v9.5 support

3.0..3.1

• Add experimental LogWriter
• Remove setting activatePageNotFoundHandling
• Ignore PageNotFoundException by default
• Support TYPO3 proxy setting
• Use sentry/sdk:3.1

2.0..3.0

• Use sentry/sdk:2.0
• Remove setting productionOnly
• Remove setting reportWithDevIP
• Rename setting activatePageNotFoundHandlingActive to activatePageNotFoundHandling
• Report E_ALL ^ E_NOTICE
• Strip project root
• Show event id in FE