Observability for third party components components using SAP Cloud ALM

[andrea_campo]

• Introduction
• Architecture Overview
• Configuration Overview
• Instrument Tomcat with OpenTelemetry
• Register Service in SAP Cloud ALM
• Get SAP Cloud ALM API Service Credentials
• Install and configure the OTel Collector
• Activate Data Collection in SAP Cloud ALM
• Check results in Health Monitoring
• Activate and check results in Real User Monitoring
• Activate and check results in Integration and Exception Monitoring
• Key Takeaways
• Link Collection
• Glossary

 

Introduction

In today's enterprise environments, organizations increasingly depend on a diverse mix of tools, platforms, and custom applications, both SAP and third party components. SAP's core strategic goal is to empower IT teams by simplifying this complexity and seamlessly integrating and monitoring these varied systems and services.

If you’re running third party components workloads—like Java applications on Apache Tomcat—but want centralized visibility and operations in SAP Cloud ALM, OpenTelemetry provides a clean path. SAP Cloud ALM can be used as a centralized, unified platform for monitoring, managing, and optimizing all components, including cloud-native services and third-party systems.

In this blog, we'll explore how you can leverage SAP Cloud ALM to monitor third party components systems using Inbound raw APIs and OpenTelemetry. As part of this blog we will focus on Health Monitoring, Real User monitoring and Integration and Exception monitoring. More applications can consume external signals, complete list per signal type can be found in link collection at the end.

Architecture Overview

The list of key components for monitoring external entities with SAP Cloud ALM using OpenTelemetry includes:

• OpenTelemetry Java Agent
• OpenTelemetry Collector
• SAP Cloud ALM raw inbound APIs

The OpenTelemetry Java Agent is a tool designed to automatically collect telemetry data, such as traces and metrics, from Java applications. It is part of the OpenTelemetry project, which aims to provide a standardized way to gather observability data for applications, making it easier to monitor their performance and troubleshoot issues.

The OpenTelemetry Collector is a component of the OpenTelemetry project that serves as an intermediary for processing, transforming, and exporting telemetry data (traces, metrics, logs) to monitoring and observability backends.

SAP Cloud ALM raw inbound APIs are interfaces that allow external systems and applications to send telemetry data directly into SAP Cloud ALM applications like Health Monitoring, Real User Monitoring or Integration and Exception Monitoring.

In this article we will describe how to configure an external system (Tomcat server) to show metrics, logs and traces in SAP Cloud ALM using all the key components.

The receiving entity in our architecture is a SAP Cloud ALM application depending on the type of signal involved:

• Real User Monitoring or Synthetic User Monitoring for traces
• Health Monitoring for metrics
• Exception Monitoring for logs

 

Configuration Overview

Required configuration steps can be summarized as follows:

1. Instrument Tomcat with OpenTelemetry
2. Register Service in SAP Cloud ALM
3. Get SAP Cloud ALM API Service Credentials
4. Install and configure the OTel Collector
5. Activate Data Collection in SAP Cloud ALM

 

Instrument Tomcat with OpenTelemetry

In general, instrumenting an application or service with OpenTelemetry means adding the “sensors” that let you see what the software is doing in production.

Instrumenting a Tomcat server with OpenTelemetry means enabling Tomcat and the web apps it hosts to emit standardized traces, metrics, and logs so you can see request flow, latency, errors, and resource usage.

This is exactly the role of the OpenTelemetry Java Agent which hooks into the JVM at startup and automatically detects common frameworks (JDBC, messaging, etc.) creating spans and metrics with appropriate context propagation. The agent can be setup to send data to a specific backend (like the OTel Collector) via configured exporters. Instrumentation is enabled/controlled by configuration (environment variables, system properties) rather than code.

The opentelemetry-javaagent.jar file must be placed in a directory accessible by the Tomcat server (e.g. $CATALINA_HOME/lib/) and the -javaagent:$CATALINA_HOME/lib/opentelemetry-javaagent.jar option must be added either to CATALINA_OPTS or the setenv.sh file like here:

