Navigation :

Trace Methods

Introduction

The trace methods record trace information which is recorded against the running instance’s in-memory trace log, assuming that trace-logging has been activated for that particular instance.

Inside any Lua script running within the LogicApp, the TRACE_LEVEL global variable indicates if trace-logging is currently enabled.

There are several ways in which an instance can have in-memory trace-logging activated. For example:

Globally via the command-line options --debug, etc.
Per-application via the applications trace_level parameter in n2svcd.xml.
Initiated by a rules-based trace trigger configured on an application.
Requested via the raise_trace built-in Lua script method.

These methods are accessed via the “n2.n2svcd” module:

    local n2svcd = require "n2.n2svcd"

Global Variables

The following global variables are available related to tracing.

These method argument list is:

Parameter	Type	Description
`TRACE_LEVEL`	`0` - `3`	`0` - No tracing. `1` - DEBUG-level tracing. `2` - DUMP-level tracing. `3` - SPAM-level tracing.

.notice [Synchronous]

The notice log method generates a message which will be:

Written to STDERR.
Written to in-memory tracing.
Written to syslog if syslog is configured in the n2svcd.xml configuration.
Written to SNMP if snmp is configured in the n2svcd.xml configuration.

The in-memory instance trace logs can be accessed via the HTTP management console or API.

The following pre-defined Event ID is used:

Event ID SV-LU-90001 is used for user-defined notice output from Lua scripts.

These method argument list is:

Parameter	Type	Description
`format`	String	A `printf` format string as per the C library function.
`args`	Any	None or more optional arguments to the `printf` string matching the printf placeholders.

Example:

    n2svcd.notice ("Service Success.  Configuration change #[%s] now active.", seq_number)

The notice methods returns true.

.warning [Synchronous]

The warning method is identical to the notice method, except that the generated log entry has level WARNING instead of NOTICE.

The following pre-defined Event ID is used:

Event ID SV-LU-90002 is used for user-defined warning output from Lua scripts.

The method arguments are identical to notice.

Example:

    n2svcd.warning ("Service Declined.  Invalid Destination MSISDN '%s'.", dest_msisdn)

The notice, and warning methods both return true.

.debug [Synchronous]

The debug method generates a message which will be:

Written to STDERR if n2svcd was run with the --debug, --dump, or --spam flags.
Written to in-memory tracing for access via the Management GUI/API if trace is enabled for this instance.

The in-memory instance trace logs can be accessed via the HTTP management console or API.

Note that:

Debug output will have no effect if in-memory trace logging is not enabled for the instance and STDERR debugging is not enabled.
Extensive use of debug output can have detrimental effect on production processing throughput.

This method has the following argument list.

Parameter	Type	Description
`format`	String	A `printf` format string as per the C library function.
`args`	Any	None or more optional arguments to the `printf` string matching the printf placeholders.

Example:

    n2svcd.debug ("Setting default widget ID = %d.", myconfig.DEFAULT_ID)

The debug method returns true.

.debug_hex [Synchronous]

The debug_hex method generates output to the same destinations as the .debug method.

The output is represented as a hex dump showing the binary content of the scalar.

This method has the following argument list.

Parameter	Type	Description
`value`	Binary	A Lua (binary) string whose contents will be represented in hexadecimal format.

Example:

    n2svcd.debug_hex (raw_asn1_bytes)

This method will not perform any tracing if the global TRACE_LEVEL == 0.

The debug_hex method returns true.

.debug_var [Synchronous]

The debug_var method generates output to the same destinations as the .debug method.

The output is represented as a pretty-printed object representation, including recursion into the sub-elements of Table/List structures.

This method has the following argument list.

Parameter	Type	Description
`value`	Any	A Lua Scalar or Table whose output will be logged.

Example:

    n2svcd.debug_var (mytable)

This method will not perform any tracing if the global TRACE_LEVEL == 0.

The debug_var method returns true.

.raise_trace [Synchronous]

The raise_trace method enables in-memory tracing (if it is not already enabled) for the in-progress LogicApp instance. This will ensure that debug information can be viewed via the HTTP management console.

This method is useful when you wish to gather debugging information about a specific scenario, but you do not wish to enable in-memory trace logging across the entire application in a production environment.

This does not affect the writing of debug to STDERR or Syslog, and does not affect any other instances.

The in-memory level will never be lowered by this method.

Parameter	Type	Description
`level`	Integer	The trace level which should be enabled. Possible values are: `0` = none `1` = `debug` `2` = `dump` `3` = `spam` The use of levels above DEBUG is not recommended in a production environment.

Example:

    n2svcd.raise_trace (1)
    n2svcd.debug ("This debug will now appear.")

The raise_trace method returns true.