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.

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.

• Any debug logging will be written to STDERR if N2SVCD was run with the --debug, --dump, or --spam flags.
• Any notice or warning logging is always written to STDERR.
• Any notice or warning logging is written to syslog if syslog is configured in the n2svcd.xml configuration.

Furthermore:

• Any debug logging will be written to the in-memory instance trace log if that is enabled for this instance.
• Any notice or warning logging will be written to the in-memory instance trace log.

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.

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.

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.

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.

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.

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.

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.

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.