Developer Guide for SIP Transparency and Normalization
Trace APIs
Downloads: This chapterpdf (PDF - 336.0KB) The complete bookPDF (PDF - 1.86MB) | Feedback

Trace APIs

Table Of Contents

Trace APIs

trace.format

trace.enable

trace.disable

trace.enabled


Trace APIs


Script tracing allows the script writer to produce traces from within the script. This must only be used for debugging the script. It must be disabled when the script starts working. There are two ways to enable script tracing.

1. Via configuration—refer to the Script Trace checkbox associated with the SIP Trunk.

2. Via scripting—refer to the trace.enable() API.

The following table indicates whether or not traces are produced by the script based on all combinations of the two settings described above:

Configuration
Scripting
Trace Produced

Enabled

Enabled

Yes

Enabled

Disabled

No

Disabled

Enabled

No

Disabled

Disabled

No


The trace library provides the following APIs:

trace.format

trace.enable

trace.disable

trace.enabled

trace.format

trace.format(format-string, p1, p2, ...)

Given a format string and a list of parameters, this function inserts the parameters into the format string and writes the output to the SDI trace file, if tracing is enabled for the trunk associated with the script and the script has enabled tracing via trace.enable().

Example

M = {}
trace.enable()
function M.inbound_INVITE(msg)
    local callid = msg:getHeader("Call-Id")
    trace.format("Call-Id header is %s", callid)
end
return M

trace.enable

trace.enable()

This allows the script to enable tracing locally.


Note Tracing must also be enabled via configuration for the SIP Trunk using the script.


Example

Refer to the trace.format example above.

trace.disable

trace.disable()

This allows the script to disable tracing locally.


Note If the script trace configuration flag for the associated trunk is enabled, script trace will still be produced by Trace.output even if disabled here.


Example:
M = {}
trace.disable()
function M.inbound_INVITE(msg)
    local callid = msg:getHeader("Call-Id")
    trace.format("Call-Id header is %s", callid)
end
return M

trace.enabled

trace.enabled() turns a boolean

True is returned if script tracing has been enabled on the device associated with this instance of the script or if the script has enabled the tracing itself. If tracing has not been enabled, it returns false.

Example

M = {}
trace.enable()
function M.inbound_INVITE(msg)
    if trace.enabled()
    then
        local callid = msg:getHeader("Call-Id")
        trace.format("Call-Id header is %s", callid)
    end
end
return M