=head1 NAME
Net::SIP::Debug - debugging of Net::SIP
=head1 SYNOPSIS
Net::SIP::Debug->level(1);
perl -MNet::SIP::Debug=1 app.pl
=head1 DESCRIPTION
Provides debugging support
for
L<Net::SIP>.
Debugging can be enabled/disabled globally or per
package
and optional per subpackage.
It provides support
for
different debugging levels, e.g.
the higher the level, the more debugging is done.
The following levels are used:
=over 4
=item
1 - Debug messages
for
users.
=item
2 - Includes short SIP packet dumps of incoming and outgoing data.
=item
5 - Includes detailed SIP packet dumps
for
incoming and outgoing data.
=item
10 - Includes information about call flow, e.g. why packets get dropped etc.
=item
50 - Detailed debugging
for
programmers using L<Net::SIP>.
=item
100 - Detailed debugging
for
core developers of L<Net::SIP>.
=back
=head1 CLASS METHODS
=over 4
=item
import
(
@ARGS
)
Extracts everything from arguments
given
to C<
use
> which might
be usable by B<level> and forwards rest to L<Exporter>.
If the argument is a reference to a subroutine it will be used
for
showing the debug message instead of printing it to STDERR.
In this case the usual prefixes incl the
time
will not be added
(useful
for
forwarding debug to syslog).
=item level (
@ARGS
)
Enables/disables debugging depending on
@ARGS
.
@ARGS
might
contain the following specifications:
=over 8
=item NUMBER
NUMBER will be interpreted as the debugging level.
It's used in B<debug> etc to
print
only debug message which a
level lower or equal to NUMBER.
=item PACKAGE
Enables debugging
for
package
PACKAGE. PACKAGE might be a fully
qualified
package
(e.g. C<Net::SIP::Registrar>) or the C<Net>
or C<Net::SIP> might be omitted (C<Registrar>). If a C<*> is added
the debugging will also be enabled
for
subpackages, e.g.
C<Endpoint*> will enable debugging
for
L<Net::SIP::Endpoint> and
L<Net::SIP::Endpoint::Context> too.
=item PACKAGE=NUMBER
Similar to the previous item, but this sets debugging level to
NUMBER
for
the specified packages and thus can also be used to
selectively disable debugging
for
some packages.
=back
If
@ARGS
is empty it will
return
the debugging level
for
the
package
which called this method (the first
package
in the
caller
stack
which is not Net::SIP::Debug itself).
=item set_prefix ( PREFIX )
Sets prefix used
for
debug messages to PREFIX. Default prefix
is
'DEBUG:'
but
for
instance
for
forking applications it might
be useful to change this to
"DEBUG($$):"
or similar.
=back
=head1 SUBROUTINES
=over 4
=item DEBUG|debug ( [ LEVEL ],( MESSAGE | FMT,
@ARG
))
If debugging is enabled it will
print
debugging info to STDERR.
If multiple arguments are
given
to the function they will be
fed into B<
sprintf
> to create a single message.
If the first argument looks like a number (see B<looks_like_number>
in L<Scalar::Util>) it will be interpreted as the debug level
for
this message, e.g.
if
it is higher than the user specified
debug level the message will not be printed.
The MESSAGE (or the result from C<<
sprintf
(FMT,
@ARG
) >>) will be
prefixed by the
caller
package
, the
caller
function and the line
from which DEBUG was called. In front of the prefix the current
time
(as float time_t) and the string
"DEBUG:"
will be added.
If the message consists of multiple lines
each
line will be prefixed
by the prefix and all but the first line will also have a TAB added
between prefix and message data.
The function is by
default
exported as B<DEBUG> and can by exported
as B<debug> too.
=item DEBUG_DUMP ( [ LEVEL ],
@DATA
)
Will call B<debug>
with
the output from L<Data::Dumper>s B<Dumper>
if
debugging is enabled. If
@DATA
has
more than one item it will
be fed as reference into B<Dumper>, otherwise only the single item
will be fed to B<Dumper>.
For the meaning of LEVEL see B<debug>.
This function is exported by
default
.
=item stacktrace ( MESSAGE | FMT,
@ARG
)
Uses the arguments in B<debug>, but instead of writing a debug
message to STDERR it will be used in Carp::longmess.
Returns string
with
stacktrace.
=item LEAK_TRACK ( REF )
This is used internally
for
tracking leaks. It will rebless REF into
a new class which behaves like the old one. Calls of LEAK_TRACK
and DESTROY on this class will be tracked and shown. If L<Devel::Peek>
can be loaded it will B<Dump> information about the REF on
each
call to LEAK_TRACK.
Exported by
default
.
=back
=head1 exported Variables
=over 4
=item
$DEBUG
This variable is set to false
if
all kind of debugging is disabled.
This variable is exported by
default
. It should not be changed.
It is intended to be used as a quick check to save expensive calls of debugging
functions
if
no
debugging will be used anyway, i.e.:
$DEBUG
&& DEBUG(...)
=back