# 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

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

#### **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](https://opentelemetry.io/docs/zero-code/java/agent/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tpi.dev/most-common-use-cases/integrating-opentelemetry-java-agent-in-digirunner.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.