tutorial

Monitoring jBPM with Vigilmon

jBPM is Red Hat's open source BPMN 2.0 workflow engine — here's how to monitor KIE Server health, process instance throughput, human task queues, SLA compliance, Business Central, Quartz scheduling, database persistence, and JVM health with Vigilmon.

jBPM is Red Hat's open source Business Process Management suite implementing the BPMN 2.0 specification. When you self-host jBPM, you run a multi-tier stack: the KIE Server (the BPMN execution runtime), Business Central (the web workbench for authoring and deployment), a relational database for process persistence, and the Quartz scheduler for timer events. Process instances — automating loan approvals, onboarding workflows, order fulfillment — live in this stack. A silent crash of any component can leave hundreds of process instances stuck at human tasks, miss SLA deadlines, and cause timer events to never fire. Vigilmon gives you end-to-end visibility across every layer of the jBPM stack.

What You'll Set Up

  • KIE Server health monitor (BPMN execution runtime)
  • Process instance throughput and active count monitors
  • Human task queue depth monitor with SLA thresholds
  • Process instance SLA violation alerts
  • Business Central availability monitor
  • Database persistence health check
  • Quartz scheduler health via cron heartbeat
  • KIE Server container deployment status check
  • JVM heap and GC health monitor

Prerequisites

  • jBPM 7.x or Red Hat Process Automation Manager (RHPAM) deployed on a server
  • KIE Server accessible on its REST port (default 8080)
  • Business Central accessible (default 8080 on the same or separate host)
  • A free Vigilmon account

Step 1: Monitor KIE Server Health

KIE Server is the execution heart of jBPM. When it goes down, no new BPMN process instances can start and no existing instances progress. Monitor its REST health endpoint first.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. URL: http://your-kie-server:8080/kie-server/services/rest/server
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Under Keyword check, enter "status":"UP" to verify KIE Server reports itself healthy, not just that Tomcat responded.
  7. Click Save.

The KIE Server REST info endpoint returns a JSON response including the server version, capabilities, and status. A 500 or absence of "status":"UP" means the KIE Server container failed to initialize.

If KIE Server is behind a reverse proxy or secured with basic auth, add the Authorization: Basic <base64> header under Custom headers in the monitor settings.

Step 2: Monitor Active Process Instance Count

A healthy jBPM deployment has a relatively stable number of active process instances at any given time. A sudden spike indicates a backlog is forming — human tasks are not being completed, or a system integration is failing to advance instances through wait states.

Use the KIE Server REST API query endpoint to count active instances:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kie-server:8080/kie-server/services/rest/server/queries/processes/instances?status=1&page=0&pageSize=0
  3. Method: GET
  4. Expected HTTP status: 200
  5. Check interval: 2 minutes
  6. Click Save.

For threshold-based alerting on the count value, expose a thin health wrapper around this query from your application code:

// Spring Boot actuator custom endpoint example
@ReadOperation
public Map<String, Object> activeInstances() {
    long count = queryService.countProcessInstancesByState(ProcessInstance.STATE_ACTIVE);
    Map<String, Object> result = new HashMap<>();
    result.put("activeInstances", count);
    result.put("status", count < 500 ? "ok" : "warning");
    return result;
}

Then point Vigilmon at http://your-app:8080/actuator/active-instances with a keyword check for "status":"ok".

Step 3: Monitor Process Instance Throughput

Process instance throughput — the rate at which new BPMN instances are created — is your leading indicator of upstream system health. If your order management system normally starts 50 process instances per minute and that drops to zero, something upstream is broken even if KIE Server itself is healthy.

Expose a throughput metric from your application layer:

// Micrometer counter — increment when each process instance starts
Counter.builder("jbpm.process.instances.started")
    .tag("process", processId)
    .register(meterRegistry)
    .increment();

Expose this via a /metrics or /actuator/prometheus endpoint and configure an alert:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/jbpmThroughput (a custom health indicator)
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 2 minutes
  6. Click Save.

A custom HealthIndicator can check that the 5-minute rolling instance creation count is above your expected minimum, giving Vigilmon a clean HTTP signal to monitor.

