Summary Messages
Introduction
Management summary messages pass between the ManageApp and any other application (including itself) to request and return an application summary for the purposes of run-time administration.
!MANAGEMENT-SUMMARY-REQUEST
The !MANAGEMENT-SUMMARY-REQUEST message is sent by ManageApp to any application
(including itself and the WatchdogApp) in order to determine that application’s
current configuration and resource allocation.
The !MANAGEMENT-SUMMARY-REQUEST message has no attributes.
!MANAGEMENT-SUMMARY-RESPONSE
The !MANAGEMENT-SUMMARY-REQUEST is returned by an application in response to an
inbount !MANAGEMENT-SUMMARY-REQUEST message.
The attributes of the MANAGEMENT-SUMMARY-RESPONSE message are:
Field
Type
Description
success
0/1
[Required] Indicates if the management summary request was successful.
shutdown_level
0/1/2
[Required] The application’s current shutdown level
0 = None, 1 = Pending, 2 = Shutdown.
configuration
Object
Container for scalar and vector configuration values on this application.
.scalars
Array
An Array of Objects representing application scalar configuration values. See documentation below.
.vectors
Array
An Array of Objects representing application vector configuration values. See documentation below.
resource
Array
Container for scalar and vector resource values on this application.
.scalars
Array
An Array of Objects representing application scalar resource values. See documentation below.
.vectors
Array
An Array of Objects representing application vector resource values. See documentation below.
statistics
Array
An Array of Objects representing current application Statistics counters. See documentation below.
poll_stats
Object
A container for timing information regarding recent polling/work-loop timing.
.total
Integer
Total number of milliseconds covered by these polling-loop statistics.
The default poll-reporting period is approximately 3000ms, but may change.
.poll_all
Integer
Total number of milliseconds spent “working” across all applications within this process.
When running n2svcd in –multi mode then this will include only one application.
.poll_app
Integer
Total number of milliseconds spent “working” for this application.
When running n2svcd in –multi (multi-process) mode, poll_app = poll_all.
.sleep
Integer
Total number of milliseconds that this process spent in “sleep” calls.
Note that total = poll_all + sleep subject to potential rounding error.
Configuration/Resource Scalars
Each Object in the Array of configuration.scalar entries for a managed application
represents a scalar configuration value associated with the application. Configuration
scalars are defined in a configuration file or database, and/or are expressly managed
by an administrator.
Each Object in the Array of resource.scalar entries for a managed application
represents a scalar resource value associated with the application. Resource
scalars are values which vary according to the current behavior of the application,
e.g. the size of a working cache in megabytes, the time of the last flush to disk,
or other such operational indicators.
Both concepts use a common data structure, with minor differences. Each
configuration.scalar or resource.scalar entry has the following attributes:
Field
Type
Description
key
String
[Required] A unique key for this configuration/resource attribute.
name
String
[Required] A human-readable name for the configuration/resource attribute.
value
String
The configuration/resource current value, which may be
undef.
type
choice/ string/ integer/ boolean
Indicates the underlying type for this scalar. This may be used to decide how to render the value visually.
When a configuration scalar is also editable, then it implies data entry checking rules.
choice entries should also have a values list of permitted values.
string entries have no special formatting, and are typically left-aligned.
integer entries have no special formatting, and are typically center-aligned.
boolean entries have value = 0/1/undef, displayed as “YES”/“NO”/“”, center-aligned.
(Default = string)
description
String
Optional “help text” for this configuration scalar.
editable
0/1
For configuration entries only. The value may be edited by an authorized administrator.
A scalar value or vector column must also have a defined type in order for it to be considered editable.
(Default = scalar value or vector column is not editable)
default
Scalar
Optional suggested default value for administration GUI to initialise for new configuration vector entries.
values
Array of String
For configuration scalars of
type = choice. The list of permitted values for this field.
(Default = constraint cannot be checked)
minlen
Integer
For configuration scalars of
type = string, minimum length in characters for new value.
(Default = No minimum length for string, empty string is permitted)
maxlen
Integer
For configuration scalars of
type = string, maximum length in characters for new value.
(Default = No maximum length for string)
min
Integer
For configuration scalars of
type = integer, minimum integer value for new value.
(Default = 0, any non-negative value may be provided)
max
Integer
For configuration scalars of
type = integer, maximum integer value for new value.
(Default = not specified, any maximum value may be provided)
Note that a scalar value or vector column denoted here as “editable” means that the application
may allow the value to be changed (subject to sanity and consistency checks) via messages
sent over the internal message bus. However, any application (such as the ManageApp)
which is providing an external HTTP interface should perform additional security
checks before sending these internal messages.
Configuration/Resource Vectors
Each Object in the Array of configuration.vectors for a managed application represents
a static vector of configuration rows associated with the application. Configuration
vectors are defined in a configuration file or database, and/or are expressly managed
by an administrator.
Each Object in the Array of resource.vectors for a managed application represents a
resource vector, i.e. a table of resource values dynamically assigned by the system during
run-time, as a side-effect of the platform functions.
Each configuration.vectors or resource.vectors entry has the following attributes:
Field
Type
Description
key
String
[Required] A unique key for this configuration/resource vector.
name
String
[Required] A human-readable name for the configuration/resource vector.
count
Integer
[Required] The number of rows in this configuration/resource vector.
drillable
0/1
Does the application support detailed drilldown on this configuration/resource vector?
(Default = 0, drilldown is not available)
status
idle / active / overload
Applies to resource vectors only. When
active, indicates that this resource
is currently being used for current or recent processing. When overload
indicates that the resource is currently or recently exceeding its maximum capacity.
(Default = idle)
Statistics Entries
Each Object in the Array of statistics entries for a managed application represents a
statistics increment-by-one event counter within the application. These statistics values
are initialized to zero on first use after application startup. Counter values will be
lost after an application restart.
These statistics are primarily designed to be relayed via StatsD “graphite-format” to a dedicated statistic management application. This API access is a secondary feature for “ad hoc” administration and management purposes.
Each statistics Array entry has the following attributes:
Field
Type
Description
slice_secs
Integer
[Required] The number of seconds captured in each statistics slice.
names
Array of String
[Required] An array containing the names of all statistics counters being reported.
last_slice_start
Integer
[Required] The epoch time for the start of the last slice in each statistics slices list.
Note that the last slice in each array is still collecting new statistics, and for this reason
you may wish to exclude it from any graphing or reporting display.
slices
Object of Array
[Required] Each attribute name in this Object is the name of a statistic counter.
Each value is an array of slices. The last slice in this array has a collection start
time defined by last_slice_start. The first slice in each array is the oldest slice.
Note: A slice value of null indicates that no statistics capture occurred during this interval.
By contrast, a slice value of 0 may indicate that the statistic was incremented and then decremented.
Note: The length of the slices array will typically be different for each statistic counter, as
null statistics slices will be discarded.
This means that the first slices in each array will not typically have matching times. It is the last slices in each array which have matching times.