README

A library for parsing monolog logfiles.

This library is compatible with Monolog 2 and provides parse options for multiline logs and Laravel logfiles.

Installation

Install the library using composer:

composer require devdot/monolog-parser

Basic Usage

Example for parsing a logfile test.log using the default options:

<?php
use Devdot\Monolog\Parser;

// create a new parser bound to the given file
$parser = new Parser('test.log');

// retrieve the log records and print them
$records = $parser->get();
foreach($records as $record) {
    printf('Logged %s at %s with message: %s',
        $record->level,
        $record->datetime->format('Y-m-d H:i:s'),
        $record->message,
    );
}

You can create a new Parser object by using the static function new as well:

<?php
use Devdot\Monolog\Parser;

$records = Parser::new('test.log')->get();

// ...

Documentation

Parser instance

Create new Parser instances:

$parser = new Parser();
$parser = Parser::new(); // equivalent to new Parser()

For parameters, see Method Reference.

Most methods return the Parser instance itself, allowing the calls to be chained in one line as seen in the examples below.

Every Parser is meant to be linked to only one file, however that is not a hard restriction and depends on your usage.

Files and Ready State

The parser has to be provided a filename (or a string, see Parsing) in order to become ready to parse. You can set the filename in the constructor or with setFile. Check, whether a parser is ready with isReady:

$parser = Parser::new();
$parser->setFile('test.log'); // throws FileNotFoundException if file does not exist
$parser->isReady(); // true. The file is ready to be parsed

Parsing

Parsing happens either when parse or get are called. The Parser object will store the results and return them from cache when get is called unless parse is called again directly or clear is called.

$parser = Parser::new()->setFile('test.log');
$records = $parser->parse()->get();
$records = $parser->get(); // this will return the records from cache
$records = $parser->parse()->get(); // this will re-parse the file

Clear the cached records:

$parser = Parser::new()->setFile('test.log');
$records = $parser->get(); // this will parse the file
$records = $parser->clear()->get(); // this will re-parse the file
$records = $parser->get(false); // this will re-parse the file

Parse a string instead of a file:

$parser = new Parser();
$records = $parser->parse('[2023-01-01] test.DEBUG: message')->get();

Log Records

The log records are returned as a Log object by get. The Log is a readonly array containing the records of type LogRecord. These objects are readonly too and can be accessed like this:

$records = Parser::new('test.log')->get();
$first = $records[0]; // access the records just like an array
foreach($records as $record) {
    $record->datetime; // object of type DateTimeImmutable
    $record->channel; // string
    $record->message; // string
    $record->context; // object, empty array by default (decoded JSON)
    $record->extra; // object or array, empty array by default (decoded JSON)
}

You may also access the LogRecord properties like array keys: $record['datetime'] instead of $record->datetime.

For reference, Monolog log records look like this:

[2020-01-01 18:00:00] debugging.WARNING: this is a message {"foo":"bar"} ["baz","bud"]
 ----- datetime ----  -channel- -level-  ---- message ---- -- context -- --- extra ---

Patterns

Besides the default pattern, there are other patterns provided as listed below. Patterns have to have named subpatterns to work correctly. You can set any pattern like this:

// use provided patterns
$parser = Parser::new()->setPattern(Parser::PATTERN_LARAVEL);
// or build your regex with named subpatterns like this:
$parser->setPattern('/^\[(?<datetime>.*?)\] (?<message>.*?) \| (?<channel>\w+).(?<level>\w+)$/m');

PATTERN_MONOLOG2 (default): will parse most configurations of Monolog's LineFormatter pattern.
PATTERN_MONOLOG2_MULTILINE: will parse most configurations of Monolog's LineFormatter with multiline support.
PATTERN_LARAVEL: will parse Laravel logfiles that were created with the Monolog configuration that is provided by Laravel.

Parsing Options

The parsing process can be modified with the following options:

The options may be set like this:

$parser = Parser::new();
// set a single option
$parser->setOptions(Parser::OPTION_SORT_DATETIME);
// set multiple options
$parser->setOptions(Parser::OPTION_SKIP_EXCEPTIONS + Parser::OPTION_JSON_AS_TEXT);
// reset the parser to default settings
$parser->setOptions(Parser::OPTION_NONE);

Exceptions

Monolog-Parser will throw exceptions as listed below.

FileNotFoundException: Whenever a file is accessed that does not exist, this exception will be thrown. Note: this will happen, when setFile is called with a non-existing file.
ParserNotReadyException: Whenever parse or get are called while the parser is not ready (isReady() is false), this exception will be thrown. This is not the case if parse is provided with a string or when a parsing option prevents exceptions.
LogParsingException: Whenever the parsing of a logfile or log record fails, this exception will be thrown. See Limits and failing logs

Limits and failing logs

If reading your logs fails, please make sure the logs are generated correctly and not listed on the list below. If files generated by the default LineFormatter pattern of Monolog fail to be parsed, please let me know and submit an issue. If you are using non-default patterns, I would still be interested to provide parse patterns if they are commonly used.

Log files or records that can (currently) not be parsed by Monolog-Parser:

Invalid JSON in the context/extra section of a log entry (will throw a LogParsingException).
Valid JSON with misleading closing brackets like all listed in this testfile. However, the examples in this other testfile will not throw an error.

Method Reference

If not stated otherwise, methods return the object $this.

About

Requirements

Monolog-Parser works with PHP 8.2 or above.
Monolog-Parser does not require any Monolog package.

License

Monolog-Parser is licensed under the MIT License. See the LICENSE file for details.

Acknowledgements

This library was inspired by ddtraceweb's monolog parser and haruncpi's laravel log reader.

devdot / monolog-parser

Maintainers

Details