Autoinstrumentation for Java

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 Buildback if:
    1. There is no entry for the parameter "buildpack"
    2. The value for the parameter buildpack is "sap_java_buildback"

You can find information on how to use the SAP Java Buildpack here.

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

SAP Java Build Pack Setup

If you are using the SAP Java Build pack:

  • 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 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": "otlp",

    "otel.metrics.exporter": "otlp",

    "otel.traces.exporter": "otlp",

    "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.8.0</version>

        <scope>runtime</scope>

    </dependency>

    <dependency>

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

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

        <version>1.5.20</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.8.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.20.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 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.8.0.jar

-Dotel.javaagent.extensions=BOOT-INF/lib/otel-agent-ext-java-1.5.20.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