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.