{
    "mode": "perldoc",
    "parameter": "SOAP::Trace",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/SOAP%3A%3ATrace/json",
    "generated": "2026-06-16T10:44:40Z",
    "synopsis": "Tracing is enabled by the SOAP::Lite import method. This is usually done at compile-time, though\nit may be done explicitly by calling import directly. The commands for setting up tracing start\nwith the keyword +trace. Alternately, +debug may be used; the two are interchangeable. After the\ninitial keyword, one or more of the signals detailed here may be specified, optionally with a\ncallback to handle them. When specifying multiple signals to be handled by a single callback, it\nis sufficient to list all of them first, followed finally by the callback, as in:\nuse SOAP::Lite +trace =>\nmethod => fault => \\&messagelevel,\ntrace => objects => \\&lowerlevel;\nIn the fragment, the reference to messagelevel is installed as the callback for both method and\nfault signals, while lowerlevel is installed for trace and object events. If callbacks aren't\nexplicitly provided, the default tracing action is to log a message to Perl's STDOUT file\ndescriptor. Callbacks should expect a one or more arguments passed in, though the nature of the\narguments varies based on the signal.\nAny signal can be disabled by prefacing the name with a hyphen, such as -result. This is useful\nwith the pseudosignal \"all,\" which is shorthand for the full list of signals. The following\nfragment disables only the two signals, while still enabling the rest:\nSOAP::Lite->import(+trace => all => -result => -parameters);\nIf the keyword +trace (or +debug) is used without any signals specified, it enables all signals\n(as if all were implied).\nThe signals and their meaning follow. Each also bears a note as to whether the signal is\nrelevant to a server application, client application, or both.",
    "sections": {
        "NAME": {
            "content": "SOAP::Trace - used only to manage and manipulate the runtime tracing of execution within the\ntoolkit\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This class has no methods or objects. It is used only to manage and manipulate the runtime\ntracing of execution within the toolkit. In absence of methods, this section reviews the events\nthat may be configured and the ways of configuring them.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "Tracing is enabled by the SOAP::Lite import method. This is usually done at compile-time, though\nit may be done explicitly by calling import directly. The commands for setting up tracing start\nwith the keyword +trace. Alternately, +debug may be used; the two are interchangeable. After the\ninitial keyword, one or more of the signals detailed here may be specified, optionally with a\ncallback to handle them. When specifying multiple signals to be handled by a single callback, it\nis sufficient to list all of them first, followed finally by the callback, as in:\n\nuse SOAP::Lite +trace =>\nmethod => fault => \\&messagelevel,\ntrace => objects => \\&lowerlevel;\n\nIn the fragment, the reference to messagelevel is installed as the callback for both method and\nfault signals, while lowerlevel is installed for trace and object events. If callbacks aren't\nexplicitly provided, the default tracing action is to log a message to Perl's STDOUT file\ndescriptor. Callbacks should expect a one or more arguments passed in, though the nature of the\narguments varies based on the signal.\n\nAny signal can be disabled by prefacing the name with a hyphen, such as -result. This is useful\nwith the pseudosignal \"all,\" which is shorthand for the full list of signals. The following\nfragment disables only the two signals, while still enabling the rest:\n\nSOAP::Lite->import(+trace => all => -result => -parameters);\n\nIf the keyword +trace (or +debug) is used without any signals specified, it enables all signals\n(as if all were implied).\n\nThe signals and their meaning follow. Each also bears a note as to whether the signal is\nrelevant to a server application, client application, or both.\n",
            "subsections": []
        },
        "TRACE SIGNALS": {
            "content": "transport *Client only*\nTriggered in the transport layer just before a request is sent and immediately after a\nresponse is received. Each time the signal is sent, the sole argument to the callback is the\nrelevant object. On requests, this is a HTTP::Request object; for responses, it's a\nHTTP::Response object.\n\ndispatch *Server only*\nTriggered with the full name of the method being dispatched, just before execution is passed\nto it. It is currently disabled in SOAP::Lite 0.55.\n\nresult *Server only*\nTriggered after the method has been dispatched and is passed the results returned from the\nmethod as a list. The result values have not yet been serialized when this signal is sent.\n\nparameters *Server only*\nTriggered before a method call is actually dispatched, with the data that is intended for\nthe call itself. The parameters for the method call are passed in as a list, after having\nbeen deserialized into Perl data.\n\nheaders *Server only*\nThis signal should be for triggering on the headers of an incoming message, but it isn't\nimplemented as of SOAP::Lite 0.55.\n\nobjects *Client or server*\nHighlights when an object is instantiated or destroyed. It is triggered in the new and\nDESTROY methods of the various SOAP::Lite classes.\n\nmethod *Client or server*\nTriggered with the list of arguments whenever the envelope method of SOAP::Serializer is\ninvoked with an initial argument of method. The initial string itself isn't passed to the\ncallback.\n\nfault *Client or server*\nAs with the method signal earlier, except that this signal is triggered when\nSOAP::Serializer::envelope is called with an initial argument of fault.\n\nfreeform *Client or server*\nLike the two previous, this signal is triggered when the method SOAP::Serializer::envelope\nis called with an initial parameter of freeform. This syntax is used when the method is\ncreating SOAP::Data objects from free-form input data.\n\ntrace *Client or server*\nTriggered at the entry-point of many of the more-significant functions. Not all the\nfunctions within the SOAP::Lite classes trigger this signal. Those that do are primarily the\nhighly visible functions described in the interface descriptions for the various classes.\n\ndebug *Client or server*\nUsed in the various transport modules to track the contents of requests and responses (as\nordinary strings, not as objects) at different points along the way.\n",
            "subsections": []
        },
        "EXAMPLES": {
            "content": "SELECTING SIGNALS TO TRACE\nThe following code snippet will enable tracing for all signals:\n\nuse SOAP::Lite +trace => 'all';\n\nYou can disable tracing for a set of signals by prefixing the signal name with a hyphen.\nTherefore, if you wish to enable tracing for every signal EXCEPT transport signals, then you\nwould use the code below:\n\nuse SOAP::Lite +trace => [ qw(all -transport) ];\n\nLOGGING SIGNALS TO A FILE\nYou can optionally provide a subroutine or callback to each signal trace you declare. Each time\na signal is received, it is passed to the corresponding subroutine. For example, the following\ncode effectively logs all fault signals to a file called fault.log:\n\nuse SOAP::Lite +trace => [ fault => \\&logfaults ];\n\nsub logfaults {\nopen LOGFILE,\">fault.log\";\nprint LOGFILE, $[0] . \"\\n\";\nclose LOGFILE;\n}\n\nYou can also use a single callback for multiple signals using the code below:\n\nuse SOAP::Lite +trace => [ method, fault => \\&log ];\n\nLOGGING MESSAGE CONTENTS\nThe transport signal is unique in the that the signal is not a text string, but the actually\nHTTP::Request being sent (just prior to be sent), or HTTP::Response object (immediately after it\nwas received). The following code sample shows how to make use of this:\n\nuse SOAP::Lite +trace => [ transport => \\&logmessage ];\n\nsub logmessage {\nmy ($in) = @;\nif (class($in) eq \"HTTP::Request\") {\n# do something...\nprint $in->contents; # ...for example\n} elsif (class($in) eq \"HTTP::Response\") {\n# do something\n}\n}\n\nONDEBUG\nThe \"ondebug\" method is available, as in:\n\nuse SOAP::Lite;\nmy $client = SOAP::Lite\n->uri($NS)\n->proxy($HOST)\n->ondebug( sub { print @; } );\n",
            "subsections": []
        },
        "ACKNOWLEDGEMENTS": {
            "content": "Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and\nredistribute large excerpts from *Programming Web Services with Perl*, mainly the SOAP::Lite\nreference found in Appendix B.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "Paul Kulchenko (paulclinger@yahoo.com)\n\nRandy J. Ray (rjray@blackperl.com)\n\nByrne Reese (byrne@majordojo.com)\n",
            "subsections": []
        }
    },
    "summary": "SOAP::Trace - used only to manage and manipulate the runtime tracing of execution within the toolkit",
    "flags": [],
    "examples": [
        "SELECTING SIGNALS TO TRACE",
        "The following code snippet will enable 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.",
        "Therefore, if you wish to enable tracing for every signal EXCEPT transport signals, then you",
        "would use the code below:",
        "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 is passed to the corresponding subroutine. For example, the following",
        "code effectively logs all fault signals to a file called fault.log:",
        "use SOAP::Lite +trace => [ fault => \\&logfaults ];",
        "sub logfaults {",
        "open LOGFILE,\">fault.log\";",
        "print LOGFILE, $[0] . \"\\n\";",
        "close LOGFILE;",
        "You can also use a single callback for multiple signals using the code below:",
        "use SOAP::Lite +trace => [ method, fault => \\&log ];",
        "LOGGING MESSAGE CONTENTS",
        "The transport signal is unique in the that the signal is not a text string, but the actually",
        "HTTP::Request being sent (just prior to be sent), or HTTP::Response object (immediately after it",
        "was received). The following code sample shows how to make use of this:",
        "use SOAP::Lite +trace => [ transport => \\&logmessage ];",
        "sub logmessage {",
        "my ($in) = @;",
        "if (class($in) eq \"HTTP::Request\") {",
        "# do something...",
        "print $in->contents; # ...for example",
        "} elsif (class($in) eq \"HTTP::Response\") {",
        "# do something",
        "ONDEBUG",
        "The \"ondebug\" method is available, as in:",
        "use SOAP::Lite;",
        "my $client = SOAP::Lite",
        "->uri($NS)",
        "->proxy($HOST)",
        "->ondebug( sub { print @; } );"
    ],
    "see_also": []
}