README

Introduction

This package provides a Monolog handler and formatter for log data delivery to Understand.io.

You may also be interested in our Laravel 4, Laravel 5 or Laravel Lumen service provider handler

Quick start

1. Install package

composer require understand/understand-monolog

1. Add an Understand handler to Monolog

use Monolog\Logger;

// input token from Understand.io
$inputToken = 'ab1cd234-1234-45e6-789f-gh1fa1234567';

// choose a handler, either async or sync (see below)
$understandAsyncHandler = new UnderstandMonolog\Handler\UnderstandAsyncHandler($inputToken); // async handler
$understandSyncHandler = new UnderstandMonolog\Handler\UnderstandSyncHandler($inputToken); // sync handler

$monologLogger = new Logger('name');
$monologLogger->pushHandler($understandAsyncHandler); // or $understandSyncHandler

$monologLogger->addError('first error');

Handlers

UnderstandSyncHandler

The sync handler uses the PHP Curl extension and delivers logs synchronously to Understand.io. This means that if your application generates a large amount of data it could slow down your app.

UnderstandAsyncHandler

We recommend making use of the async handler where possible. It is supported in most systems - the only requirement is that CURL command line tool is installed and functioning correctly. To check whether CURL is available on your system, execute the following command in your console

curl -h

If you see instructions on how to use CURL then your system has the CURL binary installed and you can use the async handler.

Exception encoder

This helper class allows you to serialize PHP exceptions as an array which can be then serialized to json. The main benefit of doing this is that Understand will then be able to parse your logs more intelligently, allowing for better search and filtering capabilities.

$exception = new \DomainException('This is Exception', 123);

$encoder = new \UnderstandMonolog\Encoder\ExceptionEncoder();
$array = $encoder->exceptionToArray($exception);

print_r($array);exit;

//Array
//(
//    [message] => This is Exception
//    [class] => DomainException
//    [code] => 123
//    [file] => /home/vagrant/share/understand-lumen-test/app/Exceptions/Handler.php
//    [line] => 30
//    [stack] => Array
//        (
//            [0] => Array
//                (
//                    [class] => App\Exceptions\Handler
//                    [function] => report
//                    [args] => Array
//                        (
//                            [0] => DomainException
//                        )
//
//                    [type] => method
//                    [file] => /home/vagrant/share/understand-lumen-test/vendor/laravel/lumen-framework/src/Application.php
//                    [line] => 354
// .......... and more

How to use the Exception encoder

use Monolog\Logger;

// input token from Understand.io
$inputToken = 'ab1cd234-1234-45e6-789f-gh1fa1234567';

// choose a handler
$understandAsyncHandler = new UnderstandMonolog\Handler\UnderstandAsyncHandler($inputToken); // async handler

$monologLogger = new Logger('name');
$monologLogger->pushHandler($understandAsyncHandler);

$exception = new \DomainException('This is Exception', 123);

$encoder = new UnderstandMonolog\Encoder\ExceptionEncoder();
$context = $encoder->exceptionToArray($exception);

$monologLogger->addError($exception->getMessage(), $context);

License

The Understand.io Monolog package is open-sourced software licensed under the MIT license