/monolog-sentry-bundle

Improves Monolog and especially Sentry logs quality by adding username, parsed user-agent and custom tags - for example server name, Symfony version, commit hash and many many more - to make logs easier to read and analyze :)

Primary LanguagePHPMIT LicenseMIT

Monolog Sentry Bundle

Latest Stable Version Build Status Coverage Status Scrutinizer Code Quality SensioLabsInsight License FOSSA Status

Bundle for appending useful data to Monolog log records like username, parsed user-agent header, host name, Symfony version, commit hash and a lot more - you can provide custom tags to be added to all your logs.

Installation

Install bundle with composer require dziki/monolog-sentry-bundle command.

TL;DR

Comparison of exactly same error handled by default monolog raven handler with sentry/sentry package client with bundle turned off and on with some basic config. As you can see - after turning bundle on - browser, user, breadcrumbs and some valuable tags showed up, making your error logs much easier to read.

Before

before

After

after

Enable the Bundle

Add entry to config/bundles.php:

return [
    // ...
    Dziki\MonologSentryBundle\MonologSentryBundle::class => ['all' => true],
];

or to app/AppKernel.php

<?php // app/AppKernel.php

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Dziki\MonologSentryBundle\MonologSentryBundle(),
        );
        // ...
    }
    // ...
}

Configuration

Default configuration looks like that:

monolog_sentry:
    user_context: true # append username from TokenStorage to log
    user_agent_parser: phpuseragent # parse browser name, version and platform from user agent

You can turn off logging user context and/or parsing browser by setting any of this values to false. Parsing user agent takes about 0.1ms (up to 1ms using native parser) for every request, so...

Caching once parsed User Agents

Caching is supported when service implementing Psr\SimpleCache\CacheInterface is provided under cache config entry. Starting from version 4.1 of Symfony there is default simple cache service cache.app.simple, in previous versions you need to define own service:

monolog_sentry:
    cache: cache.app.simple # service implementing "Psr\SimpleCache\CacheInterface" interface

Custom tags

You can extend amount of logged data by adding custom tags. For example, for logging Symfony version, setting useful Sentry environment and server name you should modify config to this:

monolog_sentry:
    ...
    tags:
        symfony_version: !php/const Symfony\Component\HttpKernel\Kernel::VERSION # useful for regression check
        commit: '%env(APP_REVISION)%' # for example hash of commit, set your own environment variable or parameter
        environment: '%env(SERVER_NAME)%' # Sentry environment discriminator, much more useful than default `prod`

Full basic config

monolog_sentry:
    user_context: true # append username from TokenStorage to log
    user_agent_parser: phpuseragent # parse browser name, version and platform from user agent
    cache: cache.app.simple # service implementing "Psr\SimpleCache\CacheInterface" interface, since SF 4.1
    tags:
        symfony_version: !php/const Symfony\Component\HttpKernel\Kernel::VERSION # useful for regression check
        commit: '%env(APP_REVISION)%' # for example hash of commit, set your own environment variable or parameter
        environment: '%env(SERVER_NAME)%' # Sentry environment discriminator, much more useful than default `prod`

User Agent parser

Bundle supports two parsers:

Configurable through user_agent_parser value, respectively phpuseragent or native. You can also add own, by providing name of service implementing ParserInterface.

Hints

  • Add stop_buffering: false to your fingers_crossed handler to keep low level messages notifications as breadcrumbs:
monolog:
    handlers:
        main:
            type:           fingers_crossed
            action_level:   error
            handler:        buffered
            stop_buffering: false
        sentry:
            type:    raven
            dsn:     '%env(SENTRY_DSN)%'
            level:   info # logs which will be shown as breadcrumbs in Sentry issue
            release: 1.0.0
  • Add Sentry handler release option to monolog config for easy regression seeking:
monolog:
    handlers:
        ...
        sentry:
            ...
            release: '%env(APP_VERSION)%' # version tag or any release ID

License

MonologSentryBundle is released under the MIT license.

FOSSA Status