====== SAP Cloud ALM Integration Monitoring ======

The **SAP Cloud ALM Integration Monitoring** monitor counts the integration messages that SAP Cloud ALM collects from your managed systems: IDocs, web service calls, SAP Integration Suite messages, AIF and PI messages and every other message type known to Cloud ALM. It reports the messages per service, message type and direction, split by status group, and raises alarms on the number of messages in error and on the error ratio.

One monitor covers every message type. It reads the **generic** Integration Monitoring provider of Cloud ALM, which SAP recommends over the older per-type providers.

===== Prerequisites =====

Network connectivity from the collector to your SAP Cloud ALM tenant API endpoint (e.g. ''https://your-tenant.eu10.alm.cloud.sap'').

Integration Monitoring must be set up in Cloud ALM for the systems you want to watch. The monitor only sees the messages that Cloud ALM itself collects.

==== Cloud ALM Connector (required) ====

The monitor requires a **Web Service** connector with authentication type **CLOUD_ALM**. See [[..:sap_cloud_alm|SAP Cloud ALM Connector]].

This connector is based on a service key of the **SAP Cloud ALM API** service instance in the BTP subaccount that contains your Cloud ALM entitlement.

The following OAuth scopes **must** be included in the instance parameters (in the ''authorities'' list):

  * ''$XSMASTERAPPNAME.calm-api.integration-monitoring.read''
  * ''$XSMASTERAPPNAME.calm-api.metrics.read''
  * ''$XSMASTERAPPNAME.calm-api.analytics.read''

=== Where to add the scopes ===

Even if you already created a service key for the ALM connector, you do **not** need to delete the instance.

  - In the BTP Cockpit go to your subaccount → **Services** → **Instances and Subscriptions**.
  - Locate your **SAP Cloud ALM API** instance.
  - Click the **⋯** (three dots) menu next to the instance.
  - Select **Update** to edit the instance.
  - Click **Next**.
  - Add the scopes above to the ''authorities'' array in the parameters JSON and save.
  - Fetch a new token or wait for the current one to expire: scopes are read when the token is issued.

<WRAP important>
Without the Integration Monitoring scope, the monitor run fails with HTTP 403 and the **Load Services** button returns an error.
</WRAP>

===== API Endpoints used =====

^ Endpoint ^ Purpose ^
| ''POST /oauth/token'' | Authentication (BTP UAA) |
| ''GET /api/calm-metrics/v1/metrics?provider=im'' | Message counts of the last 5 minute bucket |
| ''POST /api/calm-analytics/v1/analytics/providers/data'' | **Load Services** discovery, and the list of service types when a response is too large |

Each run reads **one 5 minute bucket**: the bucket that ended **Collection delay** minutes ago, rounded down to the 5 minute grid. One request returns every service and every message type. A row with a **Properties filter** costs one extra request per run.

The monitor does not replay the buckets between two runs. Keep the schedule at 5 minutes, which is the default, so that every bucket is read once.

===== Key Features =====

==== Message counting ====

For every combination of service, message type and direction, the monitor sums the messages of the bucket by **status group**. Cloud ALM groups the message statuses into **ERROR**, **WARNING**, **IN PROCESS**, **CANCELED**, **SUCCESSFUL**, **INFO** and **OTHERS**.

Each row selects the figure it publishes and alarms on:

  * **TOTAL_MESSAGES** – all messages of the bucket, whatever their status
  * **ERROR_MESSAGES** – messages in the **ERROR** status group
  * **WARNING_MESSAGES** – messages in the **WARNING** status group
  * **IN_PROCESS_MESSAGES** – messages in the **IN PROCESS** status group
  * **ERROR_RATIO** – messages in error divided by all messages of the bucket, in percent

**ERROR_RATIO** is only computed when the bucket has at least one message for the combination. A bucket with no message publishes nothing and leaves the alarms as they are.

==== Alarm Capabilities ====

  * Per-row thresholds using the standard ''G2W:1 W2M:10'' syntax. See [[..:commonsettings#multi_thresholds_syntax|Multi Threshold Syntax]].
  * Thresholds apply to the figure selected in **Metric**: a count of messages, or a percentage for **ERROR_RATIO**
  * Wildcard support (''*'') for **Service name** and **Message type**, alone or inside a name, e.g. ''S4H*'' or ''*IDOC*''
  * **Direction** restricts a row to **INBOUND** or **OUTBOUND** messages
  * **Properties filter** restricts a row to messages with given properties, for example one IDoc sender port
  * **Exclusive** stops later rows with the same **Metric** from evaluating a combination this row matched
  * Optional alarm tag added to the alarm message
  * An alarm stays open while the combination is quiet. Integration traffic is bursty, and a bucket without messages is not a sign that the problem is solved. The alarm clears when a later bucket has messages for the combination and the figure is back under the threshold, or when the row is deactivated

The alarm message names the service, the message type and the direction, then the figure, the threshold and the most frequent status, for example:

<code>
S4H.100 / WS / OUTBOUND: 12 messages in error over 5 minutes (threshold 10). Top status: System_Error (12)
ERP.200 / IDOC / INBOUND: error ratio 25.0% (3 of 12 messages, threshold 20%)
</code>

==== Metric Publishing Behavior ====

  * Every row with **Metric** (the checkbox) enabled publishes the figure selected in the **Metric** column for each combination it matches
  * A figure is published once per combination and per run, even when several rows match the same combination
  * Metrics carry the end of the 5 minute bucket as their time, not the time of the collection

==== Discovery ====

  * **Load Services** button: lists every service and message type pair that produced messages in the **last 7 days** and fills **Service name**, **Service ID** and **Message type** for the rows you select
  * A pair without traffic in the last 7 days is not listed. You can still type the service name and the message type by hand
  * The **Service ID** filled by the button is the exact key used by Cloud ALM. When it is set, the row ignores **Service name** for matching. Leave it empty for wildcard rows

===== Configuration =====

==== Monitor Configuration ====

=== Method 1: Load Services (Recommended) ===

  - Open the monitor configuration.
  - Click the **Load Services** button.
  - Select the service and message type pairs you want. Each becomes a row with the **Service name**, **Service ID** and **Message type** filled.
  - Choose the **Metric**, define the thresholds and save.

=== Method 2: Wildcard / Manual Mode ===

  * Set **Service name** = ''*'' and **Message type** = ''*'' to watch every message of the tenant with one row
  * A ''*'' can also be part of a name, for example **Service name** = ''S4H*''
  * **Message type** is the technical key of Cloud ALM: ''IDOC'', ''WS'' (web service messages), ''CPI'' (SAP Integration Suite), ''AIF'', ''PI_ABAP_MESSAGES'', ''PI_JAVA_MESSAGES'', ''SAP SuccessFactors'', ''C4C'' and about seventy more. **Load Services** shows the keys present on your tenant

=== Settings Reference ===

^ Field ^ Description ^ Default ^
| Collection delay (minutes) | Age of the bucket read on each run. Cloud ALM receives the messages from the managed systems with a delay; a bucket read too early is incomplete | ''10'' |
| Active | Enable/disable this configuration row | ''true'' |
| Service name | Filter on the service name as shown in Cloud ALM, ''*'' matches any part of the name | ''*'' |
| Service ID | Technical key of the service, filled by **Load Services**. When set, it replaces the **Service name** filter | (empty) |
| Message type | Filter on the message type key, ''*'' matches any part of the key | ''*'' |
| Direction | ''INBOUND'', ''OUTBOUND'' or ''*'' | ''*'' |
| Metric | Figure to publish and alarm on: TOTAL_MESSAGES / ERROR_MESSAGES / WARNING_MESSAGES / IN_PROCESS_MESSAGES / ERROR_RATIO | ''ERROR_MESSAGES'' |
| Properties filter | Optional, comma separated ''key=value'' pairs that the messages must all have, see below | (empty) |
| Thresholds | Multi-level thresholds on the selected figure | ''G2W:1 W2M:10'' |
| Alarm tag | Optional tag added to the alarm message | (empty) |
| Exclusive | If enabled, later rows with the same **Metric** do not evaluate the combinations matched by this row | ''false'' |
| Alarm | Enable/disable alarm creation for this row | ''true'' |
| Metric (checkbox) | Publish the selected figure for this row | ''true'' |

A new row is pre-filled with every service, every message type, **ERROR_MESSAGES** and ''G2W:1 W2M:10''. Add a second row with **ERROR_RATIO** and ''G2W:5 W2M:20'', and a third one with **TOTAL_MESSAGES** and no threshold, to get the full picture.

==== Properties filter ====

Cloud ALM stores properties with each message: the sender port and the receiver port of an IDoc, the interface name of a web service call, the integration flow of an SAP Integration Suite message. The **Properties filter** restricts a row to the messages that carry given values.

  * The filter is a comma separated list of ''key=value'' pairs. **All** pairs must match. There is no OR
  * Keys and values are the ones Cloud ALM shows for the message type, for example ''Sender Interface Name=MaterialStockReplicateOut'' for web service messages or ''SenderPort=WPUx'' for IDocs. A key that Cloud ALM does not know is ignored
  * A row with a **Properties filter** needs **one** concrete **Message type**. With ''*'' in **Message type** the row is skipped and a warning is written to the monitor log
  * A row with a **Properties filter** reads its own figures from Cloud ALM and is never affected by **Exclusive** rows above it
  * If the request of a filtered row fails, the row is skipped for that run and its open alarms stay open

===== Collected Metrics =====

All metrics are stored with the base key: ''promonitor.cloud_alm.im.*''

^ Metric Key ^ Unit ^ Description ^ Tags ^
| ''promonitor.cloud_alm.im.total_messages'' | - | Messages of the 5 minute bucket | service, service_id, service_type, message_type, direction |
| ''promonitor.cloud_alm.im.error_messages'' | - | Messages in the ERROR status group | same as above |
| ''promonitor.cloud_alm.im.warning_messages'' | - | Messages in the WARNING status group | same as above |
| ''promonitor.cloud_alm.im.in_process_messages'' | - | Messages in the IN PROCESS status group | same as above |
| ''promonitor.cloud_alm.im.error_ratio'' | % | Messages in error divided by all messages of the bucket | same as above |

The ''service'' tag is the service name as shown in Cloud ALM, for example ''S4H.100''. The ''service_type'' tag is the Cloud ALM service type, for example ''SAP_S4HANA_OP''.

===== Alarm Evaluation Notes =====

  * A row raises **one alarm per matching combination** of service, message type and direction. The alarm is identified by the service, the message type, the direction, the figure and the row
  * Thresholds fire when the figure reaches the configured level. ''G2W:1'' on **ERROR_MESSAGES** fires as soon as one message is in error
  * **ERROR_RATIO** thresholds are percentages. ''G2W:5 W2M:20'' warns at 5% of messages in error and goes major at 20%
  * A combination without messages in the bucket is not evaluated and keeps its alarm state. The alarm clears on the first bucket with messages where the figure is back under the threshold
  * **Exclusive** works per figure. An exclusive **ERROR_MESSAGES** row does not stop an **ERROR_RATIO** row below it from evaluating the same combination
  * The open alarms are kept in the collector memory. After a collector restart they are cleared once and raised again on the next bucket in error
  * A row with an invalid threshold stops the evaluation of the run with an error in the monitor log. Check the syntax before saving

===== Examples =====

==== 1. Alarm on any message in error, every system ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | * | (empty) | * | * | ERROR_MESSAGES | (empty) | G2W:1 W2M:10 | (empty) | false | true | true |

This is what a new row contains by default. One alarm per service, message type and direction with messages in error.

==== 2. Error ratio and total volume as well ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | * | (empty) | * | * | ERROR_MESSAGES | (empty) | G2W:1 W2M:10 | (empty) | false | true | true |
| true | * | (empty) | * | * | ERROR_RATIO | (empty) | G2W:5 W2M:20 | (empty) | false | true | true |
| true | * | (empty) | * | * | TOTAL_MESSAGES | (empty) | (empty) | (empty) | false | false | true |

Row 3 publishes the message volume without alarming. The three rows evaluate different figures, so **Exclusive** is not needed.

==== 3. Stricter threshold for one production system ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | S4H.100 | (empty) | * | * | ERROR_MESSAGES | (empty) | G2W:1 W2M:3 | S4H_PROD | true | true | true |
| true | * | (empty) | * | * | ERROR_MESSAGES | (empty) | G2W:5 W2M:20 | (empty) | false | true | true |

Row 1 is exclusive, so row 2 does not evaluate the messages of ''S4H.100'' again. Other services get the looser threshold.

==== 4. Inbound IDocs only ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | ERP* | (empty) | IDOC | INBOUND | ERROR_MESSAGES | (empty) | G2W:1 W2M:10 | IDOC_IN | false | true | true |

Outbound IDocs and the other message types of the ''ERP'' systems are not evaluated by this row.

==== 5. One IDoc partner ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | S4H.100 | (empty) | IDOC | INBOUND | ERROR_MESSAGES | SenderPort=WPUx | G2W:1 W2M:5 | WPU | false | true | true |

Only the IDocs received from the sender port ''WPUx'' count. The row needs a concrete **Message type** because the properties depend on it.

==== 6. Web service interface with a volume floor ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | S4H.100 | (empty) | WS | OUTBOUND | ERROR_RATIO | Sender Interface Name=MaterialStockReplicateOut | G2W:10 W2M:50 | STOCK | false | true | true |

The ratio is computed on the messages of this interface only. A bucket without a call of this interface publishes nothing and keeps the alarm state.

==== 7. Watch for a stuck queue ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | * | (empty) | CPI | * | IN_PROCESS_MESSAGES | (empty) | G2W:50 W2M:200 | CPI_BACKLOG | false | true | true |

Alarms when more than 50 SAP Integration Suite messages of a 5 minute bucket are still being processed.

==== 8. Publish without alarming ====

^ Active ^ Service name ^ Service ID ^ Message type ^ Direction ^ Metric ^ Properties filter ^ Thresholds ^ Alarm tag ^ Exclusive ^ Alarm ^ Metric ^
| true | * | (empty) | * | * | ERROR_MESSAGES | (empty) | G2W:1 W2M:10 | (empty) | false | false | true |

''Alarm = false'': the error counts are written to the time series but no alarm is raised.

===== Troubleshooting =====

  * **Run fails with HTTP 403 and "Check that the API client has the scope calm-api.integration-monitoring.read"**: the scope is missing on the **SAP Cloud ALM API** instance, or the token was issued before the scope was added. Update the instance and fetch a new token.
  * **Load Services returns nothing**: no service produced integration messages in the last 7 days, or Integration Monitoring is not set up in Cloud ALM for your systems. Check the Integration & Exception Monitoring application in Cloud ALM first.
  * **Load Services lists a service twice**: one entry per message type is normal. Select the pairs you need.
  * **No metrics and no alarms although Cloud ALM shows messages**: the bucket read by the monitor is **Collection delay** minutes old. Compare with the message times in Cloud ALM. If Cloud ALM receives the messages late, increase **Collection delay**; if they are visible at once, you can lower it.
  * **Run fails with "The response to the request is too large"**: the tenant has more combinations than the API returns in one call. The monitor splits the request per service type on its own; if a single service type is still too large, add a **Properties filter** or report the tenant size to the support.
  * **Row with a Properties filter does nothing**: the row needs one concrete **Message type**. A warning in the monitor log names the row. Check also that the pairs use ''='' and are separated by commas.
  * **Alarm does not clear although the problem is solved**: the alarm clears on the first bucket that has messages for the combination with the figure back under the threshold. While nothing is sent, the alarm stays. Deactivate the row to drop it at once.
  * **Alarms not triggering**:
    * Verify the row is **Active** and **Alarm** is enabled
    * Verify **Metric** is the figure you expect, a count or a ratio
    * Verify **Service name**, **Message type** and **Direction** match the keys Cloud ALM uses, as shown by **Load Services**
    * Verify the threshold syntax ([[..:commonsettings#multi_thresholds_syntax|Multi Threshold Syntax]])