#https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
#Previous: 1.33.3
#Current: 2.12.0
#attaches the OpenTelemetry Java agent to Tomcat at startup and turns on Tomcat-specific JMX metric scraping
export CATALINA_OPTS="$CATALINA_OPTS -javaagent:$CATALINA_HOME/lib/opentelemetry-javaagent_2.12.0.jar -Dotel.jmx.target.system=tomcat"

#uses OTLP over gRPC (port 4317) for exporting, more efficient if signals are sent to a Collector
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
#points all OTLP exports to the OpenTelemetry Collector (or backend) at host demo_otel, port 4317.
export OTEL_EXPORTER_OTLP_ENDPOINT=http://demo_otel:4317

#enable exporting logs, metrics and traces via OTLP
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=otlp

#sets resource attributes added to every signal: service name is Tomcat-Server and a custom tag sap.custom=ALM-Demo.
export OTEL_RESOURCE_ATTRIBUTES=service.name=Tomcat-Server,sap.custom=ALM-Demo

OTEL_EXPORTER_OTLP_PROTOCOL and OTEL_EXPORTER_OTLP_ENDPOINT are used to point where all the telemetry should go while OTEL_*EXPORTER options are used to make sure every signal gets shipped with the proper protocol (on modern agents, traces and metrics default to OTLP anyway, but explicitly enabling logs ensures they’re exported too if log correlation is configured).

OTEL_RESOURCE_ATTRIBUTES is just used to add some identity to the data by adding tags to every trace/metric/log with a service name and a custom attribute.

After restart, servlets, filters, and JSPs, as well as common libraries, will be auto-instrumented, and the server will start sending signals to the OTel host with no code modifications.

Register Service in SAP Cloud ALM

To configure third party components services, you need to ensure they can send signals to SAP Cloud ALM and that they are represented in the Landscape Management application in SAP Cloud ALM as an unspecific cloud service.

This is a crucial step because the Landscape ID  generated at the end of the process (e684466f-446d-4a53-a899-f0af6d94731e in this example) will be used in the OTel Collector configuration to send the signals to the proper entity in each application.

Get SAP Cloud ALM API Service Credentials

Any entity sending data to SAP Cloud ALM must be authenticated to be able consume the APIs. The procedure to enable SAP Cloud ALM APIs is described here. The goal is to be able to retrieve service credentials.

In this example service credentials (clientsecret and clientid are fake) are necessary to authenticate the collector with SAP Cloud ALM API, specifically clientid, clientsecret, and url attributes in the uaa section of the credentials form. This can be retrieved from the BTP Cockpit for the SAP Cloud ALM API service.

Service Credential (fake data)

 

Install and configure the OTel Collector

As explained before, the OpenTelemetry collector is a proxy that can receive, process, and export telemetry data in various formats (such as Jaeger, Prometheus, and OTLP) and send it to one or more backends, including SAP Cloud ALM.

Collectors can be installed and setup in few minutes; there are essentially two options: use the image and binaries from the github release project (this option will include all the receivers, exporters and extensions) or build and install a custom collector configured using specific receivers, exporters and extensions. The minimal requirement needed to authenticate the collector to the SAP Cloud ALM API is the oauth2clientauthextension. 

Regardless the installation option, setup is done via a configuration file (otel-config.yaml in the example below). 

Using docker, it is quite straightforward to start and test a collector:

docker run -v ./otel-config.yaml:/etc/otelcol-contrib/config.yaml \
-p 127.0.0.1:4317:4317 \
-p 127.0.0.1:55679:55679  \
otel/opentelemetry-collector-contrib

This command runs the OpenTelemetry Collector in a Docker container, using a custom configuration file in the current directory (otel-config.yaml) and exposing two ports (4317 and 55679) for communication with the host.

The collector yaml file includes mainly four sections:

• Receivers
• Processors
• Exporters
• Services

