====== SAP Advanced Event Mesh Queues Monitoring ======
This monitor supervises SAP Advanced Event Mesh (AEM) queues per VPN and queue pattern,
with threshold-based alarms and optional time-series metrics.

===== What Can Be Monitored =====

You can detect and alert on:
  * Queue backlog growth (too many queued messages)
  * Consumer outages or slowdown (too few bound consumer flows)
  * Message staleness and delivery delay (oldest message too old)

This supports proactive detection of integration bottlenecks and stuck processing pipelines.

===== Prerequisites =====

  * The connector URL must point at the SEMP monitor API and include the ''/SEMP/v2/monitor'' path, for example %%https://<host>.messaging.solace.cloud:943/SEMP/v2/monitor%%. Without this prefix every request returns HTTP 404.
  * The credentials require the ''vpn/read-only'' access scope. The same scope covers listing the Message VPNs, which the monitor needs when the VPN Name is a pattern rather than an exact name.

 **Note:** SAP documentation states that the API used to collect AEM data is available only from version **2.12** of Solace Element Management Protocol.

===== Monitored Data =====

The monitor queries AEM APIs to collect:
  * Queue message count
  * Queue consumer flow count
  * Oldest message age (minutes)

===== Filters =====

**VPN Name** and **Queue Name** are filters, not names. They accept the following forms:

^ Pattern ^ Matches ^
| ''*'' | Everything. |
| ''ORDER'' | Any name containing ''ORDER'' (case-insensitive). |
| ''ORDER_*'' | Wildcard match, for example ''ORDER_IN'' and ''ORDER_OUT''. |
| ''!DLQ'' | Any name **not** containing ''DLQ''. |
| ''A,B'' | Contains ''A'' **or** ''B''. |
| ''A+B'' | Contains ''A'' **and** ''B''. |

The broker also holds system objects, whose names begin with ''#'' (for example ''#REPLAY_LOG_defaultLog'', ''#telemetry-<service>'' and the ''#cluster'' VPN). A filter of ''*'' includes them. To exclude them, use ''!#''.

**Two syntax traps:**
  * Use ''!#'', not ''!#*''. Inside a negation the ''*'' is treated as a literal character, so ''!#*'' matches everything.
  * Combine with ''+'', not '',''. ''Master+!#'' works as expected. In a comma list a leading negation short-circuits, so ''!#,Master'' behaves as plain ''!#''.

If a configured VPN Name or Queue Name matches nothing on the broker, a warning is written to the collector log. This usually means a typo in the filter.

===== Configuration Hints =====

  * One surveillance row targets one set of queues (VPN + queue pattern). Several rows may target the same VPN; they share a single read of the queue list.
  * Set a threshold to exactly ''0'' to disable that specific check for the row:
    * ''Max queued messages = 0'' disables the queue size alarm.
    * ''Min. consumer flows = 0'' disables the consumer flow alarm.
    * ''Max message age (min) = 0'' disables the oldest-message-age alarm.
    Note this is the literal value ''0''. A threshold such as ''G2W:0'' is an active threshold, not a disabled check.
  * If **Severity** is disabled, matching queues are ignored entirely, for all three checks.
  * **Auto clear** controls whether alarms are clearable.
  * **Send metrics** enables metric emission for queue size and consumer flows.
  * The oldest-message-age check reads an endpoint that Solace advises against polling frequently. It is only collected for the queues of rows that actually check it, so leave ''Max message age (min)'' at ''0'' on rows that do not need it.

===== Configuration =====

==== Monitoring Parameters ====

^ Parameter ^ Type ^ Required ^ Default ^ Description ^
| Send metrics | Boolean | Yes | ''true'' | Send collected values as metrics (queue size and consumer flows). |
| Auto clear | Boolean | Yes | ''true'' | Alarms generated by this monitor are clearable when the condition recovers. |

==== Surveillance Table ====

