Apache...stTrace(3pm)

✨ Apache::TestTrace — the manual page, but make it cute ✨

okay bestie, so this is the manual for Apache::TestTrace (you'll also see it written as Apache...stTrace(3pm), that's just the man page name doing its little truncation thing, don't worry about it 💅). It's a helper module for making output. Diagnostics. Messages. The whole vibe. Let's go 🦋

---

🌸 NAME 🌸

Apache::TestTrace — helper output generation functions 🎀

---

✨ SYNOPSIS ✨

no cap, here's the whole thing, character for character:

use Apache::TestTrace;

debug "foo bar";

info_sub "missed it";

error_mark "something is wrong";

# test sub that exercises all the tracing functions
sub test {
    print $Apache::TestTrace::LogFH
          "TraceLevel: $Apache::TestTrace::Level\n";
    $_->($_,[1..3],$_) for qw(emerg alert crit error
                              warning notice info debug todo);
    print $Apache::TestTrace::LogFH "\n\n"
};

# demo the trace subs using default setting
test();

{
    # override the default trace level with 'crit'
    local $Apache::TestTrace::Level = 'crit';
    # now only 'crit' and higher levels will do tracing lower level
    test();
}

{
    # set the trace level to 'debug'
    local $Apache::TestTrace::Level = 'debug';
    # now only 'debug' and higher levels will do tracing lower level
    test();
}

{
    open OUT, ">/tmp/foo" or die $!;
    # override the default Log filehandle
    local $Apache::TestTrace::LogFH = \*OUT;
    # now the traces will go into a new filehandle
    test();
    close OUT;
}

# override tracing level via -trace opt
% t/TEST -trace=debug

# override tracing level via env var
% env APACHE_TEST_TRACE_LEVEL=debug t/TEST

so yeah. tracing. levels. files. the whole main character toolkit. 👑

---

💖 DESCRIPTION 💖

okay so this module exports a bunch of functions that make it so much easier to generate all kinds of diagnostics messages in your programs, in a consistent way. and it saves you keystrokes, because it handles the new lines and ships your messages off to STDERR for you. literally doing the most so you can do the least 🫶

This module provides the same trace methods as syslog(3)'s log levels. listed from low level to high level: emerg(), alert(), crit(), error(), warning(), notice(), info(), debug(). The only different function is warning(), since warn is already taken by Perl. (rude of Perl honestly but okay 😭)

The module provides another trace function called todo() which is, you guessed it, useful for todo items. It has the same level as debug (the highest).

There are two more variants of each of these functions:

• If the _mark suffix is appended (e.g., error_mark) the trace will start with the filename and the line number the function was called from.
• If the _sub suffix is appended (e.g., error_info) the trace will start with the name of the subroutine the function was called from.

If you have Term::ANSIColor installed the diagnostic messages will be colorized 🌈 (slay). otherwise a special for each function prefix will be used.

If Data::Dumper is installed and you pass a reference to a variable to any of these functions, the variable will be dumped with Data::Dumper::Dumper(). iconic ✨

Functions whose level is above the level set in $Apache::TestTrace::Level become NOPs. For example if the level is set to alert, only alert() and emerg() functions will generate the output. The default setting of this variable is warning. Other valid values are: emerg, alert, crit, error, warning, notice, info, debug.

Another way to affect the trace level is to set $ENV{APACHE_TEST_TRACE_LEVEL}, which takes effect if $Apache::TestTrace::Level is not set. So an explicit setting of $Apache::TestTrace::Level always takes precedence. periodt 💅

By default all the output generated by these functions goes to STDERR. You can override the default filehandler by overriding $Apache::TestTrace::LogFH with a new filehandler.

⚠️ okay bestie listen: when you override this package's global variables, think about localizing your local settings, so it won't affect other modules using this module in the same run. do not be the person who leaks globals. 🙈

---

🎀 TODO 🎀

the literal list of things that are not done yet. we love transparency:

• provide an option to disable the coloring altogether via some flag or import()

(the original bullet uses o as the marker, but we're doing bullets here 💖)

---

🌟 AUTHOR 🌟

Stas Bekman with contributions from Doug MacEachern 👑

---

and that's the whole page, bestie!! 🦋 this one came from perl v5.42.3, dated 2026-08-20, straight from the User Contributed Perl Documentation. go forth and trace responsibly 💜🌸