Health Monitoring Custom Java Metrics
for SAP BTP, Cloud Foundry environment

On this page it is explained how to enable manual instrumentation for a Java microservice, specifically for handling PaaS scenarios in SAP BTP, Cloud Foundry environment.

By default, the automatic instrumentation collects and reports numerous metrics to Health Monitoring. However, if customers wish to report their own metrics using the OpenTelemetry (OTEL) agent extension, they can follow the steps outlined in this documentation.

This document provides information about exporters. The exporters are already included in the OTEL Java agent provided by SAP. Additionally, the meter is registered in the OTEL Java extension and is configured to collect metrics every minute.

 

Setting up Custom Instrumentation

The following declarations are essential for setting up custom instrumentation with the OTEL Java agent:

 

Step 1 - Setup of OpenTelemetry 

private static final OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();

private static final Meter meter = openTelemetry.getMeter("your package");

This first line initializes the OpenTelemetry object using the globally accessible GlobalOpenTelemetry instance. This object serves as the entry point to the OpenTelemetry API, allowing you to create and manage various telemetry components, such as metrics and traces.

This second line creates a meter object using the OpenTelemetry instance. The getMeter method initializes the meter with the specified name, "com.sap.crun.landscape.aspect.ReportOtelCustomAspect". This meter is used to collect and report custom metrics specific to the application, in this case, every minute.

These declarations ensure that your Java microservice can use OpenTelemetry to capture and export custom metrics effectively.

 

Step 2 - Setting up a Custom Metric 

 private final ObservableLongMeasurement successfulJobCounter;

        private final ObservableLongMeasurement failedJobCounter;



        successfulJobCounter = meter.gaugeBuilder("custom.total.success")

                .setDescription("successful jobs")

                .setUnit("1")

                .ofLongs()

                .buildObserver();



        failedJobCounter = meter.gaugeBuilder("custom.total.failure")

                .setDescription("failed Jobs")

                .setUnit("1")

                .ofLongs()

                .buildObserver();

  • ObservableLongMeasurement is a component in the OpenTelemetry metrics API that allows you to observe and record long integer values. This is useful for capturing and monitoring specific metrics over time, such as the number of successful jobs, request counts, or other numeric data points.
  • It finalizes the configuration and constructs an observer metric based on the builder settings.
  • The buildObserver() plays a crucial role in completing the metric configuration and creating an observer metric instance ready for use in monitoring and reporting the number of successful System Landscape Information Service (SLIS) import jobs.


Step 3 - Configuring Batch Metric Recording with OpenTelemetry 

meter.batchCallback(

                () -> {

                    recordMeasurement();

                },

                successfulJobCounter,

                failedJobCounter);



    private void recordMeasurement() {

        Attributes attributes =

                Attributes.builder()

                        .put(stringKey("space"),"cfSpace")

                        .build();



        successfulJobCounter.record(totalSlisImportSuccess, attributes);

        failedJobCounter.record(totalSlisImportFailure, attributes);

    }

The meter.batchCallback() method sets up a function (callback) to execute a batch of operations when triggered.

It calls recordMeasurement() to record metrics using successfulJobCounter and failedJobCounter and it allows for efficient and controlled batch processing of metrics in applications using OpenTelemetry.