☰
Navigation :

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.