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.tasks.created, .completed, .deleted | activity |
eximeebpms.incidents.created, .resolved, .deleted | full |
eximeebpms.external.tasks.started, .ended | full |
All gauges (*.running.total, *.open.total, *.open.age.*, jobs.failed.total, etc.) | none — read runtime tables directly |
| Script Guard meters | none — sourced from Script Guard's own violation store, independent of history events |
At history-level: activity or audit, incident and external task 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.created | Counter | Incremented when a user task is created. |
eximeebpms.tasks.completed | Counter | Incremented when a user task is completed. |
eximeebpms.tasks.deleted | Counter | Incremented when a task is deleted directly (e.g. via the Task API). Does not increment when a task is removed as a side effect of deleting its parent process instance — the engine does not produce a history event on that path. |
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. |
The eximeebpms.tasks.created, eximeebpms.tasks.completed, and eximeebpms.tasks.deleted counters cannot distinguish tasks that belong to a case instance — only tasks belonging to a process instance are tagged as such, all other tasks are tagged as stand-alone (see Tags below).
eximeebpms.tasks.deleted only fires for tasks deleted directly through the Task API (typically stand-alone tasks — a task attached to a running process instance cannot be deleted that way). When a process instance is deleted and takes its open tasks with it, no corresponding history event is produced, so this counter under-counts that scenario.
External Tasks
| Meter | Type | Description |
|---|---|---|
eximeebpms.external.tasks.started | Counter | Incremented when an external task is created. |
eximeebpms.external.tasks.ended | Counter | Incremented when an external task completes successfully or is deleted. A failed execution attempt alone (with retries remaining) does not increment this counter — see eximeebpms.external.tasks.open.error.total for currently failing external tasks. |
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. |
started and ended require history-level: full — see History Level Requirements. The gauges are unaffected.
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 violation. |
eximeebpms.script.violations.total | Gauge | Live total violation count, read from the violation store on each scrape. Returns 0 when Script Guard is disabled. |
See Script Guard for details on violation detection and enforcement modes.
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
- Script Guard violations counter:
process.definition.keyactivity.idlanguageoriginrule.code
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.