Test2:...:Trace(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

💖 Test2::...::Trace — the whole scoop 🦋

okay bestie, welcome to the Perl Programmers Reference Guide page for Test2::EventFacet::Trace — yes the manual is called Test2:...:Trace(3perl) and yes it's a whole thing, we move 💅

✨ NAME ✨

Test2::EventFacet::Trace — literally just debug info for events, that's her whole job 🎀

🌸 DESCRIPTION 🌸

so like, the Test2::API::Context object AND every single Test2::Event type out there need to know where they came from, right? where they were created, the whole origin story. This object is that information. It's the receipts. It's the "no, I was born here, at this file, at this line" energy 👑

🦋 SYNOPSIS 🦋

use Test2::EventFacet::Trace;

my $trace = Test2::EventFacet::Trace->new(
    frame => [$package, $file, $line, $subname],
);

look at her go ✨ minimal effort, maximum lore.

🎀 FACET FIELDS 🎀

every single one, no skips, we don't do that here 🫶

  • $string = $trace->{details}
  • $string = $trace->details()

this one's a custom trace message, and when you call $trace->debug it gets used INSTEAD of "at <FILE> line <LINE>". so like, it fully replaces it. not "in addition to". replaces. periodt 💅

  • $frame = $trace->{frame}
  • $frame = $trace->frame()

grab the call frame arrayref, which is exactly this:

[$package, $file, $line, $subname]
  • $int = $trace->{pid}
  • $int = $trace->pid()

the process ID where the event got generated 🧚

  • $int = $trace->{tid}
  • $int = $trace->tid()

the thread ID where the event got generated.

  • $id = $trace->{cid}
  • $id = $trace->cid()

the ID of the context that was used to create the event. context said yes to being a parent, iconic.

  • $uuid = $trace->{uuid}
  • $uuid = $trace->uuid()

the UUID of the context that was used to create the event. (If uuid tagging was enabled) — so only if you turned that on, otherwise don't come for her.

  • ($pkg, $file, $line, $subname) = $trace->call

get the basic call info, as a list. list context besties rise 🌈

  • @caller = $trace->full_call

get the full caller(N) results. the deluxe version. the director's cut 🔥

  • $warning_bits = $trace->warning_bits

get index 9 from the full caller info. that's the warnings_bits field, queen.

⚠️ warning bestie: the value of this is not portable across perl versions or even across processes. lowkey rude of it. BUT — it can still be used inside the same process that generated it, to reproduce the warnings settings in a new scope:
eval <<EOT;
BEGIN { ${^WARNING_BITS} = $trace->warning_bits };
... context's warning settings apply here ...
EOT

okay so these fields were not always set properly by tools. They're MOSTLY deprecated in favor of the Test2::EventFacet::Hub facets. They are not required, and they may only reflect the hub that was current when the event was created — which is not necessarily the same hub the event was sent through. it's giving "yeah that's the vibe at the time, not the truth" 😭

some tools did do a good job setting these to the correct hub, but ngl you cannot always rely on that. use the 'hubs' facet list instead. that's the main character here, these are the supporting cast 🙈

  • $hid = $trace->{hid}
  • $hid = $trace->hid()

the ID of the hub that was current when the event was created.

  • $huuid = $trace->{huuid}
  • $huuid = $trace->huuid()

the UUID of the hub that was current when the event was created. (If uuid tagging was enabled)

  • $int = $trace->{nested}
  • $int = $trace->nested()

how deeply nested the event is. depth check ✨

  • $bool = $trace->{buffered}
  • $bool = $trace->buffered()

true if the event was buffered and not sent to the formatter independent of a parent. (This should never be set when nested is 0 or "undef") — so if you see that, something is deeply wrong, and not in the cute way 💀

⭐ METHODS ⭐

📌 Note: All facet frames are also methods. every single one. they contain multitudes.
  • $trace->set_detail($msg)
  • $msg = $trace->detail

get/set a custom trace message that will be used INSTEAD of "at <FILE> line <LINE>" when calling $trace->debug.

also: detail() is an alias to the "details" facet field, for backwards compatibility. we keep her around for the old heads, no cap 🫶

  • $str = $trace->debug

typically returns the string "at <FILE> line <LINE>". but if "detail" is set, then its value gets returned instead. she switches up but she's consistent about it 💅

  • $trace->alert($MESSAGE)

issues a warning at the frame — that's the filename and line number where errors should be reported. it's the polite lil nudge 😇

  • $trace->throw($MESSAGE)

throws an exception at the frame — same deal, filename and line number where errors should be reported. it's the alert's louder sibling 🔥

  • ($package, $file, $line, $subname) = $trace->call()

get the caller details for the debug-info. this is where errors should be reported. it's the "blame this spot" function, and honestly? fair.

  • $pkg = $trace->package

get the debug-info package.

  • $file = $trace->file

get the debug-info filename.

  • $line = $trace->line

get the debug-info line number.

  • $subname = $trace->subname

get the debug-info subroutine name.

  • $sig = trace->signature

get a signature string that identifies this trace. it's used to check if multiple events are related — like a little friendship bracelet for events 🎀 the signature includes pid, tid, file, line number, and the cid.

🌈 SOURCE 🌈

the source code repository for Test2 can be found at <https://github.com/Test-More/test-more/>. go look, it's free real estate 👑

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

💜 AUTHORS 💜

Chad Granum <exodist@cpan.org>

Copyright Chad Granum <exodist@cpan.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <https://dev.perl.org/licenses/>

and that's the whole page bestie, ty for coming to my TED talk 🫶 this was perl v5.44.0, dated 2026-10-17, and it's the Test2:...:Trace(3perl) manual — go forth and trace responsibly 💖✨🎀

📦 where this page comes from