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.

The wait method returns true.

Function: .debug/.notice/.warning

The debug, notice, and warning log methods are all used for generating output to STDERR, and/or in-memory tracing, and/or the system logs according to the standard rules.

Furthermore:

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

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.

These methods all 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.

The debug, notice, and warning methods all return true.

Function: .debug_hex/.notice_hex/.warning_hex

The debug_hex, notice_hex, and warning_hex log methods are all used for generating output to STDERR, and/or in-memory tracing, and/or the system logs according to the standard rules.

See the notes under the .debug/.notice/.warning action for where this output may be written, depending on configuration.

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

These methods all have a common argument list.

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

The debug_hex, notice_hex, and warning_hex methods all return true.

Function: .debug_var/.notice_var/.warning_var

The debug_var, notice_var, and warning_var log methods are all used for generating output to STDERR, and/or in-memory tracing, and/or the system logs according to the standard rules.

See the notes under the .debug/.notice/.warning action for where this output may be written, depending on configuration.

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

These methods all have a common argument list.

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

The debug_var, notice_var, and warning_var methods all return 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.

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.

The stat_increment method returns true.

Function: .write_edr

The write_edr method increments a statistics counter within the LogicApp.

EDR records will be written to the LogicApp EDR stream, assuming that it has been enabled using the edr_enabled flag in the n2svcd.xml configuration file.

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.
parameters Table A Lua Table of additional parameters to log for this event.
The Table values must be Scalar or List of Scalar.

The write_edr method returns true.

Function: .agent_status

The agent_status method checks the application status of a Lua Application Instance.

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.

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.