Built-In Lua Actions

Built-In Action API

Introduction

In addition to the extensible run-time actions supported by agents and services loaded by the services and agents configuration in the LogicApp configuration, there is also a set of built-in actions which are always available to Lua scripts.

These actions are handled by the LogicApp itself and do not rely on external AgentApp components.

With the exception of the wait action, all internal actions will return immediately to the Lua script without suspending the process or allowing other calls to take over process control.

Invoking Built-In Actions

A Lua Script can access the built-in actions with code such as the following:

local n2svcd = require "n2.n2svcd"

local handler = function (args)

    -- Sleep 5 seconds
    n2svcd.wait (5)

    return "SUCCESS AFTER SLEEP"
end

return n2svcd.handler (handler)

This is standard Lua-style library usage. The n2/n2svcd.lua library is loaded with require "n2.n2svcd". Then methods are invoked on the returned library object.

Available Built-In Actions

Action: .wait

This method sets a timer and hands control back to the LogicApp. When the timer expires the Lua script will be resumed.

The wait method takes the following parameters.

Example:

    n2svcd.wait (5)

The wait method returns true.

Function: .notice/.warning

The notice, and warning log methods generate 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 IDs are used:

• Event ID SV-LU-90001 is used for user-defined notice output from LUA scripts.
• Event ID SV-LU-90002 is used for user-defined warning output from LUA scripts.

These methods have a common argument list.

Example:

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

The notice, and warning methods all return true.

Function: .debug

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:

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.

Example:

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

The debug method returns true.

Function: .debug_hex

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

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

This method has the following argument list.

Example:

    n2svcd.debug_hex (raw_asn1_bytes)

The debug_hex method returns true.

Function: .debug_var

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

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.

Example:

    n2svcd.debug_var (mytable)

The debug_var method returns true.

Function: .raise_trace

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.

Example:

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

The raise_trace method returns true.

Function: .stat_increment

The stat_increment method increments a statistics counter within the LogicApp.

The current statistics counter values can be viewed via the HTTP management console.

The statistics counters will be relayed to a StatsD collection agent if this is configured in the n2svcd.xml configuration file.

Example:

    n2svcd.stat_increment ("feedback.success")

The stat_increment method returns true.

Function: .write_edr

The write_edr method requests generation of an EDR of the indicated type, and with the indicated EDR attribute values.

EDR records will be sent to the EDR Application by the LogicApp.

This requires that the executing LogicApp have EDRs enabled using the edr_enabled flag in the n2svcd.xml configuration file.

This requires that an EDR Application be running, and the the executing LogicApp be configured to send to the EDR app.

This requires that the EDR stream key be configured in the EDR application. By default, the LogicApp’s stream key will be used. However, the calling LUA logic may specify an alternate stream key.

Example:

    n2svcd.write_edr ("FEEDBACK", { MSISDN = input.msisdn, SUCCESS = 1, MYLIST = { "First", "Second" } })

The write_edr method returns true.

Function: .agent_status

The agent_status method checks the application status of a Lua Agent. The Agent will perform its own determination of availability. This will typically involve examing the Application Status of any application(s) which this agent uses to perform its function.

For example, a DB agent will use a DBApp to perform its function, and hence will consider the DBApp’s status when returning the agent status value.

The agent_status method takes the following parameters.

Example:

    local db_status = n2svcd.agent_status ("db")

The agent_status method returns an application status number between 0-8.

Function: .get_time_of_day

The get_time_of_day method queries Perl for the current system timestamp. This method allows Lua to obtain better than second resolution without the requirement of additional external libraries.

The get_time_of_day method takes no parameters.

The get_time_of_day method returns the following properties.

    local tod = n2svcd.get_time_of_day ()
    n2svcd.debug ("NOW = %d.%d", tod.seconds, tod.microseconds)