4. Instance Interface

The Instance resource provided by the AMPS monitoring interface is the administrative overview of a running AMPS instance. At a glance an administrator has access to a wide view of statistic and configuration information related to AMPS usage.

api

Selecting the api resource lists information about the AMPS internal api.

Element Description Type
command_queue_depth The number of pending commands. snapshot

Table 4.1: Client Statistics

Statistics Database Tables: IGLOBALS_STATIC, IGLOBALS_DYNAMIC

Admin path: /amps/instance/api/<metric>

clients

Selecting the clients resource will list all connected clients by name. Selecting a single client will grant the user the ability to view various properties regarding a client.

Element Description Type
authenticated_id The id used to authenticate this client, if any fixed
bytes_in Number of bytes received. cumulative
bytes_in_per_sec Rate of bytes received. interval average
bytes_out Number of bytes sent. cumulative
bytes_out_per_sec Rate of bytes sent. interval average
client_name Identifier for the client, set during logon. fixed
client_name_hash AMPS hash for the client name. fixed
client_version Version string provided by the client. fixed
connect_time UTC time client connection is established. fixed
connection_name Name of the connection. fixed
correlation_id The CorrelationId provided with the logon command, if any. fixed
denied_reads Number of read requests which have been denied. cumulative
denied_writes Number of write requests which have been denied. cumulative
messages_in Number of messages received from client. cumulative
messages_in_per_sec Rate of messages received. interval average
messages_out Number of messages sent to the client. cumulative
messages_out_per_sec Rate of messages sent to the client. interval average
query_time The amount of time spent for queries from this client. cumulative
queue_depth_out

Number of messages queued to be sent to client.

This represents a count of the messages that AMPS cannot write to the outgoing socket due to the transmit buffer being full. This does not count messages already written to the transmit buffer. (The transport_tx_queue has information about the transmit buffer.)

snapshot
queue_max_latency

The age of the oldest item in the queue which has not yet been sent. This is used as a measure of how far behind AMPS believes a subscribing client is.

This measures the age of the oldest message that AMPS cannot write to the outgoing socket due to the transmit buffer being full. This does not count messages already written to the transmit buffer. (The transport_tx_queue has information about the transmit buffer.)

The latency is measured in seconds at the resolution of the system clock.

snapshot
queued_bytes_out

Number of queued bytes waiting to be sent.

This represents a count of the number of bytes that AMPS cannot write to the outgoing socket due to the transmit buffer being full. This does not count messages already written to the transmit buffer (transport_tx_queue will show messages written to the transmit buffer that have not yet been sent).

snapshot
remote_address Address and port of the remote side of the client connection. fixed
subscription_count Number of subscriptions currently active for the client. snapshot
transport_rx_queue Number of bytes in the transport receive buffer (typically the TCP buffer) for this client. This measures messages arriving from the client. snapshot
transport_tx_queue Number of bytes in transport transmit buffer (typically the TCP buffer) for this client. This measures messages being sent to the client. snapshot

Table 4.2: Client Statistics

Statistics Database Tables: ICLIENTS_STATIC, ICLIENTS_DYNAMIC

Admin path: /amps/instance/clients/<id>/<metric>

config.xml

Selecting this will display the current AMPS configuration file. To keep the path consistent, AMPS provides the file under the config.xml path, regardless of the actual name of the file.

Admin path: /amps/instance/config.xml

config_path

Filesystem location of the configuration file.

Admin path: /amps/instance/config_path

conflated_topics

Selecting the conflated_topics resource will display a list of the conflated topics in the instance.

Element Description Type
conflation_ratio Ratio representing the amount of conflation for this topic. running average
interval Conflation interval fixed
message_type Message type for this topic. fixed
topic Name of this conflating topic replica. fixed
total_executions Total number of times the conflation algorithm has been executed. cumulative
total_time Amount of time spent processing this topic. cumulative
underlying_topic Name of the underlying topic that this topic conflates. fixed

Table 4.3: Conflated Topics

Statistics Database Tables: ICONFLATEDTOPICS_STATIC, ICONFLATEDTOPICS_DYNAMIC

Admin path: /amps/instance/conflated_topics/<id>/<metric>

cpu

The CPU resource lists properties related to overall CPU usage of the AMPS instance. Selecting the items below give more specific information to the type of CPU utilization being consumed by the AMPS process.

Notice that AMPS also collects metrics for the overall host system, available in the host resources.

Element Description Type
system_percent Percent of CPU utilization time consumed while executing kernel processes on behalf of this AMPS instance. snapshot
total_percent Total percent of CPU utilization on behalf of this AMPS instance. snapshot
user_percent Percent of CPU utilization time consumed while processing non-I/O events on behalf of this AMPS instance. snapshot

Table 4.4: Instance CPU Statistics

Statistics Database Tables: ICPUS_STATIC, ICPUS_DYNAMIC

Admin path: /amps/instance/cpu/<metric>

cwd

The current working directory from which the AMPS instance was invoked.

Admin path: /amps/instance/cwd

description

The contents of the Description element in the configuration file.

Admin path: /amps/instance/description

environment

The contents of the Environment element in the configuration file.

Admin path: /amps/instance/environment

lifetimes

Information about the lifetime of the AMPS instance, including historical information if stats.db is persisted. Each time an event related to startup or shutdown is logged, AMPS creates an entry in this resource. Each entry contains the following statistics:

Element Description Type
event The type of event logged, for example, started or shutdown. fixed
timestamp The timestamp of the event. fixed
version The AMPS version string for the instance that logged the event. fixed

Table 4.5: Lifetimes Statistics

Statistics Database Tables: ILIFETIMES_STATIC, ILIFETIMES_DYNAMIC

Admin path: /amps/instance/lifetimes/<identifier>/<metric>

logging

The logging resource contains information about the resources consumed during various AMPS logging processes. Selecting a logging mechanism (console, file or syslog) will first list all logs of that particular type. Drilling down into one of those logs will pull up more granular information about logging. If a logging mechanism is not defined in the configuration, then the results will be blank when the logging resource is selected.

Statistics Database Tables: ICONSOLE_LOGGERS_STATIC, ICONSOLE_LOGGERS_DYNAMIC, IFILE_LOGGERS_STATIC, IFILE_LOGGERS_DYNAMIC, ISYSLOG_LOGGERS_STATIC, ISYSLOG_LOGGERS_DYNAMIC

Admin path: /amps/instance/logging/<type>/<identifier>/<metric>

console

Below are the options available for reporting when console logging is enabled.

Element Description Type
bytes_written Number of bytes written to the console. cumulative
exclude_errors Errors which are excluded from logging. fixed
include_errors Errors which are included during logging. fixed
log_levels Log level used to control logging output. fixed
target Console to which logging output is directed. Default is stdout. fixed

Table 4.6: Console Logging Statistics

file

Below are the options available for reporting when file logging is enabled.

Element Description Type
bytes_written Number of bytes written to the log. cumulative
exclude_errors Errors which are excluded from logging. fixed
file_name File defined in the configuration file where the log file is written to. fixed
file_name_mask Mask of the logging output file name, if available. fixed
file_system_free_percent Percentage of free space on the file system that contains the file. snapshot
include_errors Errors which are included during logging. fixed
log_levels Log level used to control logging output. fixed
rotation Boolean representation denoting if log rotation is turned on. fixed
rotation_threshold Log size at which log rotation will occur. fixed

Table 4.7: File Logging Statistics

syslog

Below are the options available for reporting when syslog logging is enabled

Element Description Type
bytes_written Number of bytes written to syslog. cumulative
exclude_errors Errors which are excluded from logging. fixed
facility Integer enumeration of the logging facility used by syslog. fixed
ident Syslog name of the logging instance. fixed
include_errors Errors which are included during logging. fixed
log_levels Log level used to control logging output. fixed
logopt Bitfield of possible log options included. These values are configured in the configuration file in the <Options> tag. fixed

Table 4.8: System Logging Statistics

memory

AMPS can provide information regarding the process’s memory usage in its RSS and VMSize via the memory resource in the monitoring interface.

Element Description Type
caches Information about AMPS memory caches. (see caches)
paginations Information about paginated result sets. (see paginations)
rss The resident set size of the AMPS process. snapshot
vmsize The virtual memory size of the AMPS process. snapshot

Table 4.9: AMPS Instance Memory

Statistics Database Tables: IMEMORY_STATIC, IMEMORY_DYNAMIC, IMEMORY_CACHES_STATIC, IMEMORY_CACHES_DYNAMIC

Admin path: /amps/instance/memory/<metric>, /amps/instance/memory/caches/<identifier>/*<metric>, /amps/instance/memory/paginations/<metric>

The caches element provides information about currently-active memory caches:

Element Description Type
allocations Number of memory allocations for this cache. cumulative
bytes Number of bytes allocated to this cache. snapshot
description Description of the cache. fixed
efficiency Ratio of hits to requests for this cache. snapshot
entries Number of entries in this cache. snapshot
evictions Count of evictions from this cache. cumulative
fetches Count of fetches from this cache. cumulative

Table 4.10: AMPS Instance Memory Caches

Statistics Database Table: IMEMORY_CACHES

The paginations element provides information about currently-active paginated subscriptions in AMPS.

Element Description Type
memory_bytes Number of bytes consumed to maintain this paginated set. snapshot
message_type Message type for this paginated set. fixed
subscription_count Number of subscriptions using this paginated set. snapshot
topic Source topic for this paginated set. fixed

Table 4.11: AMPS Instance Paginated Sets

Statistics Database Table: IPAGINATIONS

message_types

Information regarding the message types used by AMPS are maintained in the message_types resource. AMPS can track the following information for all message types loaded into the instance.

Element Description Type
module The name of the module that implements the message type. fixed
name The name of the message type. fixed
options Any options provided to the module. fixed
type The Type configured for the message type module. this configuration parameter is obsolete in 4.0 and later releases (obsolete)

Table 4.12: AMPS Instance Message Types

Admin path: /amps/instance/message_type/<identifier>/<metric>

name

Name of the AMPS Instance.

Admin path: /amps/instance/name

name_hash

The hashed value of the AMPS Instance name.

Admin path: /amps/instance/name_hash

pid

The process ID of the current ampServer process.

Admin path: /amps/instance/pid

processors

Selecting the processors resource will list all the available message processors that the AMPS instance has invoked to handle messages. Each AMPS message processor will be listed individually, or selecting the all resource will list an aggregate of the available message processors. All AMPS message processors have the following attributes available:

Element Description Type
denied_reads Number of read requests which have been denied. cumulative
denied_writes Number of write requests which have been denied. cumulative
description Descriptor of the processor. fixed
last_active Number of seconds since a processor was last active. snapshot
matches_found Number of messages found. cumulative
matches_found_per_sec Rate of messages found. interval average
matches_found_bytes Number of bytes matched. cumulative
matches_found_bytes_ per_sec Rate of bytes matched for this processor. interval average
messages_received Number of messages received. cumulative
messages_received_per_sec Rate of messages received. interval average
messages_received_bytes_per_sec Rate of bytes received for this processor. interval average
throttle_count

Number of times the processor had to wait to add a message to the processing pipeline due to the instance reaching capacity limits on the number of in-progress messages.

This metric can indicate resource constraints on AMPS.

cumulative

Table 4.13: AMPS Message Processors

AMPS also includes information for the following processing types, presented as an entry for a message processor with the given name:

Name Description
bookmark Messages from transaction log replays (bookmark subscriptions).
detached Messages related to subscriptions that hold messages before delivering them (such as conflated subscriptions, aggregated subscriptions, and subscriptions that use pagination.
external Messages to and from regular publish/subscribe subscriptions (that is, not SOW queries, message queue subscriptions, or transaction log replays).
internal Messages internally generated by AMPS
queue Messages to and from message queues.
replication Messages to and from replication destinations.
sow Messages from queries of a SOW topic.

Table 4.14: AMPS Message Processor Types

Statistics Database Tables: IPROCESSORS_STATIC, IPROCESSORS_DYNAMIC

Admin path: /amps/instance/processors/<identifier>/<metric>

queues

The queues resource lists available information regarding the queues defined for this instance.

Element Description Type
age_of_oldest_lease The age of the oldest current lease, in microseconds. snapshot
backlog The number of leased messages awaiting acknowledgment. snapshot
expired_leases The number of leases that have expired for this queue. This counter resets when the instance is restarted. cumulative
max_backlog The configured MaxBacklog for the queue. fixed
message_type The message type for the queue. fixed
queue_depth Total number of unacknowledged messages in the queue. snapshot
seconds_behind

Age of the oldest unacknowledged message in the queue. This counter resets when the instance is restarted.

This statistic is measured in seconds, at the resolution of the system clock.

snapshot
owned Number of messages currently owned by this instance of the queue. snapshot
proxied_transfer Status of the enable proxied transfer setting. fixed
topic Name of the queue topic. fixed
transferred_in The number of messages originally published to another instance that have been transferred to this instance for delivery from this queue. cumulative
transferred_out The number of messages originally published to this instance that have been transferred to another instance for delivery from the replicated instance of this queue. cumulative

Table 4.15: Queues

Statistics Database Tables: IQUEUES_STATIC, IQUEUES_DYNAMIC

Admin path: /amps/instance/queues/<identifier>/<metric>

queries

The queries resource lists all available information regarding the query messages sent to AMPS.

queued_queries

A count of all queries which have not yet completed processing.

Admin path: /amps/instance/queries/<metric>

replication

Selecting the replication resource will display a list of available downstream replication instances used by this instance of AMPS. Selecting an individual replication instance will display the following statistics.

Element Description Type
authenticated_id The ID used to authenticate this connection. fixed
bytes_out Number of bytes sent to this destination. cumulative
bytes_out_per_sec Rate of bytes sent. interval average
client_name The client name used for this destination. fixed
client_type Specifies whether client is a replication source or destination. fixed
connect_time Time connected to this destination. snapshot
destination_admin_addr The admin address of the destination. fixed
destination_group_name The group name of the destination. fixed
destination_name The name of the destination. fixed
disconnect_count Number of times replication destination has been disconnected. cumulative
disconnect_time Timestamp of the last time the replication destination disconnected. snapshot
is_connected Boolean telling whether replication destination is currently connected. snapshot
messages_out Number of messages sent to this destination. cumulative
messages_out_per_sec Rate of messages sent to this destination. interval average
name Name of replication configuration. fixed
pass_through Boolean stating whether messages received via replication can be forwarded on this connection. fixed
replication_type One of either sync or async. snapshot
seconds_behind

The current fully-acknowledged replay point for this destination, as measured by the age of the oldest message in the transaction log that has not yet been acknowledged by the destination.

This metric tracks acknowledgements from the downstream instance. These acknowledgements indicate that the downstream instance considers the message to be persisted locally and to any sync destinations that the downstream instance would replicate to (see the AMPS User Guide for details). This metric is useful for detecting pauses or delays in replication acknowledgements, but does not, by itself, indicate whether messages have been delivered to subscribers from a downstream instance.

When the connection is active, the seconds_behind metric will, by definition, lag behind the point at which messages have been transmitted to the downstream instance. However, AMPS does not consider messages to have been successfully replicated until the downstream instance acknowledges them.

snapshot

Table 4.16: Replication

Statistics Database Tables: IREPLICATIONS_STATIC, IREPLICATIONS_DYNAMIC

Admin path: /amps/instance/replication/<identifier>/<metric>

The replication resource also provides options for managing replication instances. The following management functions are available.

Element Description
downgrade Change the replication type of this connection from sync to async.
reconnect Close and reopen the connection to the remote instance.

Table 4.17: Replication

sow

Clicking the sow link will list all available topics in the state of the world for this AMPS instance. Selecting a single topic will list the following available statistics about the topic.

Element Description Type
delete_count Number of deletes processed by the SOW. cumulative
deletes_per_sec Number of deletes per second processed by the SOW. interval average
device Device the topic is stored on, if applicable. fixed
historical_granularity The granularity at which the SOW maintains history for this topic (if set). fixed
historical_window The window for which the SOW maintains history for this topic (if set). fixed
insert_count Count of the number of new records inserted into this topic. cumulative
inserts_per_sec Rate of inserts into this topic. interval average
memory_bytes The number of bytes of memory used for this topic. snapshot
mmaps The number of memory maps used for this topic in the SOW. snapshot
message_type Message type for this topic. fixed
path File system location of the SOW topics file store. fixed
queries_per_sec Rate of queries for this SOW topic. interval average
query_count Number of queries processed for this topic. cumulative
record_size Configured record size for the topic in the SOW. fixed
resident_percent Percentage of the storage of this topic that is currently resident in memory. snapshot
stored_bytes Number of bytes stored for this topic. snapshot
topic Name of this SOW topic. fixed
update_count Number of updates to existing records processed by this topic. cumulative
updates_per_sec Number of updates to existing records per second. interval average
valid_keys Number of distinct messages in the SOW - defined by the SOW topic key. snapshot

Table 4.18: SOW Interface

Statistics Database Tables: ISOW_STATIC, ISOW_DYNAMIC

Admin path: /amps/instance/sow/<identifier>/<metric>

statistics

The statistics resource contains information regarding how AMPS monitors its own statistics.

Element Description Type
disk_per_sample Amount of storage the stats database has grown since the last sample interval. snapshot
file_name Location where statistics are stored. Default is :memory:, which stores the statistics database in system memory. fixed
file_size Size on disk of the statistics database. snapshot
interval Time in milliseconds between statistics database updates. fixed
memory_used Size in bytes of the system memory consumption of the statistics database. snapshot
queries Number of queries processed from the statistics database. cumulative
time_per_sample Time taken to process each statistics database query. snapshot
total_commit_time Total amount of time spent committing statistics information to the database. cumulative
total_samples Number of statistics database updates that have taken place since the AMPS server started. cumulative
total_time Total amount of time spent publishing statistics, including the commit time, since the AMPS server started. cumulative

Table 4.19: Statistics Interface

Statistics Database Tables: ISTATISTICS_STATIC, ISTATISTICS_DYNAMIC

Admin path: /amps/instance/statistics/<metric>

subscriptions

Each client that submits a subscribe command message is tracked by AMPS, and their relevant metrics are captured in the monitoring instance database. Selecting the subscriptions resource lists the available subscribers. Selecting a subscriber will list the available statistics below:

Element Description Type
backlog The current number of messages leased on this subscription. Applies to subscriptions to a queue. snapshot
bookmark The bookmark the client provided when the subscription was entered, if any. fixed
client_id The ID of the subscribing client. fixed
entitlement_filter

The filter applied to this subscription by the entitlement module, if any.

(Since a regular expression subscription can have multiple entitlement filters, one for each matching topic, this is blank for subscriptions that use a regular expression for the topic name.)

fixed
filter The filter requested on the subscription, if any. fixed
message_type Transport type of the subscription message. All return acknowledgments and messages use the same transport as the subscription. fixed
options The options string for the subscription. fixed
pagination_id For subscriptions that use pagination, the identifier of the paginated set for this subscription. fixed
seconds_behind For bookmark subscriptions, the age of the last message enqueued for the client. This indicates the point in the transaction log at which replay is currently happening, and does not necessarily correspond to the rate at which the client is receiving messages or the amount of time required for the client to complete replay. snapshot
sub_id The subscription id for this subscription. fixed
topic Subscription topic. fixed

Table 4.20: Subscriptions Interface

Statistics Database Tables: ISUBSCRIPTIONS_STATIC, ISUBSCRIPTIONS_DYNAMIC

Admin path: /amps/instance/subscriptions/<id>/<metric>

timestamp

The timestamps of the historical admin statistics intervals as recorded by AMPS. The interval between these timestamps is determined by the AMPS Admin Interval configuration value.

These values can be used to ensure valid results are returned from a Historical Time Based Selection

All times used for the report generation and presentation are ISO- 8601 formatted. ISO-8601 formatting is of the following form: YYYYMMDDThhmmss, where YYYY is the year, MM is the month, DD is the year, T is a separator between the date and time, hh is the hours, mm is the minutes and ss is the seconds. Decimals are permitted after the ss units.

All times used for the report generation and presentation are stored and returned in UTC time.

Admin path: /amps/instance/timestamp

transaction_log

Clicking the transaction_log link will display the statistics that AMPS gathers for the transaction log, if one is configured.

Element Description Type
max_timestamp The largest timestamp in the transaction log snapshot
min_timestamp The smallest timestamp in the transaction log snapshot
write_latency Statistics covering the latency of writes to the transaction log. snapshot
write_size Statistics covering the size of writes to the transaction log. snapshot

Table 4.21: Transaction Log Interface

Statistics Database Tables: ITRANSACTION_LOG_DYNAMIC, ITRANSACTION_LOG_STATIC, ITRANSACTION_WRITE_LATENCY_DYNAMIC, ITRANSACTION_LOG_WRITE_LATENCY_STATIC, ITRANSACTION_WRITE_SIZE_DYNAMIC, ITRANSACTION_LOG_WRITE_SIZE_STATIC

Admin path: /amps/instance/transaction_log/<metric>

The write_latency and write_size metrics contain the following details:

Element Description Type
histogram An ASCII histogram of the monitored statistic snapshot
lower_bound The lowest observed sample of the statistic snapshot
upper_bound The largest observed sample of the statistic snapshot

Table 4.22: Transaction Log Statistic Details

transports

Clicking the transports link will give a list of the transports defined in the configuration file for the AMPS instance. Clicking a view will display the detailed resources for views.

Element Description Type
is_enabled Indicates whether the transport is enabled. snapshot
message_type The message type for this transport. fixed
name The name of this transport. fixed
options The options provided for this transport. fixed
type The type of transport. fixed

Table 4.23: Transports Interface

Statistics Database Tables: ITRANSPORTS_STATIC, ITRANSPORTS_DYNAMIC

Admin path: /amps/instance/transports/<id>/<metric>

tuning

Clicking the tuning link will give a list of the tuning parameters for the instance. Clicking a parameter will give the current value for the instance.

Element Description Type
NUMA Indicates whether AMPS NUMA tuning is enabled. fixed

Table 4.24: Tuning Interface

Admin path: /amps/instance/tuning/<metric>

uptime

The length of time that the AMPS instance has been running, which conforms to a hh:mm:ss.uuuuuu format. This format is explained in the table below.

Element Description Type
hh hours snapshot
mm minutes snapshot
ss seconds snapshot
uuuuuu microseconds snapshot

Table 4.25: Time formatting used in uptime

Admin path: /amps/instance/uptime

user_id

The username for the owner for the ampServer process.

Admin path: /amps/instance/user_id

version

Version of the current running instance of AMPS.

Admin path: /amps/instance/version

views

Clicking the views link will give a list of the views defined in the configuration file for the AMPS instance. Clicking a view will display the detailed resources for views.

Element Description Type
conflation The inline conflation mode of the view. fixed
conflation_ratio The ratio of incoming to conflated updates. snapshot
grouping List of one or more fields, which are used to determine message aggregation. fixed
message_type The message type of messages produced by this view. fixed
projection The formula defined in the AMPS config for the computed transformation of one or more fields onto a new field. fixed
queue_depth The number of updates to the view that are pending, but have not yet been applied. snapshot
topic The name of the new AMPS topic created by this view. fixed
underlying_topic The source topic used to compute the projected view. fixed

Table 4.26: Views Interface

Statistics Database Tables: IVIEWS_STATIC, IVIEWS_DYNAMIC

Admin path: /amps/instance/views/<id>/<metric>