Subscribing to Message Bus Events

To receive event messages published on the router message bus, an application must use connect to the Message VPN where the event occurs and subscribe to the associated event topic.

The table below summarizes the standard event message topics and texts for each type of standard event message, while the following sections provide the details:

Note:   

  • An application can receive all published events on a Message VPN by subscribing to:

    #LOG/> (when events are published using SMF topic syntax)
    or
    $SYS/LOG/#
    (when events are published using MQTT topic syntax)

    Note that subscriptions to event message topics are a direct topic match. For example, an application subscribing to #LOG/WARNING/> receives event messages for the WARNING level only, not ones of higher or lower level severity.

  • An application can receive all subscribe and unsubscribe events on a Message VPN, but not receive any other event messages, by subscribing to:

    #LOG/INFO/SUB*/> (when events are published using SMF topic syntax)
    or
    $SYS/LOG/INFO/SUB_ADD/# and $SYS/LOG/INFO/SUB_DELETE/# (when events are published using MQTT topic syntax)

  • All router event logs, and all published events (except for subscribe and unsubscribe events), include a timestamp in ISO 8601 format.

Summary of Standard Event Message Topics and Text

Event Type

Topic

Message Text

System

#LOG/<level>/SYSTEM/<routerName>/<eventName>

$SYS/LOG/<level>/SYSTEM/<routerName>/<eventName>

SYSTEM:  eventName: -  - descriptiveText

Message-VPN

#LOG/<level>/VPN/<routerName>/<eventName>/<vpnName>

$SYS/LOG/<level>/VPN/<routerName>/<eventName>/<vpnName>

VPN:  eventName:  vpnName  - descriptiveText

Client

#LOG/<level>/CLIENT/<routerName>/<eventName>/<vpnName>/<ClientName>

$SYS/LOG/<level>/CLIENT/<routerName>/<eventName>/<vpnName>/<ClientName>

CLIENT:  eventName:  vpnName ClientName  descriptiveText

Subscribe

#LOG/INFO/SUB_ADD/<subscribedTopic>

$SYS/LOG/INFO/SUB_ADD/<subscribedTopic>

SUBSCRIPTION_ADD subscribedTopic

Unsubscribe

#LOG/INFO/SUB_DEL/<subscribedTopic>

$SYS/LOG/INFO/SUB_DEL/<subscribedTopic>

SUBSCRIPTION_DELETE subscribedTopic

System Event Topics

To receive system scope events from the router message bus when events are published using SMF topic syntax, subscribe to:

#LOG/<level>/SYSTEM/<routerName>/<eventName>

To receive system scope events from the router message bus when events are published using MQTT topic syntax, subscribe to:

$SYS/LOG/<level>/SYSTEM/<routerName>/<eventName>

Where:

<level> is the message event severity level: crit, err, warning, notice, or info. Refer to Monitoring Events Using Syslog for details.

<routerName> is the name of the router where the event occurred.

<eventName> is the name of the event message as listed and described in SolOS Event Reference.

Example:

#LOG/INFO/SYSTEM/rtr215/SYSTEM_CHASSIS_FAN_HIGH

Both the event log text, and the published message text, are formatted as follows:

timestamp  level  routerName  SYSTEM:  eventName: -  - descriptiveText

Example:

2008-05-24T09:40:41-0400 <local3.info> rtr215 SYSTEM: SYSTEM_CHASSIS_FAN_HIGH:  -  -  Fan 1 speed high threshold exceeded

To receive all system scope events from the router message bus when events are published using SMF topic syntax, subscribe to:

#LOG/*/SYSTEM/>

To receive all system scope events from a particular router when events are published using SMF topic syntax, subscribe to:

#LOG/*/SYSTEM/<routerName>/>

To receive all system scope events from the router message bus when events are published using MQTT topic syntax, subscribe to:

$SYS/LOG/+/SYSTEM/#

To receive all system scope events from a particular router when events are published using MQTT topic syntax, subscribe to:

$SYS/LOG/+/SYSTEM/<routerName>/#

Message VPN Event Topics

Message VPN events will be published according to the topic formats (SMF or MQTT) selected for event publishing. Refer to Setting a Topic Format for Published Events for more information.

To receive Message VPN scope events published using SMF topic syntax from the router message bus, subscribe to:

#LOG/<level>/VPN/<routerName>/<eventName>/<vpnName>

To receive Message VPN scope events published using MQTT topic syntax from the router message bus, subscribe to:

$SYS/LOG/<level>/VPN/<routerName>/<eventName>/<vpnName>

Where:

<level> is the message event severity level: crit, err, warning, notice, or info. Refer to Monitoring Events Using Syslog for details.

<routerName> is the name of the router where the event occurred.

<eventName> is the name of the event message as listed and described in SolOS Event Reference.

<vpnName> is the name of the Message VPN where the event occurred

Example:

