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.

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.

The monitor requires a Web Service connector with authentication type CLOUD_ALM. See 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

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

1. In the BTP Cockpit go to your subaccount → Services → Instances and Subscriptions.
2. Locate your SAP Cloud ALM API instance.
3. Click the ⋯ (three dots) menu next to the instance.
4. Select Update to edit the instance.
5. Click Next.
6. Add the scopes above to the authorities array in the parameters JSON and save.
7. 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>

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.

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.

• Per-row thresholds using the standard G2W:1 W2M:10 syntax. See 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:

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%)

• 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

• 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

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

• 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

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.

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

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

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.

• 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

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

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

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

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

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

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.

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

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

• 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 (Multi Threshold Syntax)