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.

Parameter Type Description
seconds Number The number of seconds to wait.

Example:

    n2svcd.wait (5)

The wait method returns true.

Function: .notice/.warning

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

These methods have a common 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.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:

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.

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.

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

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.

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

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.

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.

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.

Parameter Type Description
name String The name of the StatsD statistic to increment.

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.

Parameter Type Description
event_name String The name of the event type to log.
This is recorded in the Event Type field within the EDR output file.
fields Table A Lua Table of additional fields to log for this event.
Each element of the fields Table must have a value which is Scalar or List of Scalar.
stream_key Table An optional stream key, if this EDR is to be written to a non-default EDR stream.
This stream key must refer to a known, pre-configured stream key in the EdrApp.
(Default = The default configured for the LogicApp)

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.

Parameter Type Description
action String The name of the action to check the status of.
route String The name of a specific named instance for an action to check the status of.

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.

Parameter Type Description
seconds Integer The total number of Epoch seconds.
microseconds Integer The microseconds associated with our number of Epoch seconds.
    local tod = n2svcd.get_time_of_day ()
    n2svcd.debug ("NOW = %d.%d", tod.seconds, tod.microseconds)