Integrate the OTEL agent with the Community Implementation and enable metric collection.

Rustam Lotsmanenko (EPAM)
2026-04-15T13:24:50Z

### Description
Enable OpenTelemetry auto-instrumentation using the OpenTelemetry Java agent and the shared CI/CD pipeline. This implementation must not require application source code changes and must remain fully runtime-configurable via Helm values and CI variables.

This task standardizes OTEL enablement across Community Implementation services.

---

### Scope

Applies to: `{service}-core-plus` repositories.

---

### 1. Helm Template Update

File:
`devops/core-plus/deploy/templates/configmap.yaml`

Add the following block:

```
{{- if .Values.data.javaToolOptions }}
JAVA_TOOL_OPTIONS: {{ .Values.data.javaToolOptions | quote }}
OTEL_EXPORTER_OTLP_ENDPOINT: {{ .Values.data.otelExporterEndpoint | quote}}
OTEL_EXPORTER_OTLP_PROTOCOL: {{ .Values.data.otelExporterProtocol | quote}}
{{- end }}
```

This ensures OTEL variables are injected only when explicitly configured.

Example: https://community.opengroup.org/osdu/platform/system/indexer-service/-/blob/master/devops/core-plus/deploy/templates/configmap.yaml#L28

---

### 2. Helm Values Update

File:
`devops/core-plus/deploy/values.yaml`

Under `data`, add:

```
javaToolOptions: ""
otelExporterEndpoint: ""
otelExporterProtocol: ""
```

These values are populated via CI/CD `--set` overrides.

Example: https://community.opengroup.org/osdu/platform/system/indexer-service/-/blob/master/devops/core-plus/deploy/values.yaml#L22

---

### 3. CI/CD Integration

File:
`.gitlab-ci.yml`

Include the shared OTEL pipeline:

```
- project: "osdu/platform/ci-cd-pipelines"
file: "build/cimpl-otel.yml"
```

Example: https://community.opengroup.org/osdu/platform/system/indexer-service/-/blob/master/.gitlab-ci.yml?ref_type=heads#L71

---

### 4. Docker Image Update

File:
`{service}-core-plus/cloudbuild/Dockerfile`

Add:

```
ENV JAVA_TOOL_OPTIONS=""
COPY otel/opentelemetry-javaagent.jar /app/telemetry/opentelemetry-javaagent.jar
CMD java $JAVA_TOOL_OPTIONS ...
```

This ensures:

* The agent is packaged inside the container.
* Runtime arguments can activate instrumentation.
* OTEL remains optional and environment-driven.

Example: https://community.opengroup.org/osdu/platform/system/indexer-service/-/blob/master/indexer-core-plus/cloudbuild/Dockerfile?ref_type=heads#L15

---

### 5. Documentation Update

File:
`{service}-core-plus/docs/baremetal/README.md`

Add the following entries to the environment variables table:

| Variable | Example | Description | Required |
| --------------------------- | ----------------------------------------------------- | ---------------------------------------------------------------- | -------- |
| OTEL_EXPORTER_OTLP_ENDPOINT | [http://127.0.0.1:4318](http://127.0.0.1:4318) | OpenTelemetry collector endpoint | no |
| OTEL_EXPORTER_OTLP_PROTOCOL | grpc | OpenTelemetry collector protocol | no |
| JAVA_TOOL_OPTIONS | -javaagent:/app/telemetry/opentelemetry-javaagent.jar | Extends runtime arguments to enable the OpenTelemetry Java agent | no |

Add section:

~~~
### OpenTelemetry Integration

The `opentelemetry-javaagent.jar` file is the OpenTelemetry Java agent. It is used to automatically instrument a Java application at runtime without requiring manual changes to the source code.

This provides critical observability features:

* **Distributed tracing:** Traces the path of requests as they travel across different services.
* **Metrics:** Captures performance indicators and application-level metrics.
* **Logs:** Correlates logs with traces and other telemetry data.

Enabling this agent makes it significantly easier to monitor, debug, and manage the application in development and production environments. The agent is activated via runtime arguments when the `JAVA_TOOL_OPTIONS` environment variable includes the `-javaagent:/app/telemetry/opentelemetry-javaagent.jar` argument.

The agent is available from the official OpenTelemetry GitHub repository. It is recommended to use the latest stable version.

Official Download Page: https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases

~~~

Example: https://community.opengroup.org/osdu/platform/system/indexer-service/-/blob/master/indexer-core-plus/docs/baremetal/README.md?ref_type=heads

---

### Acceptance Criteria

* Service builds successfully.
* Deployment works with OTEL disabled (default empty values).
* When CI variables are set, telemetry is exported to the configured collector.
* Docker image contains `/app/telemetry/opentelemetry-javaagent.jar`.
* Documentation updated accordingly.
* Telemetry is available at https://jaeger.dev1.osdu-cimpl.opengroup.org/search

---

### Notes

* No application code changes are required.
* Instrumentation is fully controlled via environment variables.
* Configuration is centrally managed through the shared CI/CD pipeline.