Below is an example of a configuration file using the service credential attributes—specifically clientid, clientsecret, and url—as explained in the "Get SAP Cloud ALM API Service Credentials" section. These attributes are used for oauth2client authentication within the OpenTelemetry Collector configuration.
When configuring the oauth2client extension, ensure that the token_url parameter is constructed by appending /oauth/token to the provided url value. This step is required for proper authentication against the SAP Cloud ALM API.

extensions:

#This enables zPages, a web-based UI for viewing in-process telemetry data.
#It listens on port 55679 and can be accessed via http://<otel-collector-host>:55679/zpages
  zpages:
    endpoint: 0.0.0.0:55679

#This is used to authenticate requests sent by the exporters. 
#In this case the client_id (sb-sapcloudalmapi!b48494|sapcloudalm!b36409) includes a character | which is not supported in the file or string.
#OpenTelemetry typically expects the client_id and client_secret to be provided via a file (e.g., client_id_file) or as a simple string without special characters like |, hence we use files here. 
#Make sure the files are protected and not accessible by unauthorized users.
 
  oauth2client/prod:
    client_id_file: ./client_id_file
    client_secret_file: ./client_secret_file
    token_url: https://calm-acme-demo.authentication.eu10.hana.ondemand.com/oauth/token

#This defines a receiver that listens for telemetry data (metrics, logs, traces) from the otlp/tomcat source.
#It uses the gRPC protocol and listens on port 4317 for incoming data. This is the same port that the Tomcat OpenTelemetry Java agent is configured to send data to.
#Make sure that the port 4317 is open and not blocked by any firewall or network security group.
receivers:
  otlp/tomcat:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

#This improves performance by reducing the number of requests and optimizing network usage.
processors:
  batch:

#These define exporters that send telemetry data to external systems.
#There are three exporters, one for each type of telemetry data: metrics, logs, and traces.
#Each exporter is configured to send data to a specific endpoint in the SAP Cloud ALM system
#Each exporter uses the oauth2client/prod extension for authentication.
exporters:
  otlphttp/tomcat_metrics:
    metrics_endpoint: https://eu10.alm.cloud.sap/api/calm-metrics/v1/metrics?serviceId=e684466f-446d-4a53-a899-f0af6d94731e&useCase=hm&dev=false&tag=otelcol_prodemo
    compression: none
    auth:
      authenticator: oauth2client/prod
    headers:
      Content-type: "application/x-protobuf"

  otlphttp/tomcat_logs:
    logs_endpoint: https://eu10.alm.cloud.sap/api/calm-logs/v1/logs?serviceId=e684466f-446d-4a53-a899-f0af6d94731e&useCase=exm&dev=false&tag=otelcol_prodemo
    compression: none
    auth:
      authenticator: oauth2client/prod
    headers:
      Content-type: "application/x-protobuf"

  otlphttp/tomcat_traces:
    traces_endpoint: https://eu10.alm.cloud.sap/api/calm-traces/v1/traces?serviceId=e684466f-446d-4a53-a899-f0af6d94731e&useCase=rum&dev=false&tag=otelcol_prodemo
    compression: none
    auth:
      authenticator: oauth2client/prod
    headers:
      Content-type: "application/x-protobuf"

#The service section ties everything together.
service:

#Uses the oauth2client/prod extension for authentication and enables zPages for monitoring.
  extensions: [zpages,oauth2client/prod]

#Defines how telemetry data flows:
  pipelines:
#Receives metrics, batches them, and sends them to otlphttp/tomcat_metrics.
    metrics/tomcat:
      receivers: [otlp/tomcat]
      processors: [batch]
      exporters: [otlphttp/tomcat_metrics]
#Receives logs, batches them, and sends them to otlphttp/tomcat_logs.
    logs/tomcat:
      receivers: [otlp/tomcat]
      processors: [batch]
      exporters: [otlphttp/tomcat_logs]
#Receives traces, batches them, and sends them to otlphttp/tomcat_traces.
    traces/tomcat:
      receivers: [otlp/tomcat]
      processors: [batch]
      exporters: [otlphttp/tomcat_traces]

Spoiler

