OpenTelemetry in JBPM

 🚀 Introduction

Modern systems require end-to-end observability. By enabling OpenTelemetry (OTel) in jBPM, you can trace workflows, monitor task execution, and connect process events with external services.

This tutorial shows how to enable OpenTelemetry in jBPM using both:

• Java Agent (no code changes)
• Custom instrumentation (Process Event Listeners, WorkItemHandlers)

🧱 Prerequisites

• Running jBPM environment (KIE Server/Business Central on WildFly, or jBPM in Spring Boot)
• OpenTelemetry Java Agent (opentelemetry-javaagent.jar)
• Tracing backend (choose one):
• 🧭 Jaeger → http://localhost:4317 (OTLP gRPC)
• 📊 Grafana Tempo → OTLP gRPC
• Any vendor supporting OTLP

⚙️ Option A: Enable OTel with the Java Agent

WildFly (KIE Server / Business Central)

JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/otel/otel-agent.jar"
JAVA_OPTS="$JAVA_OPTS -Dotel.service.name=kie-server"
JAVA_OPTS="$JAVA_OPTS -Dotel.exporter.otlp.endpoint=http://localhost:4317"
JAVA_OPTS="$JAVA_OPTS -Dotel.traces.exporter=otlp -Dotel.metrics.exporter=otlp -Dotel.logs.exporter=otlp"
JAVA_OPTS="$JAVA_OPTS -Dotel.resource.attributes=service.namespace=jbpm,env=dev"

Spring Boot jBPM App

java -javaagent:/opt/otel/otel-agent.jar \
 -Dotel.service.name=jbpm-app \
 -Dotel.exporter.otlp.endpoint=http://localhost:4317 \
 -Dotel.traces.exporter=otlp -Dotel.metrics.exporter=otlp -Dotel.logs.exporter=otlp \
 -Dotel.resource.attributes=service.namespace=jbpm,env=dev \
 -jar target/jbpm-app.jar

🧠 Option B: Custom Instrumentation

Add Dependencies (Maven)

<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>latest</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-sdk</artifactId>
  <version>latest</version>
</dependency>
<dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-exporter-otlp</artifactId>
  <version>latest</version>
</dependency>

Process Event Listener Example

public class OtelProcessEventListener implements ProcessEventListener {
  private final Tracer tracer = GlobalOpenTelemetry.getTracer("jbpm");

  @Override
  public void beforeProcessStarted(ProcessStartedEvent event) {
    Span span = tracer.spanBuilder("process.start")
        .setAttribute("jbpm.process.id", event.getProcessInstance().getProcessId())
        .setAttribute("jbpm.instance.id", event.getProcessInstance().getId())
        .startSpan();
    span.end();
  }
}

Custom WorkItemHandler Example

Span span = tracer.spanBuilder("service.call").startSpan();
try (Scope s = span.makeCurrent()) {
  span.setAttribute("http.url", url);
  span.setAttribute("jbpm.task.name", workItem.getName());
  // call external service
} catch (Exception e) {
  span.recordException(e);
  span.setStatus(StatusCode.ERROR);
  throw e;
} finally {
  span.end();
}

🔗 Context Propagation

W3CTraceContextPropagator.getInstance()
  .inject(Context.current(), httpRequest, (req, k, v) -> req.addHeader(k, v));

🧪 Quick Test

• Deploy a simple process: Start → User Task → End
• Trigger a Service Task (HTTP)
• Open Jaeger/Tempo → verify:
• Process start span
• Node trigger spans
• External service span

📊 OpenTelemetry Architecture with jBPM

This diagram shows how jBPM integrates with the OpenTelemetry agent, which exports traces, metrics, and logs via OTLP to observability tools like Jaeger or Grafana Tempo.

🛠️ Troubleshooting

• No spans: verify -javaagent path + OTLP port (4317 gRPC vs 4318 HTTP).
• Unlinked services: check traceparent headers are passed.
• Too many spans: enable sampling:

  -Dotel.traces.sampler=parentbased_traceidratio
  -Dotel.traces.sampler.arg=0.2

👉 Watch Enable OpenTelemetry in JBPM in Action better:

Here's a quick video to help you understand Enable OpenTelemetry in JBPM in Action better: Coming soon 

🎯 Conclusion

By enabling OpenTelemetry in jBPM, you unlock full observability:

• End-to-end traces from processes to external services
• Correlated logs and metrics
• Faster debugging and performance monitoring

👉 Start with the Java Agent for zero-code setup, then add custom spans in EventListeners and WorkItemHandlers for rich process insights.

💼 Professional Support Available

If you are facing issues in real projects related to enterprise backend development or workflow automation, I provide paid consulting, production debugging, project support, and focused trainings.

Technologies covered include Java, Spring Boot, PL/SQL, Azure, and workflow automation (jBPM, Camunda BPM, RHPAM).

📧 Contact: ishikhanirankari@gmail.com | info@realtechnologiesindia.com

🌐 Website: IT Trainings | Digital lectern | Digital rostrum | Digital metal podium