NAME

Log::Log4perl::OpenTracing - inject logs with OpenTracing SpanContext

VERSION

This is documentation for version 'v0.1.2'

SYNOPSIS

    use Log::Log4perl;
    use Log::Log4perl::OpenTracing;
    
    my $config = q{
        log4perl.rootLogger           = TRACE, json
        log4perl.appender.json        = Log::Log4perl::Appender::File
        log4perl.appender.json.layout = Log::Log4perl::Layout::JSON::Readable
        log4perl.appender.json.layout.field.message  = %m{chomp}
        log4perl.appender.json.layout.field.time     = %d
        log4perl.appender.json.layout.field.trace-id = %O{opentracing.trace_id}
        log4perl.appender.json.layout.field.span-id  = %O{opentracing.span_id}
        log4perl.appender.json.layout.canonical      = 1
        log4perl.appender.json.layout.first_fields   = time, trace-id, span-id
    };
    
    Log::Log4perl::init( \$config );

DESCRIPTION

This module bridges the gap between Logging and OpenTracing. Some tracing backends are capable to correlate log-messages with spans and traces. This could be achieved by adding the span-id and the trace-id to the logfiles.

This module introduces a new %O (capital letter 'O') placeholder that can be used with PatternLayouts.

The information that is availabale, depends on the implementation specific inject_context method for a hash reference. Since OpenTracing has no control on what data is being exposed from that inject_context method, nor what keys are used, or any data structures (like baggage_items), this module uses a 'dotted' key syntax for nested data. Check with the specific implementation for what data is injected.

CAVEAT

This module uses Hash::Fold to flatten the data structure that come from inject_context. That flettening may potentially lead to issues where data structures might lead to the same 'flattened' key if one would forge a structure that already has a . (dot) in its keys.

SEE ALSO

OpenTracing::Interface::Tracer

A role that defines the Tracer interface.

Log::Log4perl

Log4j implementation for Perl

AUTHOR

Theo van Hoesel <tvanhoesel@perceptyx.com>

COPYRIGHT AND LICENSE

'Log::Log4perl::OpenTracing' is Copyright (C) 2020, Perceptyx Inc

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This package is distributed in the hope that it will be useful, but it is provided "as is" and without any express or implied warranties.

For details, see the full text of the license in the file LICENSE.