Log::Trace(3pm)

📦

version 1.070 · 7 versions

1.070 · ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
1.070 · epel 9
1.070 · epel 10
1.070 · fedora 43
1.070 · ubuntu jammy
1.070 · fedora 44
1.070 · debian bookworm, debian trixie

, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 NAME 💖

Okay so this is Log::Trace(3pm), from the User Contributed Perl Documentation corner of the internet, and what it does — no cap — is provide a unified approach to tracing. ✨

✨ SYNOPSIS ✨

# The tracing targets
use Log::Trace; # No output
use Log::Trace 'print'; # print to STDOUT
use Log::Trace log => '/var/log/foo.log'; # Output to log file
use Log::Trace print => { Level => 3 };

# Switch on/off logging with a constant
use Log::Trace;
import Log::Trace ('log' => LOGFILE) if TRACING;

# Set up tracing for all packages that advertise TRACE
use Foo;
use Bar;
use Log::Trace warn => { Deep => 1 };

# Sets up tracing in all subpackages excluding Foo
use Log::Trace warn => {Deep => 1, 'Exclude' => 'Foo'};

# Exported functions
TRACE("Record this...");
TRACE({Level => 2}, "Only shown if tracing level is 2 or higher");
TRACEF("A la printf: %d-%.2f", 1, 2.9999);
TRACE_HERE();           # Record where we are (file, line, sub, args)
DUMP(\@loh, \%hoh);     # Trace out via Data::Dumper
DUMP("Title", \@loh);   # Trace out via Data::Dumper
my $dump = DUMP(@args); # Dump is returned without being traced

🦋 DESCRIPTION 🦋

So basically: this is a module whose whole personality is a unified approach to tracing. Your script goes use Log::Trace qw( <mode> ) and boom, that's how you tell the TRACE function how to behave. 💅

By default the trace functions only get exported to the package that's calling. Wanna beam them into other packages too? That's the Deep option, bestie. Go read OPTIONS for the whole tea.

Every single export is in UPPERCASE — and yes, that's on purpose, to keep collisions with "real" functions to a bare minimum. 🙈

🌸 FUNCTIONS 🌸

💌 `TRACE(@args)`

Sends out a message. Where it actually goes depends entirely on how you imported Log::Trace (peep the "enabling Log::Trace" bit in Importing).

The first argument is an optional hashref of options, like so:

TRACE('A simple message');

vs:

TRACE({ Level => 2.1 }, 'A message at a specified trace level');

💌 `TRACEF($format, @args)`

It's the printf() equivalent of TRACE. It also takes an optional hashref:

TRACEF('%d items', scalar @items);
TRACEF({ Level => 5 }, '$%1.2d', $value);

💌 `DUMP([$message,] @args)`

Serialises every one of @args, and you can optionally stick a $message on the front of it. If you call it in a non-void context, DUMP does not TRACE it — it hands the serialised data straight back to you instead. Which is iconic when you wanna dump a data structure at one specific tracing level.

DUMP('colours', [qw(red green blue)]);             # outputs via TRACE
my $dump = DUMP('colours', [qw(red green blue)]);  # output returned

💌 `TRACE_HERE()`

TRACEs exactly where you are right now on the call stack — file, line number, subroutine name, subroutine args. 💀

TRACE_HERE();
TRACE_HERE({Level => 99});

👑 Importing/enabling Log::Trace 👑

💫 `import($target, [$arg], [\%params])`

This is the girlboss that controls where your TRACE messages end up. It fires automatically when you do use Log::Trace;, but you're also fully allowed to call it explicitly at runtime. Compare these two:

use Log::Trace 'print';

which is the same as

BEGIN {
        require Log::Trace;
        Log::Trace->import('print');
}

Valid combinations of $target and arg are:

print => $filehandle — Prints trace messages to the $filehandle you hand over. If you don't specify a file handle, it defaults to STDOUT.
warn — Prints trace messages via warn()s to STDERR.
buffer => \$buffer — Appends trace messages to a string reference.
file => $filename — Append trace messages to a file. If the file doesn't already exist, it will be created for you. 🫶
log => $filename — This is equivalent to:

use Log::Trace file => $filename, {Verbose => 2};

syslog => $priority — Logs trace messages to syslog via Sys::Syslog, if it's available.

You should consult your syslog configuration before using this option. Like, actually consult it. 🙈

The default $priority is "debug", and the ident is set to Log::Trace. You can configure the priority, but beyond that, you can implement your own syslogging via the custom trace target.

custom => \&custom_trace_sub — Trace messages get processed by a custom subroutine. E.g.

use Log::Trace custom => \&mylogger;

sub mylogger {
        my @messages = @_;
        foreach (@messages) {
                # highly sensitive trace messages!
                tr/a-zA-Z/n-za-mN-ZA-M/;
                print;
        }
}

The import \%params are optional. These two statements are functionally the same:

import Log::Trace print => {Level => undef};
import Log::Trace 'print';

Peep OPTIONS for more info.

Note: If you use the custom tracing option, you should be careful about supplying a subroutine named TRACE.

🔥 OPTIONS 🔥

AllSubs => BOOL — Attaches a TRACE statement to every single subroutine in the package. Perfect for tracking the execution path of your code, and it's especially useful when you pair it with the Deep and Everywhere options.

Note: Anonymous subroutines and AUTOLOAD are not TRACEd. Not even a little.

AutoImport => BOOL — By default, Log::Trace only sets up TRACE routines in modules that are already loaded. This option overrides require() so that modules loaded after Log::Trace can automatically get set up for tracing too.

Note: This is an experimental feature. Check out the ENVIRONMENT NOTES for the behaviour under different versions of perl.

