version 1.02
Log::Any::Adapter::JSON - One-line JSON logging of arbitrary structured data
Get a logger and specify the output destination:
use Log::Any '$log'; use Log::Any::Adapter ('JSON', '/path/to/file.log'); # or use Log::Any '$log'; use Log::Any::Adapter; my $handle = ...; # FH, pipe, etc Log::Any::Adapter->set('JSON', $handle);
Log some data:
$log->info('Hello, world'); $log->info('Hello, %s', $name); $log->debug('Blabla', { tracking_id => 42 }); $log->debug('Blorgle', { foo => 'bar' }, [qw/a b c/], 'last thing');
This Log::Any adapter logs formatted messages and arbitrary structured data in a single line of JSON per entry. You must pass a filename or an open handle to which the entries will be printed.
Optionally you may pass an encoding argument which will be used to apply a binmode layer to the output handle. The default encoding is UTF-8.
encoding
binmode
UTF-8
The adapter expects a string and an optional list @items.
@items
If the string has no formatting tokens, it is included in the log entry in the message field as-is.
message
If the string has formatting tokens, @items is checked to verify that the next N values are scalars, where N is the number of tokens in the string. If the number is the same, the string and tokens are combined using sprintf() and the resulting string is included in the log entry in the message field. If the token and value counts don't match, the adapter croaks.
N
sprintf()
After the format processing, the remainder of the items array is processed. It may hold arrayrefs, which are included in a top- level key named list_data; additional scalars, which are pushed into the additional_messages key; and hashrefs. The first hashref encountered has its keys promoted to top-level keys in the log entry, while additional hashrefs are included in a top-level key named hash_data.
items
list_data
additional_messages
hash_data
In addition, the log entry will have the following fields:
time
level
category
$log->debug('a simple message');
Output is a single string with JSON like:
{ "category":"main", "level":"debug", "message":"hello, world", "time":"2021-03-03T17:23:25.73124" }
my $val = "string"; my $num = 2; $log->debug('a formatted %s with %d tokens', $val, $num);
{ "category":"main", "level":"debug", "message":"a formatted string with 2 tokens", "time":"2021-03-03T17:23:25.73124" }
The first hashref encountered has its keys elevated to the top level.
$log->debug('the message', { tracker => 42 });
{ "category":"main", "level":"debug", "message":"the message", "time":"2021-03-03T17:23:25.73124", "tracker":42 }
Reserved key names that may not be used in the first hashref include:
* category * context * level * message * time
$log->debug('the message', { tracker => 42 }, { foo => 'bar'});
{ "category":"main", "hash_data":{ "foo":"bar" }, "level":"debug", "message":"the message", "time":"2021-03-03T17:23:25.73124", "tracker":42 } $log->debug('the message', { tracker => 42 }, {foo => 'bar'}, [1..3]);
{ "category":"main", "hash_data":[ {"foo":"bar"} ], "level":"debug", "list_data":[ [1,2,3] ], "message":"the message", "time":"2021-03-03T17:23:25.73124", "tracker":42 }
Any scalars that are passed that are not consumed as the values of formatting tokens will be included in an additonal_messages key.
additonal_messages
$log->debug('a simple message', 'foo', 'bar');
{ "additional_messages":[ 'foo', 'bar' ], "category":"main", "level":"debug", "message":"hello, world", "time":"2021-03-03T17:23:25.73124" }
Log::Any
Log::Any::Adapter
Nick Tonkin <tonkin@cpan.org>
This software is copyright (c) 2021 by Nick Tonkin.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Log::Any::Adapter::JSON, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Log::Any::Adapter::JSON
CPAN shell
perl -MCPAN -e shell install Log::Any::Adapter::JSON
For more information on module installation, please visit the detailed CPAN module installation guide.