FlightRecorder

Structured Logging

Logging for Distributed Systems

method: begin method: branch method: count method: data method: debug method: end method: error method: fatal method: info method: output method: report method: reset method: serialize method: simple method: succinct method: switch method: verbose method: warn

package main;

use FlightRecorder;

my $f = FlightRecorder->new(
  auto => undef
);

# $f->begin('try');
# $f->debug('something happened');
# $f->end;

Types::Standard

auto: ro, opt, Maybe[FileHandle] head: ro, opt, Str item: ro, opt, HashRef refs: ro, opt, HashRef level: ro, opt, Enum[qw(debug info warn error fatal)] logs: ro, opt, ArrayRef[HashRef] format: rw, opt, Str

Data::Object::Role::Pluggable Data::Object::Role::Throwable

This package provides a simple mechanism for logging events with context, serializing and distributing the event logs, and producing a transcript of activity to provide insight into the behavior of distributed systems.

The begin method creates and logs a new context.

begin(Str $label) : Object

=example-1 begin

# given: synopsis

$f->begin('test')

The branch method creates and returns a new FlightRecorder object which shares the event log with the parent object. This method creates a new context when called.

branch(Str $label) : Object

=example-1 branch

# given: synopsis

$f->begin('test')->branch('next')

The count method returns the total number of log entries, or the number of log entries matching the log level specified.

count(Maybe[Str] $level) : Int

=example-1 count

# given: synopsis

$f->begin('try')->debug('something happened')->end;
$f->count;

=example-2 count

# given: synopsis

$f->info('something happened');
$f->count('info');

=example-3 count

# given: synopsis

$f->fatal('something happened');
$f->count('fatal');

The data method associates arbitrary metadata with the last event.

data(HashRef[Str] $data) : Object

=example-1 data

# given: synopsis

$f->debug('something happened')->data({
  error => 'unknown at ./example line 10'
});

The debug method logs a debug level event with context.

debug(Str @message) : Object

=example-1 debug

# given: synopsis

$f->debug('something happened')

The end method logs the end of the current context.

end() : Object

=example-1 end

# given: synopsis

$f->begin('main')->end

The error method logs an error level event with context.

error(Str @message) : Object

=example-1 error

# given: synopsis

$f->error('something happened')

The fatal method logs a fatal level event with context.

fatal(Str @message) : Object

=example-1 fatal

# given: synopsis

$f->fatal('something happened')

The info method logs an info level event with context.

info(Str @message) : Object

=example-1 info

# given: synopsis

$f->info('something happened')

The output method outputs the last event using the format defined in the format attribute. This method is called automatically after each log-event if the auto attribute is set, which is by default set to STDOUT.

output(FileHandle $handle) : Str

=example-1 output

# given: synopsis

$f->begin('test')->output

=example-2 output

package main;

use FlightRecorder;

my $f = FlightRecorder->new;

$f->begin('try');

# $f->output

$f->debug('something happened');

# $f->output

$f->end;

# $f->output

The report method loads and returns the specified report plugin.

report(Str $name, Str $level) : Object

=example-1 report

# given: synopsis

$f->report('verbose')

=example-2 report

# given: synopsis

$f->report('succinct', 'fatal')

The reset method returns an object to its initial state.

reset() : Object

=example-1 reset

# given: synopsis

$f->begin('try')->debug('something happened')->end;
$f->reset;

=example-2 reset

# given: synopsis

$f->begin('try')->debug('something happened')->end;
$f->branch('main')->switch('try')->fatal('something happened')->end;
$f->reset;

The serialize method normalizes and serializes the event log and returns it as a hashref.

serialize() : HashRef

=example-1 serialize

# given: synopsis

$f->begin('main')->serialize

The simple method loads and returns the FlightRecorder::Plugin::ReportSimple report plugin.

simple() : Object

=example-1 simple

# given: synopsis

$f->simple

The succinct method loads and returns the FlightRecorder::Plugin::ReportSuccinct report plugin.

succinct() : Object

=example-1 succinct

# given: synopsis

$f->succinct

The switch method finds and sets the current context based on the name provided.

switch(Str $name) : Object

=example-1 switch

# given: synopsis

$f->begin('main')->begin('test')->switch('main')

The verbose method loads and returns the FlightRecorder::Plugin::ReportVerbose report plugin.

verbose() : Object

=example-1 verbose

# given: synopsis

$f->verbose

The warn method logs a warn level event with context.

warn(Str @message) : Object

=example-1 warn

# given: synopsis

$f->warn('something happened')

cpanm FlightRecorder

perl -MCPAN -e shell
install FlightRecorder