This option has no effect on perl < 5.6.

Deep => BOOL — Attaches Log::Trace to all packages (that define a TRACE function). Any TRACEF, DUMP and TRACE_HERE routines will also be overridden in these packages.
Dumper => Data::Serializer backend — Specifies a serialiser to use for DUMPing data structures.

This should either be a string naming a Data::Serializer backend (e.g. YAML) or a hashref of parameters which get passed to Data::Serializer, e.g.

{
        serializer => 'XML::Dumper',
        options => {
                dtd => 'path/to/my.dtd'
        }
}

Note that the raw_serialise() method of Data::Serializer is what gets used. See Data::Serializer for more.

If you don't have Data::Serializer installed, just leave this option undefined and it'll use Data::Dumper natively. 🧚

Default: undef (use standalone Data::Dumper)

Everywhere => BOOL — When you use this alongside the Deep option, it overrides the standard behaviour of only enabling tracing in packages that define TRACE stubs.

Default: false

Exclude => STRING|ARRAY — Excludes a module, or a whole list of modules, from tracing.
Level => NUMBER|LIST|CODE — Says which trace levels get displayed.

If no Level is defined, all TRACE statements will be output.

If the value is numeric, only TRACEs at the specified level or below will be output.

If the value is a list of numbers, only TRACEs matching the specified levels get output.

The level may also be a code reference, which is passed the package name and the TRACE level. It must return a true value if the TRACE is to be output.

Default: undef

Match => REGEX — Exports trace functions to packages matching the supplied regular expression. Can be used together with Exclude. You can also use Match as an exclusion method if you give it a negative look-ahead.

For example:

Match => qr/^(?!Acme::)/  # will exclude every module beginning with Acme::

and

Match => qr/^Acme::/      # does the reverse

Default: '.' # everything

Verbose => 0|1|2 — You can use this option to prepend extra information to each trace message. The levels represent increasing levels of verbosity:

0: the default*, don't add anything
1: adds subroutine name and line number to the trace output
2: As [1], plus a filename and timestamp (in ISO 8601 : 2000 format)

This setting has no effect on the custom or log targets.

* the log target uses 'Verbose' level 2

🌈 ENVIRONMENT NOTES 🌈

The AutoImport feature overrides CORE::require(), which requires perl 5.6 — but you may see unexpected errors if you aren't using at least perl 5.8. The AutoImport option has no effect on perl < 5.6.

In mod_perl or other persistent interpreter environments, different applications could trample on each other's TRACE routines if they use the Deep (or Everywhere) option. For example, application A could route all the trace output from Package::Foo into appA.log, and then application B could import Log::Trace right over the top, re-routing all the trace output from Package::Foo to appB.log for evermore. One way around this is to make sure you always import Log::Trace on every run in a persistent environment, from all your applications that use the Deep option. They may provide some more tools to work around this in a later version of Log::Trace. 😭

Log::Trace has not been tested in a multi-threaded application. Just so you know.

🎀 DEPENDENCIES 🎀

Carp
Time::HiRes      (used if available)
Data::Dumper     (used if available - necessary for meaningful DUMP output)
Data::Serializer (optional - to customise DUMP output)
Sys::Syslog      (loaded on demand)

💖 `Log::TraceMessages` 💖

okay so Log::TraceMessages is similar in design and purpose to Log::Trace — like, same vibe, same goal. But it only offers a subset of this module's functionality. Most notably, it doesn't offer a mechanism to control the tracing output of an entire application; tracing must be enabled on a module-by-module basis. Log::Trace also offers control over the output with the trace levels and supports more output targets. so that's a big difference, periodt 💅.

🦋 `Log::Agent` 🦋

Log::Agent offers a procedural interface to logging. It strikes a good balance between configurability and ease of use. It differs to Log::Trace in a number of ways. Log::Agent has a concept of channels and priorities, while Log::Trace only offers levels. Log::Trace also supports tracing code execution path and the Deep import option. Log::Trace trades a certain amount of configurability for increased ease-of use. so it's giving convenience over knobs, and honestly? valid 😌.

✨ `Log::Log4Perl` ✨

Log::Log4Perl is a feature rich perl port of the popular log4j library for Java. It is object-oriented and comprised of more than 30 modules. It has an impressive feature set, but some people may be frightened of its complexity. In contrast, to use Log::Trace you need only remember up to 4 simple functions and a handful of configuration options. so if Log::Log4Perl feels like a whole boss battle, Log::Trace is the cozy tutorial level 🎀.

👀 SEE ALSO 👀

Log::Trace::Manual - A guide to using Log::Trace

🏷️ VERSION 🏷️

version vibes: $Revision: 1.70 $ on $Date: 2005/11/01 11:32:59 $ by $Author: colinr $ 🫶

👑 AUTHOR 👑

John Alden and Simon Flack with some additions by Piers Kent and Wayne Myers <cpan _at_ bbc _dot_ co _dot_ uk> 💌

📜 COPYRIGHT 📜

(c) BBC 2005. This program is free software; you can redistribute it and/or modify it under the GNU GPL.

See the file COPYING in this distribution, or http://www.gnu.org/licenses/gpl.txt

and that's the whole entire tea ☕: this page is source/version perl v5.36.0, date 2022-10-13, and it's Log::Trace(3pm). stay tracing, bestie 💅✨🫶

📦 where this page comes from

ubuntu noble: liblog-trace-perl 1.070-5 · GPL-2.0-or-later
ubuntu resolute: liblog-trace-perl 1.070-5 · GPL-2.0-or-later
ubuntu stonking: liblog-trace-perl 1.070-5 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms