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
command_queue_depth The number of pending commands.

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
authenticated_id The id used to authenticate this client, if any
bytes_in Number of bytes received.
bytes_in_per_sec Rate of bytes received.
bytes_out Number of bytes sent.
bytes_out_per_sec Rate of bytes sent.
client_name Identifier for the client, set during logon.
client_name_hash AMPS hash for the client name.
client_version Version string provided by the client.
connect_time UTC time client connection is established.
connection_name Name of the connection.
correlation_id The CorrelationId provided with the logon command, if any.
denied_reads Number of read requests which have been denied.
denied_writes Number of write requests which have been denied.
messages_in Number of messages received from client.
messages_in_per_sec Rate of messages received.
messages_out Number of messages sent to the client.
messages_out_per_sec Rate of messages sent to the client.
query_time The amount of time spent for queries from this client.
queue_depth_out Number of messages queued to be sent to client.
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.
queued_bytes_out Number of queued bytes waiting to be sent.
remote_address IP and port of the client connection.
subscription_count Number of subscriptions the client has requested.
transport_rx_queue Number of bytes in receive queue for this client.
transport_tx_queue Number of bytes in transmit queue for this client.

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
conflation_ratio Ratio representing the amount of conflation for this topic.
interval Conflation interval
message_type Message type for this topic.
topic Name of this conflating topic replica.
total_executions Total number of times the conflation algorithm has been executed.
total_time Amount of time spent processing this topic.
underlying_topic Name of the underlying topic that this topic conflates.

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.

Element Description
system_percent Percent of CPU utilization time consumed while executing kernel processes.
total_percent Total percent of CPU utilization.
user_percent Percent of CPU utilization time consumed while processing non-I/O events.

Table 4.4: 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
event The type of event logged, for example, started or shutdown.
timestamp The timestamp of the event.
version The AMPS version string for the instance that logged the event.

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
bytes_written Number of bytes written to the console.
exclude_errors Errors which are excluded from logging.
include_errors Errors which are included during logging.
log_levels Log level used to control logging output.
target Console to which logging output is directed. Default is stdout.

Table 4.6: Console Logging Statistics

file

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

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

Table 4.7: File Logging Statistics

syslog

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

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

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
caches Information about AMPS memory caches.
rss The resident set size of the AMPS process.
vmsize The virtual memory size of the AMPS process.

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
allocations Number of memory allocations for this cache.
bytes Number of bytes allocated to this cache.
description Description of the cache.
efficiency Ratio of hits to requests for this cache.
entries Number of entries in this cache.
evictions Count of evictions from this cache.
fetches Count of fetches from this cache.

Table 4.10: AMPS Instance Memory Caches

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

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

Table 4.11: AMPS Instance Paginated Sets

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
module The name of the module that implements the message type.
name The name of the message type.
options Any options provided to the module.
type The Type configured for the message type module. this configuration parameter is obsolete in 4.0 and later releases

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
denied_reads denied_writes Number of read requests which have been denied. Number of write requests which have been denied.
description Descriptor of the processor.
last_active Number of milliseconds since a processor was last active.
matches_found Number of messages found.
matches_found_per_sec Rate of messages found.
matches_found_bytes Number of bytes matched.
matches_found_bytes_ per_sec Rate of bytes matched for this processor.
messages_received Number of messages received.
messages_received_per_sec Rate of messages received.
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.

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
age_of_oldest_lease The age of the oldest current lease, in seconds.
backlog The number of leased messages awaiting acknowledgment.
expired_leases The number of leases that have expired for this queue. This counter resets when the instance is restarted.
max_backlog The configured MaxBacklog for the queue.
message_type The message type for the queue.
queue_depth Total number of unacknowledged messages in the queue.
seconds_behind Age of the oldest unacknowledged message in the queue. This counter resets when the instance is restarted.
owned Number of messages currently owned by this instance of the queue.
topic Name of the queue topic.
transferred_in The number of messages originally published to another instance that have been transferred to this instance for delivery from this queue.
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.

Table 4.15: Queues

Statistics Database Tables: IQUEUES_STATIC, IQUEUES_DYNAMIC

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

The queues resource also contains the following resource that produces information on the current live state of the queue. This information is produced directly from the internal state of AMPS, and is not recorded in the statistics database.

Element Description
details

Detailed information about the state of the queue. This information is produced in JSON format, and includes detailed internal metrics for the queue as well as the current depth of the queue and information about the individual messages at the head of the queue (up to the first 1000 messages).

This information is produced on demand from the current state, and is not produced from the statistics database.

Table 4.16: Queues Live State

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

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
authenticated_id The ID used to authenticate this connection.
bytes_out Number of bytes sent.
bytes_out_per_sec Rate of bytes sent.
client_type Specifies whether client is a replication source or destination.
connect_time Time connected to replication instance.
destination_admin_addr The admin address of the destination.
destination_group_name The group name of the destination.
destination_name The name of the destination.
disconnect_count Number of times replication destination has been disconnected.
disconnect_time Timestamp of the last time this replication destination disconnected.
is_connected Boolean telling whether replication destination is currently connected.
messages_out Number of messages sent.
messages_out_per_sec Rate of messages sent.
name Name of replication configuration.
pass_through Boolean stating whether messages can only be sent to one client, or can messages be sent on to other downstream clients.
replication_type One of either sync or async.
seconds_behind The number of seconds the destination is behind, as measured by the oldest message which has not yet been transmitted to the destination.

Table 4.17: 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.18: Replication

sow

Clicking the sow link will list all available SOW topics for the AMPS instance. Selecting a single sow topic will list the following available statistics about the sow topic:

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

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

Table 4.20: 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
backlog The current number of messages leased on this subscription. Applies to subscriptions to a queue.
client_id The ID of the subscribing client.
entitlement_filter The filter applied by the entitlement module, if any.
filter The filter requested on the subscription, if any.
is_replication Boolean value to determine if the subscription is applied to replication.
message_type Transport type of the subscription message. All return acknowledgments and messages use the same transport as the subscription.
options The options string for the subscription.
pagination_id For subscriptions that use pagination, the identifier of the paginated set for this subscription.
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.
topic Subscription topic.

Table 4.21: 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
max_timestamp The largest timestamp in the transaction log
min_timestamp The smallest timestamp in the transaction log
write_latency Statistics covering the latency of writes to the transaction log.
write_size Statistics covering the size of writes to the transaction log.

Table 4.22: 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
histogram An ASCII histogram of the monitored statistic
lower_bound The lowest observed sample of the statistic
upper_bound The largest observed sample of the statistic

Table 4.23: 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
is_enabled Indicates whether the transport is enabled.
message_type The message type for this transport.
name The name of this transport.
options The options provided for this transport.
type The type of transport.

Table 4.24: 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
NUMA Indicates whether AMPS NUMA tuning is enabled.

Table 4.25: 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
hh hours
mm minutes
ss seconds
uuuuuu microseconds

Table 4.26: 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
grouping List of one or more fields, which are used to determine message aggregation.
message_type The message type of messages produced by this view.
projection The formula defined in the AMPS config for the computed transformation of one or more fields onto a new field.
queue_depth The number of messages in the view that have not yet completed processing.
topic The name of the new AMPS topic created by this view.
underlying_topic The source topic used to compute the projected view.

Table 4.27: Views Interface

Statistics Database Tables: IVIEWS_STATIC, IVIEWS_DYNAMIC

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