# 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.

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)

Table 20.1: /AMPS/ClientStatus Event Message Fields

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.

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

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)

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`, `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.