Overview

Setup

Please verify if you are using the SAP Java buildpack.

  1. Open your mta.yaml file
  2. Search for the term "buildpack"
  3. You are using the SAP Java buildpack if:
    1. There is no entry for the parameter "buildpack"
    2. The value for the parameter buildpack is "sap_java_buildpack_jakarta"

You can find information on how to use the SAP Java buildpack here(opens in new tab).

If you are using SAP Java buildpack you do not need to perform the steps in section "Maven Setup".

SAP Java buildpack setup

If you are using the SAP Java buildpack:

  • Create a new user-provided service in the application's space named xotel-agent-ext-java with the following content:
{

    "account": "<name of subaccount in which the instrumented application is running>",


    "otel.logs.exporter": "none"

}
  • Create a binding to this service in the application
 
  • When your application is bound to a SAP Cloud Logging(opens in new tab) instance you can also configure the OTEL agent to send all logs, metrics and traces to SAP Cloud Logging. Just configure the corresponding exporters in your xotel-agent-ext-java user-provided service as follows:
{

    "account": "My_Account",

    "otel.logs.exporter": "cloud-logging",

    "otel.metrics.exporter": "cloud-logging",

    "otel.traces.exporter": "cloud-logging",

    "otel.instrumentation.logback-appender.experimental.capture-code-attributes": "true",

    "otel.instrumentation.logback-appender.experimental.capture-marker-attribute": "true",

    "otel.instrumentation.logback-appender.experimental.capture-key-value-pair-attributes": "true",

    "otel.experimental.resource.disabled-keys": "process.command_line,process.command_args,process.executable.path"

}

The OTEL parameters are described in the OpenTelemetry documentation:

Maven setup

If you are not using the SAP Java buildpack include the dependency in your pom.xml:

pom.xml 
<dependencies>


...


    <dependency>

        <groupId>io.opentelemetry.javaagent</groupId>

        <artifactId>opentelemetry-javaagent</artifactId>

        <version>2.24.0</version>

        <scope>runtime</scope>

    </dependency>

    <dependency>

        <groupId>com.sap.xdsr</groupId>

        <artifactId>otel-agent-ext-java</artifactId>

        <version>1.5.35.1</version>

        <scope>runtime</scope>

    </dependency>


...


</dependencies>


Add the following Java VM parameters via the mta.yaml:

mta.yaml 
modules:


  - name: <MyService>


    type: java


    ...


    properties:


      ...


      JBP_CONFIG_OPEN_JDK_JRE: "{ jre: { version: 11.+ }}"


      JBP_CONFIG_JAVA_OPTS: "[java_opts: '-javaagent:BOOT-INF/lib/opentelemetry-javaagent-2.24.0.jar -Dotel.javaagent.enabled=true -Dotel.resource.attributes=account=<name of subaccount in which the instrumented application is running>,calmTenantId=<id of subaccount in which the instrumented application is running>,otel.poll.service.type=SAP_CP_CF -Dotel.service.name=MyService -Dotel.propagators=sapuniversal -Dotel.traces.exporter=none -Dotel.metrics.exporter=none -Dotel.logs.exporter=none -Dotel.javaagent.extensions=BOOT-INF/lib/otel-agent-ext-java-1.5.35.1.jar' -Dotel.instrumentation.spring-boot-actuator-autoconfigure.enabled=true]"

Make sure to replace the following placeholders in the parameter JBP_CONFIG_JAVA_OPTS:

  • <MyService>: Name of the CF service
  • <subaccount name>: Name of the subaccount, where the instrumented application is running.
  • <subaccount id>: Technical ID of the subaccount, where the instrumented application is running. The technical ID can be found in the SAP BTP cockpit and has the form of a guid: 12345678-1234-1234-1234-123456789abc and will be used by SAP Cloud ALM to map the data to the corresponding cloud service.

Remarks:

  • Since the update of OpenTelemetry Agent to version 2.0.0 the following parameter has to be set in addition: -Dotel.logs.exporter=none
  • Since the update of OpenTelemetry Agent to version 2.2.0 the following parameter should be set in addition: -Dotel.instrumentation.spring-boot-actuator-autoconfigure.enabled=true
  • The .custom suffix can be used to override the service name with -Dotel.service.name.custom='demo-app'.
  • -Dotel.service.name.custom='demo-app' can be added in variable JBP_CONFIG_JAVA_OPTS in mta.yaml.

Additional parameters

We strongly recommend, that you normalize the requests to benefit from a good aggregation and to be able to use the requests for change point detection in Real User Monitoring.
The following parameter is available for this:

NameTypeDescription

urlNormalizerPatterns

Array<String>

A list of regular expression patterns to be applied on (server) URLs. This can be used to normalize URLs containing timestamps, GUIDs etc. The matching sub-strings will be replaced by an *. Example: ["(?<=$filter=|%24filter=).*?(?=&|%24|$)|(?<=$skip=|%24skip=)\d+|(?<=$top=|%24top=)\d+"]

 

Further optional parameters are:

NameTypeDescription

urlExclusionPatterns

Array<Pattern>

A list of regular expression patterns to be applied on (server) URLs to be excluded. Spans with such inbound URLs will simply not be sent to CALM. Example: ["/odata/v4/MyService/$metadata.*","/abc/internal/only.*"]

Additional steps for SAP BTP, KYMA runtime

  • During Dockerization unzip the contents of the application jar like below
  • Below is a sample Dockerfile
FROM maven:<version> as builder

COPY . /usr/src/build

WORKDIR /usr/src/build

RUN mvn clean install



FROM openjdk:11

COPY --from=builder /usr/src/build/target/<application-jar-name> app.jar



RUN jar -xvf app.jar # Extract of the contents of application jar



EXPOSE <PORT>

ENTRYPOINT ["java","-jar","/app.jar"]


Reference the OTEL JARs from the BOOT-INF in the environment variable JAVA_OPTS

spec:

replicas: 1

selector:

matchLabels:

app.name: <app-name>

template:

metadata:

labels:

app.name: <app-name>

spec:

containers:

- env:

- name: _JAVA_OPTIONS

value: >

-javaagent:BOOT-INF/lib/opentelemetry-javaagent-2.24.0.jar

-Dotel.javaagent.extensions=BOOT-INF/lib/otel-agent-ext-java-1.5.35.1.jar

-Dotel.service.name=MyService

-Dotel.propagators=sapuniversal -Dotel.traces.exporter=none

-Dotel.metrics.exporter=none -Dotel.logs.exporter=none

-Dotel.instrumentation.spring-boot-actuator-autoconfigure.enabled=true