README

A logfmt formatter for Monolog.

Installation

The formatter can be installed using Composer:

$ composer require petert82/monolog-logfmt

Requirements

• PHP 7.4.0 or later.

Usage

Simply set an instance of Petert82\Monolog\Formatter\LogfmtHandler as the formatter for the Handler that you wish to output logfmt formatted logs.

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Petert82\Monolog\Formatter\LogfmtFormatter;

$log = new Logger('name');
$handler = new StreamHandler('php://stdout', Logger::WARNING);
$handler->setFormatter(new LogfmtFormatter());
$log->pushHandler($handler);

$log->addError('Danger! High voltage!', ['voltage' => 9000]);

Running this example would output something like:

ts=2017-11-21T20:02:10+00:00 lvl=ERROR chan=name msg="Danger! High voltage!" voltage=9000

Customisation

By default these keys will be used for the default log fields in the logfmt output:

All of these keys, and the format used for formatting logged DateTimes, can be customised by passing the appropriate parameters to the formatter's constructor. For example:

$tsKey = 'date';
$levelKey = 'level';
$channelKey = 'channel';
$msgKey = 'message';
$dateFormat = 'Ymd-His';
$formatter = new LogfmtFormatter($tsKey, $levelKey, $channelKey, $msgKey, $dateFormat);

Logs formatted using this formatter would look like this:

date=20171119-190000 level=INFO channel=app message=Message

The standard keys can also be excluded from the output by passing an empty string (or null) to the appropriate constructor param. For example, to include only the message:

$formatter = new LogfmtFormatter('', '', '', 'msg');

The formatter's output would now look like this:

msg=Message

Structure Flattening

By default, nested arrays and objects in the log context and extra fields are serialized as JSON strings. If you would prefer to instead flatten such structures into logfmt-compatible key-value pairs, set the $flattenStructures constructor parameter true:

// Default JSON serialization
$formatter = new LogfmtFormatter();
// Produces output like: user={"name":"John","roles":["admin","editor"]}

// With flattening enabled
$formatter = new LogfmtFormatter(
    'ts', 'lvl', 'chan', 'msg',
    DateTime::RFC3339, "\n",
    true // Enable flattening
);
// Outfut now looks like: user_name=John user_roles_0=admin user_roles_1=editor

Development

A Makefile is provided to test the library locally, the only requirement for this is that Docker be installed on your development machine. Simply run make in the project root to execute the test suite.

License

Licensed under the MIT License - see the LICENSE file for details