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:

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:

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

The following pre-defined Event ID is used:

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:

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:

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

Note that:

  1. Debug output will have no effect if in-memory trace logging is not enabled for the instance and STDERR debugging is not enabled.
  2. 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.