^ Field ^ Required ^ Default ^ Description ^
| Active | Yes | ''true'' | Enables/disables this surveillance row. |
| VPN Name | Yes | ''*'' | Message VPN filter. See [[#filters|Filters]]. |
| Queue Name | Yes | ''*'' | Queue filter. See [[#filters|Filters]]. |
| Max queued messages | Yes | ''G2W:100'' | Alarm when the number of queued messages reaches the threshold. ''0'' disables the check. |
| Min. consumer flows | Yes | ''G2W:0'' | Alarm when the number of bound consumer flows falls to the threshold or below. ''0'' disables the check. |
| Max message age (min) | Yes | ''G2W:10'' | Alarm when the oldest message has been queued longer than the threshold, in minutes. ''0'' disables the check and skips its collection. |
| Severity | Yes | ''4'' | Severity used for simple numeric threshold mode. Disabled excludes matching queues from all checks. |
| Alarm tag | No | (empty) | Optional alarm classification/tag field. |
| Alarm | No | ''true'' | Enables/disables alarm generation for this row. |

===== Alarm Conditions =====

For each active surveillance row matching a queue:
  * **Queue size alarm**: triggered when ''msgCount >= Max queued messages''
  * **Consumer flow alarm**: triggered when ''flowCount <= Min. consumer flows''
  * **Message age alarm**: triggered when ''oldestTime >= Max message age (min)''

A check is only evaluated when its value was successfully collected. If a queue cannot be read in a given cycle, the corresponding check is skipped and a warning is written to the collector log rather than a value being assumed.

===== Consumer Flows Versus Clients =====

The consumer count reports **bound consumer flows**, not distinct client applications. A single client may hold several flows on the same queue, in which case that queue reports a flow count higher than the number of connected applications.

This matches how the broker itself counts binds, through ''maxBindCount'' and the queue consumer flows event. When setting **Min. consumer flows**, base the threshold on the number of flows the consumer normally holds, not on the number of applications.

===== Generated Metrics =====

If **Send metrics** is enabled, the monitor emits metrics with tags:
  * ''vpn=<vpnName>''
  * ''queue=<queueName>''

^ Metric ^ Unit ^ Description ^
| Queue size | Messages | Number of messages currently queued. |
| Consumer flows | Flows | Number of consumer flows bound to the queue. |

A metric is only emitted when its value was collected, so a gap in a metric indicates that the queue could not be read in that cycle.

===== Generated Alarms =====

Alarm messages include queue and VPN context, for example:
  * ''X message(s) in queue <queue> (>=Y) on vpn <vpn>''
  * ''X consumer flow(s) (<=Y) for queue <queue> on vpn <vpn>''
  * ''Oldest message spent X min (>=Y) in queue <queue> on vpn <vpn>''

===== Sizing =====

The monitor reads the queue list of each matching VPN, then issues one request per matching queue for the consumer flow count, plus one more per queue when the message age check is enabled. Requests are rate limited to stay within the broker's recommended 10 requests per second.

With the default job timeout this supports roughly 500 queues with the message age check enabled, or around 1100 without it. Beyond that, restrict the Queue Name filter or disable the message age check on rows that do not require it.

===== Example =====

^ Active ^ VPN Name ^ Queue Name ^ Max queued messages ^ Min. consumer flows ^ Max message age (min) ^ Severity ^ Alarm tag ^ Alarm ^
| true | ''PROD_*'' | ''ORDER_*'' | ''G2W:5000'' | ''G2W:1'' | ''G2W:15'' | 4 | ''AEM,ORDER'' | true |
| true | ''*'' | ''DLQ_*'' | ''G2W:100'' | ''G2W:0'' | ''G2W:5'' | 3 | ''AEM,DLQ'' | true |
| true | ''*'' | ''!#'' | ''G2W:1000'' | ''0'' | ''0'' | 4 | ''AEM'' | true |

The third row watches the backlog of every business queue while excluding system queues, with the consumer flow and message age checks disabled.