#LOG/INFO/VPN/rtr215/VPN_VPN_EG_MSG_RATE_HIGH/blue

Both the event log text, and the published message text, are formatted as follows:

timestamp  level  routerName   VPN:  eventName:  vpnName  - descriptiveText

Example:

2008-05-24T09:40:41-0400 <local3.info> rtr215  VPN:  MSG_RATE: blue  -  Maximum message rate threshold exceeded

To receive all Message VPN scope events published using SMF topic syntax from the router message bus, for the Message VPN to which the client is connected, subscribe to:

#LOG/*/VPN/>

To receive all Message VPN scope events published using SMF topic syntax from a particular router, for the Message VPN to which the client is connected, subscribe to:

#LOG/*/VPN/<routerName>/>

To receive all Message VPN scope events published using MQTT topic syntax from the router message bus, for the Message VPN to which the client is connected, subscribe to:

$SYS/LOG/+/VPN/#

To receive all Message VPN scope events published using MQTT topic syntax from a particular router, for the Message VPN to which the client is connected, subscribe to:

$SYS/LOG/+/VPN/<routerName>/#

Client Event Topics

To receive client scope events published using SMF topic syntax from the router message bus, on a per‑client basis, subscribe to:

#LOG/<level>/CLIENT/<routerName>/<eventName>/<vpnName>/<clientName>

To receive client scope events published using MQTT topic syntax from the router message bus, on a per‑client basis, subscribe to:

$SYS/LOG/<level>/CLIENT/<routerName>/<eventName>/<vpnName>/<clientName>

Where:

<level> is the message event severity level: crit, err, warning, notice, or info. Refer to Monitoring Events Using Syslog for details.

<routerName> is the name of the router where the event occurred.

<eventName> is the name of the event message as listed and described within the SolOS Event Reference.

<vpnName> is the name of the associated Message VPN where the event occurred.

<clientName> is the name of the associated client where the event occurred.

Example:

#LOG/INFO/CLIENT/rtr215/CLIENT_CLIENT_EGRESS_MSG_DISCARD/blue/host83/12401/#0001

Both the event log text, and the published message text, are formatted as follows:

timestamp  routerName  CLIENT:  eventName:  vpnName clientName descriptiveText

Example:

2008-05-24T09:40:41-0400 <local3.info> rtr215  CLIENT: DISCARD_INDICATION: blue  host83/12401/#0001  Egress message(s) discarded

To receive all client scope events published using SMF topic syntax from the router message bus, for the Message VPN to which the client is connected, subscribe to:

#LOG/*/CLIENT/>

To receive all client scope events published using SMF topic syntax from a particular router for the Message VPN to which the client is connected, subscribe to:

#LOG/*/CLIENT/<routerName>/>

To receive all client scope events published using MQTT topic syntax from the router message bus, for the Message VPN to which the client is connected, subscribe to:

$SYS/+/CLIENT/#

To receive all client scope events published using MQTT topic syntax from a particular router for the Message VPN to which the client is connected, subscribe to:

$SYS/+/CLIENT/<routerName>/#

Subscribe Event Topics

Subscribe events are published using SMF topic syntax to the following topic on the Message VPN where the subscription was added:

#LOG/INFO/SUB_ADD/<subscribedTopic>

Subscribe events are published using MQTT topic syntax to the following topic on the Message VPN where the subscription was added:

$SYS/LOG/INFO/SUB_ADD/<subscribedTopic>

Where:

<subscribedTopic> is the associated subscription topic string. Note that if the subscription topic string is greater than 235 bytes, it will be truncated in the published topic.

Subscribe topic example:

#LOG/INFO/SUB_ADD/animals/dogs

The published message text is formatted as follows:

routerName vpnName clientName  SUBSCRIPTION_ADD subscribedTopic

Subscribe message text example:

rtr215  blue  host83/12401/#0001  SUBSCRIPTION_ADD  animals/dogs

Note:  To minimize the performance impact of publishing subscribe events, a timestamp is not included in the message text.

Unsubscribe Event Topics

Unsubscribe events are published using SMF topic syntax to the following topic, on the Message VPN where the subscription was removed:

#LOG/INFO/SUB_DEL/<subscribedTopic>

Unsubscribe events are published using MQTT topic syntax to the following topic, on the Message VPN where the subscription was removed:

$SYS/LOG/INFO/SUB_DEL/<subscribedTopic>

Where:

<subscribedTopic> is the associated subscription topic string. Note that if the subscription topic string is greater than 235 bytes, it will be truncated in the published topic.

Unsubscribe topic example:

#LOG/INFO/SUB_DEL/animals/dogs

The published message text is formatted as follows.

routerName vpnName clientName  SUBSCRIPTION_DELETE subscribedTopic

Unsubscribe message text example:

rtr215  blue  host83/12401/#0001  SUBSCRIPTION_DELETE  animals/dogs

Note:  To minimize the performance impact of publishing subscribe events, a timestamp is not included in the message text.