1SOAP::Trace(3) User Contributed Perl Documentation SOAP::Trace(3)
2
6 SOAP::Trace - used only to manage and manipulate the runtime tracing of
7 execution within the toolkit
8
10 This class has no methods or objects. It is used only to manage and
11 manipulate the runtime tracing of execution within the toolkit. In
12 absence of methods, this section reviews the events that may be
13 configured and the ways of configuring them.
14
16 Tracing is enabled by the SOAP::Lite import method. This is usually
17 done at compile-time, though it may be done explicitly by calling
18 import directly. The commands for setting up tracing start with the
19 keyword +trace. Alternately, +debug may be used; the two are
20 interchangeable. After the initial keyword, one or more of the signals
21 detailed here may be specified, optionally with a callback to handle
22 them. When specifying multiple signals to be handled by a single
23 callback, it is sufficient to list all of them first, followed finally
24 by the callback, as in:
25 use SOAP::Lite +trace =>
27 method => fault => \&message_level,
28 trace => objects => \&lower_level;
29 In the fragment, the reference to message_level is installed as the
31 callback for both method and fault signals, while lower_level is
32 installed for trace and object events. If callbacks aren't explicitly
33 provided, the default tracing action is to log a message to Perl's
34 STDOUT file descriptor. Callbacks should expect a one or more arguments
35 passed in, though the nature of the arguments varies based on the
36 signal.
37 Any signal can be disabled by prefacing the name with a hyphen, such as
39 -result. This is useful with the pseudosignal "all," which is shorthand
40 for the full list of signals. The following fragment disables only the
41 two signals, while still enabling the rest:
42 SOAP::Lite->import(+trace => all => -result => -parameters);
44 If the keyword +trace (or +debug) is used without any signals
46 specified, it enables all signals (as if all were implied).
47 The signals and their meaning follow. Each also bears a note as to
49 whether the signal is relevant to a server application, client
50 application, or both.
51
53 transport Client only
54 Triggered in the transport layer just before a request is sent and
55 immediately after a response is received. Each time the signal is
56 sent, the sole argument to the callback is the relevant object. On
57 requests, this is a HTTP::Request object; for responses, it's a
58 HTTP::Response object.
59 dispatch Server only
61 Triggered with the full name of the method being dispatched, just
62 before execution is passed to it. It is currently disabled in
63 SOAP::Lite 0.55.
64 result Server only
66 Triggered after the method has been dispatched and is passed the
67 results returned from the method as a list. The result values have
68 not yet been serialized when this signal is sent.
69 parameters Server only
71 Triggered before a method call is actually dispatched, with the
72 data that is intended for the call itself. The parameters for the
73 method call are passed in as a list, after having been deserialized
74 into Perl data.
75 headers Server only
77 This signal should be for triggering on the headers of an incoming
78 message, but it isn't implemented as of SOAP::Lite 0.55.
79 objects Client or server
81 Highlights when an object is instantiated or destroyed. It is
82 triggered in the new and DESTROY methods of the various SOAP::Lite
83 classes.
84 method Client or server
86 Triggered with the list of arguments whenever the envelope method
87 of SOAP::Serializer is invoked with an initial argument of method.
88 The initial string itself isn't passed to the callback.
89 fault Client or server
91 As with the method signal earlier, except that this signal is
92 triggered when SOAP::Serializer::envelope is called with an initial
93 argument of fault.
94 freeform Client or server
96 Like the two previous, this signal is triggered when the method
97 SOAP::Serializer::envelope is called with an initial parameter of
98 freeform. This syntax is used when the method is creating
99 SOAP::Data objects from free-form input data.
100 trace Client or server
102 Triggered at the entry-point of many of the more-significant
103 functions. Not all the functions within the SOAP::Lite classes
104 trigger this signal. Those that do are primarily the highly visible
105 functions described in the interface descriptions for the various
106 classes.
107 debug Client or server
109 Used in the various transport modules to track the contents of
110 requests and responses (as ordinary strings, not as objects) at
111 different points along the way.
112
114 SELECTING SIGNALS TO TRACE
115 The following code snippet will enable tracing for all signals:
116 use SOAP::Lite +trace => 'all';
118 You can disable tracing for a set of signals by prefixing the signal
120 name with a hyphen. Therefore, if you wish to enable tracing for every
121 signal EXCEPT transport signals, then you would use the code below:
122 use SOAP::Lite +trace => [ qw(all -transport) ];
124 LOGGING SIGNALS TO A FILE
126 You can optionally provide a subroutine or callback to each signal
127 trace you declare. Each time a signal is received, it is passed to the
128 corresponding subroutine. For example, the following code effectively
129 logs all fault signals to a file called fault.log:
130 use SOAP::Lite +trace => [ fault => \&log_faults ];
132 sub log_faults {
134 open LOGFILE,">fault.log";
135 print LOGFILE, $_[0] . "\n";
136 close LOGFILE;
137 }
138 You can also use a single callback for multiple signals using the code
140 below:
141 use SOAP::Lite +trace => [ method, fault => \&log ];
143 LOGGING MESSAGE CONTENTS
145 The transport signal is unique in the that the signal is not a text
146 string, but the actually HTTP::Request being sent (just prior to be
147 sent), or HTTP::Response object (immediately after it was received).
148 The following code sample shows how to make use of this:
149 use SOAP::Lite +trace => [ transport => \&log_message ];
151 sub log_message {
153 my ($in) = @_;
154 if (class($in) eq "HTTP::Request") {
155 # do something...
156 print $in->contents; # ...for example
157 } elsif (class($in) eq "HTTP::Response") {
158 # do something
159 }
160 }
161 ON_DEBUG
163 The "on_debug" method is available, as in:
164 use SOAP::Lite;
166 my $client = SOAP::Lite
167 ->uri($NS)
168 ->proxy($HOST)
169 ->on_debug( sub { print @_; } );
170
172 Special thanks to O'Reilly publishing which has graciously allowed
173 SOAP::Lite to republish and redistribute large excerpts from
174 Programming Web Services with Perl, mainly the SOAP::Lite reference
175 found in Appendix B.
176
178 Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.
179 This library is free software; you can redistribute it and/or modify it
181 under the same terms as Perl itself.
182
184 Paul Kulchenko (paulclinger@yahoo.com)
185 Randy J. Ray (rjray@blackperl.com)
187 Byrne Reese (byrne@majordojo.com)
189perl v5.36.0 2023-01-20 SOAP::Trace(3)