You can check the status of the local collector accessing the link http://localhost:55679/debug/servicez. This will show you the enabled extensions and features. 

In short: 

• Receiver otlp/tomcat collect telemetry data.
• Processors (like batch) optimize the data before exporting.
• Exporters, like otlphttp/tomcat_metrics, send the data to external systems (SAP Cloud ALM Health monitoring application)
• Service defines how everything works together using pipelines like metrics/tomcat.

Collector metric data flow

Activate Data Collection in SAP Cloud ALM

After restarting the collector, signals will be sent to the SAP Cloud ALM applications. To actually see the data in each application, few additional steps are needed.

Check results in Health Monitoring

If everything is set up properly, Health Monitoring will display the metrics list for the custom Tomcat service you created. Simply choose "Unspecific Cloud Service" as the service type in the scope selector

Scope Selector for Unspecific Cloud Services

and confirm that data collection is enabled for the "Tomcat" service in your configuration.

Health Monitoring Overview and Service activation

To view system details, just click on the Unspecific Cloud Service tile:

Monitoring Overview

Monitoring System Details

 

Activate and check results in Real User Monitoring

To enable Real User Monitoring for Tomcat, select the unspecific cloud service

Real User Monitoring scope selection for Unspecific Cloud Services

click the configuration wheel, and activate data collection in Managed Components.

Real User Monitoring: Tomcat data collection and Overview

Requests traces will then be available in the detailed pages:

       RUM Requests Overview

RUM Request Executions

 

Activate and check results in Integration and Exception Monitoring

Error logs will appear on the Exception Monitoring page as soon as data collection is activated, just like Health Monitoring and Real User Monitoring.

Integration and Exception Monitoring Overview

  Integration and Exception Monitoring details

Key Takeaways

• Unified Monitoring: SAP Cloud ALM enables centralised monitoring and management of both SAP andthird party components systems, providing a centralized entry point for IT operations.
• OpenTelemetry Integration: Leveraging the OpenTelemetry Java Agent and Collector allows for seamless collection and forwarding of telemetry data (metrics, logs, traces) from external systems such as Tomcat servers.
• API-Driven Data Ingestion: SAP Cloud ALM’s raw inbound APIs facilitate direct ingestion of external telemetry data, supporting use cases like Health Monitoring, Real User Monitoring, Exception Monitoring and more.
• Step-by-Step Configuration: The integration process involves instrumenting the external system, registering it in SAP Cloud ALM, obtaining API credentials, configuring the OpenTelemetry Collector, and activating data collection in the relevant SAP Cloud ALM applications.
• Security and Authentication: Secure authentication is achieved using service credentials (client ID, client secret, and token URL) when configuring the OpenTelemetry Collector to communicate with SAP Cloud ALM.
• Operational Visibility: Once configured, IT teams gain real-time visibility into the health, performance, and exceptions of external systems, enhancing proactive management and troubleshooting.
• Extensibility: The approach is adaptable to a wide range of third party componentsworkloads and can be extended to additional applications and signal types as needed.

Link Collection

• RAW inbound APIs
• Expert Portal
  • Health Monitoring
  • Real User Monitoring
  • Integration and Exception Monitoring 
• OpenTelemetry
  • Java Agent
  • Java Agent Releases 
  • Collector
  • Custom Collector
  • Collector Contrib Release
  • Collector Oauth Extension

Glossary

BTP Cockpit (SAP Business Technology Platform Cockpit): is the web console for administering SAP BTP: manage accounts and regions, assign entitlements, provision services, configure environments and connectivity, handle users/roles and security, and monitor usage and billing.

OTel (OpenTelemetry): open-source observability framework that standardizes collection of telemetry data - traces, metrics, and logs- from applications and services, providing vendor-neutral SDKs, APIs, and agents to export data to backends for monitoring and analysis.

JMX (Java Management Extensions): Java technology for monitoring and managing applications, JVMs, and resources via MBeans, enabling runtime configuration, metrics, and operations through standard APIs and remote connectors (e.g., JMX RMI).