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.
- Any
debug
logging will be written to STDERR if N2SVCD was run with the--debug
,--dump
, or--spam
flags. - Any
notice
orwarning
logging is always written to STDERR. - Any
notice
orwarning
logging is written to syslog ifsyslog
is configured in then2svcd.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
orwarning
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:
- Debug output will have no effect if in-memory trace logging is not enabled for the instance and STDERR debugging is not enabled.
- 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:
|
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. |