Step 4: Monitor Human Task Queue Depth

jBPM's human tasks are the manual checkpoints in your BPMN processes — loan officer approvals, manager sign-offs, customer verification steps. When the queue backs up beyond your SLA threshold, real business processes are falling behind.

Query the KIE Server task API to count pending tasks:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kie-server:8080/kie-server/services/rest/server/queries/tasks/instances?status=Ready&status=Reserved&page=0&pageSize=0
  3. Method: GET
  4. Expected status: 200
  5. Check interval: 2 minutes
  6. Click Save.

For SLA-aware alerting, create a dedicated health endpoint in your application:

@ReadOperation
public Health taskQueueHealth() {
    long pendingTasks = taskService.getTasksOwnedByStatus(
        userId, Arrays.asList(Status.Ready, Status.Reserved), "en-UK"
    ).size();
    
    if (pendingTasks > 1000) {
        return Health.down()
            .withDetail("pendingTasks", pendingTasks)
            .withDetail("threshold", 1000)
            .build();
    }
    return Health.up().withDetail("pendingTasks", pendingTasks).build();
}

Set Alert after: 2 consecutive failures to avoid noise from momentary spikes.

Step 5: Monitor Process SLA Violations

BPMN processes often carry SLA timers — a loan application must complete within 48 hours, a support ticket within 24 hours. When SLA deadlines are missed, it's a business compliance issue, not just a technical one.

Expose SLA violation counts from your application:

// Query process instances that have exceeded their SLA
List<ProcessInstanceDesc> slaViolations = queryService.getProcessInstancesByVariable(
    "slaStatus", Arrays.asList("Violated"), new QueryContext()
);

// Expose as a health indicator
if (slaViolations.size() > 0) {
    return Health.down()
        .withDetail("slaViolations", slaViolations.size())
        .build();
}
  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/jbpmSla
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 5 minutes
  6. Click Save.

Configure the alert to notify your business operations team (not just the on-call engineer) — SLA violations are a business escalation, not a purely technical incident.

Step 6: Monitor Business Central

Business Central is the web workbench where your team authors BPMN process definitions, manages deployments, and monitors running instances. Its unavailability blocks process development and KJAR redeployments.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-business-central:8080/business-central
  3. Expected status: 200
  4. Keyword check: Business Central (appears in the page title)
  5. Check interval: 2 minutes
  6. Enable Monitor SSL certificate if Business Central is HTTPS-exposed, with expiry alert at 21 days.
  7. Click Save.

Business Central has higher resource requirements than KIE Server — it's the more likely of the two to become unresponsive under JVM memory pressure.

Step 7: Monitor Database Persistence

jBPM stores all process instance state in a relational database. A lost database connection means process instances cannot persist state changes — any instance that tries to advance will fail with a persistence exception, effectively freezing your entire workflow automation.

Monitor the database from your application's connection pool health:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health/db
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

Spring Boot's built-in DataSourceHealthIndicator covers this automatically. For manual verification, expose a lightweight SQL probe:

@ReadOperation
public Health databaseHealth() {
    try {
        jdbcTemplate.queryForObject("SELECT 1", Integer.class);
        return Health.up().build();
    } catch (Exception e) {
        return Health.down().withException(e).build();
    }
}

Set Alert after: 1 failure — database loss is immediately critical and should never be suppressed.

Step 8: Monitor Quartz Scheduler with a Heartbeat

jBPM uses Quartz for all BPMN timer events: boundary timers, intermediate catching timer events, and deadline escalations. When Quartz stops, all timer-based process transitions cease — processes that should escalate after 24 hours will wait indefinitely.

Add a Quartz heartbeat job to your application that pings Vigilmon on each successful scheduler tick:

@Component
public class QuartzHealthHeartbeat implements Job {
    
    private final RestTemplate restTemplate;
    private final String vigilmonHeartbeatUrl;
    
    @Override
    public void execute(JobExecutionContext context) {
        // Verify Quartz itself scheduled and fired this job
        restTemplate.getForObject(vigilmonHeartbeatUrl, String.class);
    }
}

