FlightRecorder - Structured Logging
Logging for Distributed Systems
package main;
use FlightRecorder;
my $f = FlightRecorder->new(
auto => undef
);
# $f->begin('try');
# $f->debug('something happened');
# $f->end;
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.
This package integrates behaviors from:
This package uses type constraints from:
This package has the following attributes:
auto(Maybe[FileHandle])
This attribute is read-only, accepts (Maybe[FileHandle])
values, and is optional.
format(Str)
This attribute is read-write, accepts (Str)
values, and is optional.
head(Str)
This attribute is read-only, accepts (Str)
values, and is optional.
item(HashRef)
This attribute is read-only, accepts (HashRef)
values, and is optional.
level(Enum[qw(debug info warn error fatal)])
This attribute is read-only, accepts (Enum[qw(debug info warn error fatal)])
values, and is optional.
logs(ArrayRef[HashRef])
This attribute is read-only, accepts (ArrayRef[HashRef])
values, and is optional.
refs(HashRef)
This attribute is read-only, accepts (HashRef)
values, and is optional.
This package implements the following methods:
begin(Str $label) : Object
The begin method creates and logs a new context.
-
begin example #1
# given: synopsis $f->begin('test')
branch(Str $label) : Object
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 example #1
# given: synopsis $f->begin('test')->branch('next')
count(Maybe[Str] $level) : Int
The count method returns the total number of log entries, or the number of log entries matching the log level specified.
-
count example #1
# given: synopsis $f->begin('try')->debug('something happened')->end; $f->count;
-
count example #2
# given: synopsis $f->info('something happened'); $f->count('info');
-
count example #3
# given: synopsis $f->fatal('something happened'); $f->count('fatal');
data(HashRef[Str] $data) : Object
The data method associates arbitrary metadata with the last event.
-
data example #1
# given: synopsis $f->debug('something happened')->data({ error => 'unknown at ./example line 10' });
debug(Str @message) : Object
The debug method logs a debug
level event with context.
-
debug example #1
# given: synopsis $f->debug('something happened')
end() : Object
The end method logs the end of the current context.
-
end example #1
# given: synopsis $f->begin('main')->end
error(Str @message) : Object
The error method logs an error
level event with context.
-
error example #1
# given: synopsis $f->error('something happened')
fatal(Str @message) : Object
The fatal method logs a fatal
level event with context.
-
fatal example #1
# given: synopsis $f->fatal('something happened')
info(Str @message) : Object
The info method logs an info
level event with context.
-
info example #1
# given: synopsis $f->info('something happened')
output(FileHandle $handle) : Str
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 example #1
# given: synopsis $f->begin('test')->output
-
output example #2
package main; use FlightRecorder; my $f = FlightRecorder->new; $f->begin('try'); # $f->output $f->debug('something happened'); # $f->output $f->end; # $f->output
report(Str $name, Str $level) : Object
The report method loads and returns the specified report plugin.
-
report example #1
# given: synopsis $f->report('verbose')
-
report example #2
# given: synopsis $f->report('succinct', 'fatal')
reset() : Object
The reset method returns an object to its initial state.
-
reset example #1
# given: synopsis $f->begin('try')->debug('something happened')->end; $f->reset;
-
reset example #2
# given: synopsis $f->begin('try')->debug('something happened')->end; $f->branch('main')->switch('try')->fatal('something happened')->end; $f->reset;
serialize() : HashRef
The serialize method normalizes and serializes the event log and returns it as
a hashref
.
-
serialize example #1
# given: synopsis $f->begin('main')->serialize
simple() : Object
The simple method loads and returns the FlightRecorder::Plugin::ReportSimple report plugin.
-
simple example #1
# given: synopsis $f->simple
succinct() : Object
The succinct method loads and returns the FlightRecorder::Plugin::ReportSuccinct report plugin.
-
succinct example #1
# given: synopsis $f->succinct
switch(Str $name) : Object
The switch method finds and sets the current context based on the name provided.
-
switch example #1
# given: synopsis $f->begin('main')->begin('test')->switch('main')
verbose() : Object
The verbose method loads and returns the FlightRecorder::Plugin::ReportVerbose report plugin.
-
verbose example #1
# given: synopsis $f->verbose
warn(Str @message) : Object
The warn method logs a warn
level event with context.
-
warn example #1
# given: synopsis $f->warn('something happened')
Al Newkirk, awncorp@cpan.org
Copyright (C) 2011-2019, Al Newkirk, et al.
This is free software; you can redistribute it and/or modify it under the terms of the The Apache License, Version 2.0, as elucidated in the "license file".