SOAP::Trace(3)

💅 SOAP::Trace(3) — the vibes guide ✨

okay so this page is from the Perl world — specifically SOAP::Trace in the user-contributed Perl docs section, and bestie, it's a short one but it slaps. Let's get into it 🫶

---

✨ NAME ✨

SOAP::Trace — used only to manage and manipulate the runtime tracing of execution within the toolkit. That's it. That's the whole job. No cap.

---

🎀 DESCRIPTION 🎀

Lowkey the most important thing to know: this class has no methods or objects. None. Zero. It exists purely to manage and manipulate the runtime tracing of execution within the toolkit. Periodt.

And since there are no methods to talk about, this section is instead gonna review the events you can configure and the ways of configuring them. Cute, right? 💖

---

🦋 SYNOPSIS 🦋

So tracing gets enabled by the SOAP::Lite import method. Usually that happens at compile-time, but you can do it explicitly by calling import directly — you're the main character, you make the rules 💅

The commands for setting up tracing all start with the keyword +trace. Alternately, +debug works too — the two are interchangeable, iykyk.

After that initial keyword, you list one or more of the signals detailed below, optionally with a callback to handle them. And here's the slay part: when you want multiple signals handled by a single callback, you just list all of them first, then the callback at the end, like this:

use SOAP::Lite +trace =>
  method => fault => \&message_level,
  trace => objects => \&lower_level;

In that little fragment, the reference to message_level gets installed as the callback for both the method and fault signals, while lower_level is installed for the trace and object events. Two-for-one deal, we love to see it 🎀

If you don't explicitly provide callbacks, the default tracing action is to log a message to Perl's STDOUT file descriptor. And heads up — callbacks should expect one or more arguments passed in, though the nature of those arguments varies based on the signal. Just trust the process ✨

Any signal can be disabled by prefacing the name with a hyphen, like -result. This is extra useful with the pseudosignal "all," which is shorthand for the full list of signals. So this fragment right here disables only the two signals while still enabling everything else:

SOAP::Lite->import(+trace => all => -result => -parameters);

And if you use the keyword +trace (or +debug) with no signals specified at all? It enables all signals, as if all were implied. Sneaky but iconic 💀

The signals and what they mean follow below — each one also has a lil note about whether it's relevant to a server application, a client application, or both.

---

🔥 TRACE SIGNALS 🔥

• transport — Client only — Triggered in the transport layer just before a request is sent and immediately after a response is received. Every time the signal fires, the sole argument to the callback is the relevant object. On requests that's an HTTP::Request object; for responses it's an HTTP::Response object. Obsessed with the precision here 💜
• dispatch — Server only — Triggered with the full name of the method being dispatched, just before execution is passed to it. Ngl though — it is currently disabled in SOAP::Lite 0.55. Sad, I know 😭
• result — Server only — Triggered after the method has been dispatched and it's passed the results returned from the method as a list. Key detail: the result values have not yet been serialized when this signal is sent 👑
• parameters — Server only — Triggered before a method call is actually dispatched, with the data that's intended for the call itself. The parameters for the method call get passed in as a list, after having been deserialized into Perl data 🌸
• headers — Server only — This signal should be for triggering on the headers of an incoming message, but bestie it just isn't implemented as of SOAP::Lite 0.55. It's giving aspiration 🫠
• objects — Client or server — Highlights when an object is instantiated or destroyed. Triggered in the new and DESTROY methods of the various SOAP::Lite classes ✨
• method — Client or server — Triggered with the list of arguments whenever the envelope method of SOAP::Serializer is invoked with an initial argument of method. Little detail: the initial string itself isn't passed to the callback 💅
• fault — Client or server — Same deal as the method signal earlier, except this one triggers when SOAP::Serializer::envelope is called with an initial argument of fault 🔥
• freeform — Client or server — Like the two previous, this signal triggers when the method SOAP::Serializer::envelope is called with an initial parameter of freeform. This syntax is used when the method is creating SOAP::Data objects from free-form input data 🦋
• trace — Client or server — Triggered at the entry-point of many of the more-significant functions. Not all the functions within the SOAP::Lite classes trigger this signal, though — the ones that do are primarily the highly visible functions described in the interface descriptions for the various classes 🌈
• debug — Client or server — Used in the various transport modules to track the contents of requests and responses (as ordinary strings, not as objects) at different points along the way ⭐

---

🧚 EXAMPLES 🧚

🌸 SELECTING SIGNALS TO TRACE

This code snippet enables tracing for all signals:

use SOAP::Lite +trace => 'all';

You can disable tracing for a set of signals by prefixing the signal name with a hyphen. So if you want tracing for every signal EXCEPT transport signals, you'd use this:

use SOAP::Lite +trace => [ qw(all -transport) ];

💖 LOGGING SIGNALS TO A FILE

You can optionally provide a subroutine or callback to each signal trace you declare. Each time a signal is received, it gets passed to the corresponding subroutine. For example, this code effectively logs all fault signals to a file called fault.log:

use SOAP::Lite +trace => [ fault => \&log_faults ];

sub log_faults {
  open LOGFILE,">fault.log";
  print LOGFILE, $_[0] . "\n";
  close LOGFILE;
}

And you can also use a single callback for multiple signals using this:

use SOAP::Lite +trace => [ method, fault => \&log ];

👑 LOGGING MESSAGE CONTENTS

Okay the transport signal is unique because it is not a text string — it's the actual HTTP::Request being sent (just prior to being sent), or the HTTP::Response object (immediately after it was received). Here's how to make use of that:

use SOAP::Lite +trace => [ transport => \&log_message ];

sub log_message {
  my ($in) = @_;
  if (class($in) eq "HTTP::Request") {
    # do something...
    print $in->contents; # ...for example
  } elsif (class($in) eq "HTTP::Response") {
    # do something
  }
}

🍓 ON_DEBUG

The "on_debug" method is available too, as in:

use SOAP::Lite;
my $client = SOAP::Lite
  ->uri($NS)
  ->proxy($HOST)
  ->on_debug( sub { print @_; } );

---

🙈 ACKNOWLEDGEMENTS 🙈

Special thanks to O'Reilly publishing, which has graciously allowed SOAP::Lite to republish and redistribute large excerpts from Programming Web Services with Perl — mainly the SOAP::Lite reference found in Appendix B. Genuinely so generous of them 🫶

---

💜 COPYRIGHT 💜

Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.

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

---

🌟 AUTHORS 🌟

• Paul Kulchenko (paulclinger@yahoo.com) 👑
• Randy J. Ray (rjray@blackperl.com) ✨
• Byrne Reese (byrne@majordojo.com) 🦋

---

and that's the whole page, bestie — brought to you by perl v5.42.0, dated 2024-03-04, in the classic SOAP::Trace(3) manpage slot. go trace responsibly 💅🎀