Register this job with a 5-minute interval in your Quartz configuration. In Vigilmon:

  1. Click Add Monitor → Heartbeat.
  2. Set Name to jBPM Quartz Scheduler.
  3. Set Expected ping interval to 10 minutes (2× the job interval, giving tolerance for one missed fire).
  4. Copy the heartbeat URL and paste it as vigilmonHeartbeatUrl in your job configuration.
  5. Click Save.

If Vigilmon does not receive a ping within 10 minutes, the alert fires — meaning Quartz has stopped scheduling or the scheduler thread pool is exhausted.

Step 9: Monitor KIE Server Container Deployment Health

jBPM processes are packaged as KJARs (KIE Java Archives) and deployed to KIE Server as containers. A failed KJAR deployment means the associated BPMN processes are unavailable — new instances cannot start and existing instances cannot advance past wait states that require the process definition.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-kie-server:8080/kie-server/services/rest/server/containers
  3. Method: GET
  4. Expected status: 200
  5. Keyword check: "status":"STARTED" — all healthy containers report STARTED status.
  6. Check interval: 2 minutes
  7. Click Save.

If any container reports FAILED or is absent from the list, the keyword check will not match and the alert fires. You can also add a container-specific check:

http://your-kie-server:8080/kie-server/services/rest/server/containers/my-process-kjar_1.0.0

This is useful for production where you know the exact container ID of your deployed processes.

Step 10: Monitor JVM Heap and GC

jBPM's KIE Server and Business Central both run on the JVM. Large working memories (from Drools rule sessions running alongside jBPM), many active process instances, and aggressive BPMN event logging can all push heap usage toward the limit.

Expose JVM health via Spring Boot Actuator or the JVM Micrometer metrics:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: http://your-app:8080/actuator/health
  3. Expected status: 200
  4. Keyword check: "status":"UP"
  5. Check interval: 1 minute
  6. Click Save.

For heap-specific alerting, create a custom health indicator:

@Component
public class HeapHealthIndicator implements HealthIndicator {
    
    @Override
    public Health health() {
        MemoryMXBean memBean = ManagementFactory.getMemoryMXBean();
        long used = memBean.getHeapMemoryUsage().getUsed();
        long max = memBean.getHeapMemoryUsage().getMax();
        double pct = (double) used / max * 100;
        
        if (pct > 85) {
            return Health.down()
                .withDetail("heapUsedPct", String.format("%.1f%%", pct))
                .build();
        }
        return Health.up()
            .withDetail("heapUsedPct", String.format("%.1f%%", pct))
            .build();
    }
}

A heap above 85% in KIE Server is a leading indicator of OutOfMemoryError, which instantly terminates all in-flight BPMN process executions.

Alerting Configuration

In Vigilmon, configure alert channels to match the severity of each component:

KIE Server health — alert immediately on 1 failure to your on-call engineer and your process automation team. All BPMN execution stops.

Database persistence — alert immediately on 1 failure. Process state loss is unrecoverable for in-flight instances.

Quartz scheduler — alert after 10 minutes of missed heartbeat. A few late timer events are recoverable; a stopped scheduler is not.

Human task queue — alert after 2 consecutive threshold breaches. Notify your business operations team, not just engineering.

SLA violations — alert every breach to both engineering (root cause) and the business owners (compliance).

Business Central — alert after 2 consecutive failures. Unavailability is serious but brief restarts are common.

JVM heap — alert above 85%. Include a Restart runbook link in the alert notification.

Conclusion

A self-hosted jBPM deployment runs a complex stack where a failure in any layer — KIE Server, Business Central, the database, or the Quartz scheduler — can silently freeze your BPMN workflow automation. With Vigilmon monitoring each layer independently, you get precise failure isolation: you know immediately whether it's KIE Server that crashed, the database that dropped, or the Quartz scheduler that stopped, rather than waiting for users to report that their workflows are stuck. The combination of HTTP monitors for service health and a heartbeat monitor for Quartz gives you complete coverage of the jBPM operational surface.

Start with the free Vigilmon account and have your first KIE Server monitor running in under five minutes.

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles