21. Event Topics¶

AMPS publishes specific events to internal topics that begin with the /AMPS/ prefix, which is reserved for AMPS only. For example, all client connectivity events are published to the internal /AMPS/ClientStatus topic. This allows all clients to monitor for events that may be of interest.

Tip

You can subscribe to an event topic using a content filter, just like any other topic within AMPS.

A client may subscribe to event topics on any connection with a message type that supports views. This includes all of the default message types and bson, but does not include the binary message type.

Messages are delivered as the message type for the connection. For example, if the connection uses JSON messages, the event topic messages will be JSON. A connection that uses FIX will receive FIX messages from an event topic.

Client Status¶

The AMPS engine will publish client status events to the internal /AMPS/ClientStatus topic whenever a client connects, issues a logon command, disconnects, enters or removes a subscription, queries a SOW or issues a sow_delete. AMPS sends a message if a client fails authentication. In addition, upon a disconnect, a client status message will be published for each subscription that the client had registered at the time of the disconnect. This mechanism allows any client to monitor what other clients are doing and is especially useful for publishers to determine when clients subscribe to a topic of interest.

To help identify clients, it is recommended that clients send a logon command to the AMPS engine and specify a meaningful client name. This client name is used to identify the client within client status event messages, logging output and information on clients within the monitoring console. The client name must be unique if a transaction log is configured for the AMPS instance.

Each message published to the client status topic will contain an event and a client_name. Depending on the event type, the message will contain other relevant fields.

For example, the following JSON document demonstrates the message for a SOW query:

{
 "ClientStatus":{
    "timestamp":"20160509T171919.976304Z",
    "event":"sow",
    "client_name":"test_client",
    "connection_name":"AMPS-Sample-any-tcp-9-242891694350073019",
    "correlation_id":null,
    "query_id":"1",
    "topic":"order",
    "filter":"/item/qty > 50",
    "options":"send_empties",
    "sub_id":"1",
    "auth_id":null,
    "entitlement_filter":null
 }
}

The table below defines the header fields which may be returned as part of the subscription messages to the /AMPS/ClientStatus topic.

*/AMPS/ClientStatus Event Message Fields*¶
FIX	XML	JSON/BSON/MsgPack	Description
20062	`Reason`	`reason`	Reason for the event (if applicable). This is present on client disconnect events to record the reason that the client disconnected.
20065	`Timestamp`	`timestamp`	Timestamp at which AMPS processed the message
20066	`Event`	`event`	Command executed by the client
20067	`ClientName`	`client_name`	Client Name
20068	`Tpc`	`topic`	Topic for the event (if applicable)
20069	`Filter`	`filter`	Filter (if applicable)
20070	`SubId`	`sub_id`	Subscription ID (if applicable)
20071	`ConnName`	`connection_name`	Internal AMPS connection name
20072	`Options`	`options`	The options for the subscription (if applicable)
20073	`QId`	`query_id`	The identifier for the query (if applicable)
20074	`CorrelationID`	`correlation_id`	The correlation ID of the command (if applicable)
20080	`ClientAddr`	`client_address`	The remote address of the client
20081	`AuthId`	`auth_id`	The authenticated identity of the client (if applicable)
20082	`EntitlementFilter`	`entitlement_filter`	The entitlement filter for the command (if applicable)

Tip

The /AMPS/ClientStatus topic is not available for protobuf, composite, binary, or struct message types.

SOW Statistics¶

AMPS can publish SOW statistics for each SOW topic which has been configured. To enable this functionality, specify the SOWStatsInterval in the configuration file. The value provided in SOWStatsInterval is the time between updates to the /AMPS/SOWStats topic.

For example, the following would be a configuration that would publish /AMPS/SOWStats event messages every 5 seconds.

<AMPSConfig>
    ...
    <SOWStatsInterval>5s</SOWStatsInterval>
    ...
</AMPSConfig>

When a SOWStatsInterval is provided, AMPS publishes a message for each topic defined in the SOW at the requested interval. These messages contain basic information about the topic. The format of the /AMPS/SOWStats messages matches the message type of the connection that has requested the messages.

For example, the following message provides information in JSON format about a topic named a-sample-topic. That topic is of message type bflat.

{
 "SOWStats":{
    "message_type":"bflat",
    "topic":"a-sample-topic",
    "record_count":15021,
    "timestamp":"20161108T225452.280650Z"
 }
}

In the SOWStats message above, message_type provides the name of the message type, topic specifies the name of the topic, record_count shows the number of records currently in the topic and timestamp includes the time the event was generated.

The table below defines the header fields which may be returned as part of the subscription messages to the /AMPS/SOWStats topic.

*/AMPS/SOWStats Event Message Default Fields*¶
FIX	XML	JSON/BSON/MsgPack	Definition
20007	`MessageType`	`message_type`	The message type of the topic
20065	`Timestamp`	`timestamp`	Timestamp in which AMPS sent the message
20066	`Topic`	`topic`	Topic that statistics are being reported on
20067	`Records`	`record_count`	Number of records in the SOW topic

For compatibility with systems that expect a consistent set of FIX tags across messages, AMPS provides a set of FIX tags that are unified with the tags used in the /AMPS/ClientStatus topic. To use the unified FIX tags, set the AMPSVersionCompliance configuration element to 5. The following table lists the unified FIX tags:

*/AMPS/SOWStats Event Message Unified Fields (Version 5)*¶
FIX	Definition
20007	The message type of the topic
20065	Timestamp in which AMPS sent the message
20068	Topic that statistics are being reported on
20075	Number of records in the SOW topic

Tip

The /AMPS/SOWStats topic is not available for protobuf, composite, binary or struct message types. (AMPS will report statistics for topics of those types, but the format for the messages that AMPS generates must be a message type that can accept arbitrary fields, not a message type that requires a single schema.)

Persisting Event Topic Data¶

By default, AMPS event topics are not persisted to the SOW. However, because AMPS event topic messages are treated the same as all other messages, the event topics can be persisted to the SOW. Providing a topic definition with the appropriate Key definition can resolve that issue by instructing AMPS to persist the messages.

The Key definition you specify must match the field name used for the message type specified in the SOW topic. That is, to track distinct records by client name for a SOW that uses json, you would use the following key:

<Key>/client_name</Key>

While to track distinct records by client name for a SOW that uses fix, you would use the following key:

<Key>/20067</Key>

For example, to persist the last /AMPS/SOWStats message for each topic in fix, json and xml format, the following Topic sections could be added to the SOW section of the AMPS configuration file:

<SOW>
    <!-- Persist /AMPS/SOWStats in FIX format -->
    <Topic>
        <Name>/AMPS/SOWStats</Name>
        <FileName>./sow/sowstats.fix.sow</FileName>
        <MessageType>fix</MessageType>
        <!-- use FIX field for the key -->
        <Key>/20066</Key>
    </Topic>

    <!-- Persist /AMPS/SOWStats in JSON format -->
    <Topic>
        <Name>/AMPS/SOWStats</Name>
        <FileName>./sow/sowstats.json.sow</FileName>
        <MessageType>json</MessageType>
        <!-- use the JSON field for the key -->
        <Key>/topic</Key>
    </Topic>

    <!-- Persist /AMPS/SOWStats in XML format -->
    <Topic>
        <Name>/AMPS/SOWStats</Name>
        <FileName>./sow/sowstats.xml.sow</FileName>
        <MessageType>xml</MessageType>
        <!-- use the XML field for the key -->
        <Key>/Topic</Key>
    </Topic>
</SOW>

Every time an update occurs, AMPS will persist the /AMPS/SOWStats message and it will be stored three times, once to the fix SOW topic, once to the json SOW topic, and once to the xml SOW topic. Each update to the respective SOW topic will overwrite the record with the same 20066, topic or Topic tag value. Doing this allows clients to now query the SOWStats topic instead of actively listening to live updates.

Table Of Contents

Related Topics

21. Event Topics¶

Client Status¶

SOW Statistics¶

Persisting Event Topic Data¶