Integrating OpenTelemetry Java Agent in digiRunner

digiRunner is a Java web application developed based on the Spring Boot framework. The integration method of the OpenTelemetry Java Agent is the same as with typical Spring Boot applications—by configuring the Java Agent parameters. This document explains how to integrate OpenTelemetry into digiRunner within a containerized environment and provides practical command examples.

Dockerfile for the digiRunner Application Image

Below is a sample Dockerfile used by digiRunner. The image is built on Azul’s lightweight OpenJDK 21 distribution: azul/zulu-openjdk-alpine:21.

FROM azul/zulu-openjdk-alpine:21

RUN set -eux; \
    apk update; \
    apk upgrade; \
    apk add --no-cache curl; \
    mkdir -p /app; \
    rm -rf /var/cache/apk/*;

WORKDIR /opt/dgr-v4

COPY ./dgrv4_Gateway_serv/build/libs/H2/ .

ENV TAEASK=TsmpAESEncryptionActionSecretKey
ENV APP_ROOT_DIR=/opt/dgr-v4

RUN set -eux && \
    adduser -D tpiuser && \
    mkdir -p /opt/dgr-v4/h2dir /opt/dgr-v4/apilogs && \
    chown -R tpiuser:tpiuser /opt
USER tpiuser

ENTRYPOINT [ \
    "java", \
    "-cp", \
    "app-cp/*" \
]

CMD [ \
    "-Xms2g", \
    "-Xmx4g", \
    "-Dloader.path=lib/,libsext/", \
    "-Djava.security.debug=properties", \
    "-Djava.security.properties=./config/dgr.java.security", \
    "-Dspring.config.location=file:./config/", \
    "-DdigiRunner.token.key-store.path=./keys", \
    "-Djasypt.encryptor.privateKeyLocation=file:./keys/enc.pem", \
    "-Dfile.encoding=UTF-8", \
    "-Dlogging.config=file:./config/logback.xml", \
    "-Dserver.port=18080", \
    "-Dspring.profiles.active=local", \
    "org.springframework.boot.loader.launch.PropertiesLauncher" \
]

Sample docker run Command to Run digiRunner

Here is a basic docker run command to start the digiRunner container. You can adjust it based on your environment:

docker run -d \
  -e TZ=Asia/Taipei \
  -e TAEASK=TsmpAESEncryptionActionSecretKey \
  -p 28080:28080 \
  localhost/apim/digirunner:v4.5.2.0 \
  -Xms2048m -Xmx2048m \
  -XX:MaxMetaspaceSize=256m -XX:MaxDirectMemorySize=128m \
  -Xss512k \
  -Dserver.undertow.direct-buffers=true \
  -Dserver.undertow.threads.io=4 \
  -Dserver.undertow.threads.worker=24 \
  -Dasync.max-pool-size=2000 \
  -Dasync.highway-pool-size-rate=0.5 \
  -Dloader.path=lib/,libsext/ \
  -Dfile.encoding=UTF-8 \
  -Dlogging.config=file:config/logback.xml \
  -Dspring.profiles.active=local \
  -Dserver.ssl.enabled=false \
  -Dserver.port=28080 \
  -Dspring.datasource.url=jdbc:h2:tcp://172.27.1.100:9091/./h2dir/dgrdb;NON_KEYWORDS=VALUE;Mode=MySQL \
  -Dspring.sql.init.mode=never \
  -DdigiRunner.gtw.deploy.role=Landing \
  -Ddigi.instance.id=dgR-Slave01-28080 \
  -Djob.start.enable=false \
  org.springframework.boot.loader.launch.PropertiesLauncher

Enabling OpenTelemetry Auto-Instrumentation

To enable OpenTelemetry’s automatic tracing and telemetry capabilities in a Java application, follow these steps:

1. Use the -v option to mount the OpenTelemetry Java Agent JAR into the container.

2. Add the -javaagent option to the Java startup parameters to load the agent.

3. Configure the required OpenTelemetry system properties or environment variables.

Example: docker run Command with OpenTelemetry Java Agent Integration

docker run -d \
  -e TZ=Asia/Taipei \
  -e TAEASK=TsmpAESEncryptionActionSecretKey \
  -p 28080:28080 \
  -v /path/to/opentelemetry-javaagent.jar:/opt/dgr-v4/opentelemetry-javaagent.jar \
  localhost/apim/digirunner:v4.5.2.0 \
  -Xms2048m -Xmx2048m \
  -XX:MaxMetaspaceSize=256m -XX:MaxDirectMemorySize=128m \
  -Xss512k \
  -javaagent:/opt/dgr-v4/opentelemetry-javaagent.jar \
  -Dotel.service.name=digirunner-service \
  -Dotel.traces.exporter=otlp \
  -Dotel.metrics.exporter=otlp \
  -Dotel.logs.exporter=otlp \
  -Dotel.exporter.otlp.endpoint=http://your-otel-collector:4317 \
  -Dserver.undertow.direct-buffers=true \
  -Dserver.undertow.threads.io=4 \
  -Dserver.undertow.threads.worker=24 \
  -Dasync.max-pool-size=2000 \
  -Dasync.highway-pool-size-rate=0.5 \
  -Dloader.path=lib/,libsext/ \
  -Dfile.encoding=UTF-8 \
  -Dlogging.config=file:config/logback.xml \
  -Dspring.profiles.active=local \
  -Dserver.ssl.enabled=false \
  -Dserver.port=28080 \
  -Dspring.datasource.url=jdbc:h2:tcp://172.27.1.100:9091/./h2dir/dgrdb;NON_KEYWORDS=VALUE;Mode=MySQL \
  -Dspring.sql.init.mode=never \
  -DdigiRunner.gtw.deploy.role=Landing \
  -Ddigi.instance.id=dgR-Slave01-28080 \
  -Djob.start.enable=false \
  org.springframework.boot.loader.launch.PropertiesLauncher

Key Changes Explained

Mount OpenTelemetry Agent	Use -v to mount the agent JAR from the host into the container: -v /path/to/opentelemetry-javaagent.jar:/opt/dgr-v4/opentelemetry-javaagent.jar
Enable Java Agent	Add -javaagent to enable the agent functionality: -javaagent:/opt/dgr-v4/opentelemetry-javaagent.jar
Set Service Name	-Dotel.service.name=digirunner-service is used to identify the service source
Enable Trace Export	-Dotel.traces.exporter=otlp uses OTLP protocol to send trace data
Enable Metrics Export	-Dotel.metrics.exporter=otlp uses OTLP protocol to send metric data
Enable Logs Export	-Dotel.logs.exporter=otlp uses OTLP protocol to send log data
Set Export Endpoint	-Dotel.exporter.otlp.endpoint=http://your-otel-collector:4317 should be replaced with your OpenTelemetry Collector URL

Notes

• Replace /path/to/opentelemetry-javaagent.jar with the actual file path to your OpenTelemetry agent JAR on the host machine.

• Replace http://your-otel-collector:4317 with your actual deployed OpenTelemetry Collector endpoint.

• For TLS support, authentication, advanced sampling settings, or other custom configurations, refer to the official OpenTelemetry Java Agent documentation.

• OpenTelemetry Java Agent official documents