20. 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.
Event topic messages can be subscribed with content filters 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 with 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
}
}
Table 20.1 defines the header fields which may be returned as
part of the subscription messages to the /AMPS/ClientStatus
topic.
FIX | XML | JSON / BSON | Definition |
---|---|---|---|
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) |
Table 20.1: /AMPS/ClientStatus Event Message Fields
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, the timestamp
field includes the time
the event was generated, topic
specifies the name of the topic,
message_type
provides the name of the message type, and records
shows the number of records currently in the topic.
Table 20.2 defines the header fields which may be returned as
part of the subscription messages to the /AMPS/SOWStats
topic.
FIX | XML | JSON/BSON | 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 |
Table 20.2: /AMPS/SOWStats Event Message Default Fields
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:
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 |
Table 20.3: /AMPS/SOWStats Event Message Unified Fields (Version 5)
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
, xml
and json
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 xml
SOW topic, and once to the json
SOW
topic. Each update to the respective SOW topic will overwrite the record
with the same Topic
, topic
or 20066
tag value. Doing this
allows clients to now query the SOWStats
topic instead of actively
listening to live updates.