Application Monitoring
The eximeebpms-bpm-monitor extension adds application-level monitoring for a Spring Boot application running EximeeBPMS. It exposes Micrometer counter and gauge meters via Spring Boot’s Actuator, which can be scraped by vendor-neutral monitoring systems such as Prometheus or forwarded to systems like Elastic.
This page documents the eximeebpms-bpm-monitor extension, which is optional and requires an extra dependency. For the process engine’s built-in, database-reported metrics that are always available, see Metrics.
Setup
Add the extension dependency to a Spring Boot application:
<dependency>
<groupId>org.eximeebpms.bpm.extension.monitor</groupId>
<artifactId>eximeebpms-bpm-spring-boot-monitor</artifactId>
</dependency>
The extension is automatically configured via Spring Boot’s auto-configuration mechanism — no additional annotations are required.
History Level Requirements
The extension’s counters are driven by the process engine’s history events, so they only fire for event types your configured eximeebpms.bpm.history-level actually produces. The extension’s gauges read live runtime tables directly and are unaffected by the history level.
| Meters | Minimum history-level |
|---|---|
eximeebpms.process.instances.started, .ended | activity |
eximeebpms.process.instances.finished.total | activity |
eximeebpms.incidents.created, .resolved, .deleted | full |
All gauges (*.running.total, *.open.total, *.open.age.*, jobs.failed.total, etc.) | none — read runtime tables directly |
eximeebpms.script.violations, .total | none — driven directly by the script-execution engine's own violation callback, not a history event or a runtime-table read |
At history-level: activity or audit, incident counters silently stay at zero — the engine simply never produces those history events at those levels, so no error is raised. The Spring Boot starter defaults eximeebpms.bpm.history-level to full, so this only matters if it has been explicitly lowered.
Metrics
Process Instances
| Meter | Type | Description |
|---|---|---|
eximeebpms.process.instances.started | Counter | Incremented when a process instance starts. |
eximeebpms.process.instances.ended | Counter | Incremented when a process instance ends. |
eximeebpms.process.instances.running.total | Gauge | Number of currently running process instances, per process definition. |
eximeebpms.process.instances.running.suspended.total | Gauge | Number of currently suspended process instances, per process definition. |
eximeebpms.process.instances.finished.total | Gauge | Number of finished process instances currently eligible for history clean up, per process definition. |
Incidents
| Meter | Type | Description |
|---|---|---|
eximeebpms.incidents.created | Counter | Incremented when an incident is created. |
eximeebpms.incidents.resolved | Counter | Incremented when an incident is resolved. |
eximeebpms.incidents.deleted | Counter | Incremented when an incident is deleted. |
eximeebpms.incidents.open.total | Gauge | Number of currently open incidents, per process definition. |
eximeebpms.incidents.open.age.newest.seconds | Gauge | Age, in seconds, of the newest currently open incident, per process definition. |
eximeebpms.incidents.open.age.oldest.seconds | Gauge | Age, in seconds, of the oldest currently open incident, per process definition. |
The three counters above require history-level: full — see History Level Requirements. The gauges are unaffected.
Tasks
| Meter | Type | Description |
|---|---|---|
eximeebpms.tasks.open.total | Gauge | Number of currently open tasks. |
eximeebpms.tasks.open.age.newest.seconds | Gauge | Age, in seconds, of the newest currently open task. |
eximeebpms.tasks.open.age.oldest.seconds | Gauge | Age, in seconds, of the oldest currently open task. |
External Tasks
| Meter | Type | Description |
|---|---|---|
eximeebpms.external.tasks.open.total | Gauge | Number of currently open external tasks. |
eximeebpms.external.tasks.open.error.total | Gauge | Number of currently open external tasks that have a recorded error from a failed execution attempt. |
Jobs
| Meter | Type | Description |
|---|---|---|
eximeebpms.jobs.failed.total | Gauge | Number of currently failing jobs (jobs with a recorded exception), per process definition. This is a live snapshot, not a lifetime counter. |
Script Guard
| Meter | Type | Description |
|---|---|---|
eximeebpms.script.violations | Counter | Incremented on every Script Guard rule violation, tagged with the offending script's context (see Tags). |
eximeebpms.script.violations.total | Counter | Total Script Guard violations recorded since the instance started, independent of tag values. |
See Script Guard for what a rule violation is and how the underlying policy is configured.
Tags
Meters are tagged as follows:
- Process instance meters (counters
started/ended):process.definition.idprocess.definition.key
- Process instance gauges (
running,suspended,finished):tenant.idprocess.definition.idprocess.definition.key
- Incident meters:
tenant.idprocess.definition.idprocess.definition.keyactivity.idfailed.activity.idincident.type
- User task meters (related to a process instance):
tenant.idprocess.definition.idprocess.definition.keytask.definition.key
- User task gauges (related to a case instance):
tenant.idcase.definition.idtask.definition.key
- User task meters (stand-alone, not related to a process or case instance):
tenant.idtask.name
- External task meters:
tenant.idprocess.definition.idprocess.definition.keyactivity.idtopic.name
- Failed job gauge:
tenant.idprocess.definition.idprocess.definition.key
Configuration
The extension provides the following Spring Boot properties:
| Property | Default | Description |
|---|---|---|
eximeebpms.monitoring.snapshot.enabled | true | Whether gauge snapshot monitoring is enabled. In a cluster with multiple instances sharing the same database, only one running instance needs this enabled. |
eximeebpms.monitoring.snapshot.updateRate | 10000 | Rate, in milliseconds, at which the snapshot of gauge metrics is refreshed. |
Cluster Considerations
When running in a cluster with a shared database, only one instance needs to poll the gauge metrics, since they provide the current snapshot from the database and would report the same value on every node (e.g. eximeebpms.process.instances.running.total). All instances, however, should have their counter metrics monitored, since each counts only what happened on that instance since it started.
Set eximeebpms.monitoring.snapshot.enabled=true on a single instance in the cluster and false on the rest to avoid redundant gauge polling.
Reporting Limitations
The extension’s counters do not look up EximeeBPMS’s history database, which keeps it lightweight and scalable. When an instance restarts or crashes, its counters reset to zero — so counter values in the monitoring system may not be exact. This is acceptable for application monitoring but not for reporting use cases that require exact figures. For exact reporting, use the history database directly or a history event handler — see History Configuration.