☰
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

The statistics Object holds statistics in the form of counters, gauges, and timing measurements.

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.

The statistics Object contains the following attributes:

Field Type Description
gauges Object of Integer [Required] Contains details for statistics gauges for the application, representing the current value of a measured item.

These statistics values are initialized to the appropriate value on first use after application startup and are lost after an application restart.

Each attribute name in this Object is the name of a statistic gauge pointing at its current value.
slice_secs Integer [Required] The number of seconds captured in each statistics slice for counters and timings.
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.
counters Object of Array of Integer [Required] Contains details for increment-by-one statistics counters for the application, representing discrete countable events separated by timed slices, regardless of any tags applied.

Each attribute name in this Object is the name of a statistic counter, pointing at an array of its values for historical timed slices.

These statistics values are initialized to zero only on first use after application startup and are lost after an application restart.

The last slice in each array has a collection start time defined by last_slice_start. The first slice in each array is the oldest slice.

The length of the slices array may be different for each statistic. This means that the first slices in each array may not typically have matching times. It is the last slices in each array which have matching times.
timings Object of Array of Array of Integer [Required] Contains details for statistics timings for the application, showing the time used (in milliseconds) for measured operations separated by timed slices, regardless of any tags applied.

Each attribute name in this Object is the name of a statistic timing pointing at an array of all of its occurrences for historical timed slices. Each occurrence is an integer showing the milliseconds measured for the relevant operation.

These statistics values are lost after an application restart.

The last slice in each array has a collection start time defined by last_slice_start. The first slice in each array is the oldest slice.

The length of the slices array may be different for each statistic. This means that the first slices in each array may not typically have matching times. It is the last slices in each array which have matching times.
timings_summary Object of Array of Object [Required] Contains summarised details for statistics timings for the application, showing the minimum, maximum, and average time used (in milliseconds) along with occurrence count for measured operations separated by timed slices, regardless of any tags applied.

Each attribute name in this Object is the name of a statistic timing pointing at an array of all of its summarised occurrences within the given timed slice. Each summary will always contain the member count, indicating the number of occurrences for the given slice. If count is positive, the members min, max, and average will also be present, showing the relevant summary time in milliseconds.

These statistics values are lost after an application restart.

The last slice in each array has a collection start time defined by last_slice_start. The first slice in each array is the oldest slice.

The length of the slices array may be different for each statistic. This means that the first slices in each array may not typically have matching times. It is the last slices in each array which have matching times.