Bonita Runtime Monitoring

For Enterprise and Performance editions only.

Discover how to monitor a runtime environment running Bonita

Monitoring metrics can be published via 3 channels:

  • JMX

  • Log file

  • Prometheus endpoint

Why monitoring ?

Monitoring a Production environment is crucial to ensure the runtime is correctly sized and tuned, along with detecting abnormal behavior.

Bonita provides a series of technical and Bonita-related metrics to monitor the health of Bonita runtime environment.
Some metrics are enabled by default and cannot be disabled. Some others are optional and can be enabled according to your needs.

Glossary

Work: a unitary piece of code that executes parts of process instances, tasks, BPM elements…​ and allows the processes to move forwards. It executes in a Java thread.

Connector work: a unit piece of code that specifically executes Bonita connectors.

Work queue: a queue storing pending works before they are taken by threads for execution.

What can be monitored?

The runtime uses Micrometer to produce and publish metrics. Metrics are indicators (generally numeric values) giving information on the system. They can be technical (number of running threads on the JVM), or more Bonita-oriented (total number of connectors executed).

Bonita-related metrics

Bonita-related metrics are enabled by default and cannot be disabled. Here are the provided metrics:

  • The number of currently running works, under the logical key name bonita_bpmengine_work_running_works

  • The number of currently pending works, waiting in the work queue to be treated, under the logical key name bonita_bpmengine_work_pending_works

  • The total number of executed works (since the last start of Bonita runtime), under the logical key name bonita_bpmengine_work_executed_works_total

  • The number of currently running connector works, under the logical key name bonita_bpmengine_connector_running_connectors

  • The number of currently pending connector works, waiting in the connector work queue to be treated, under the logical key name bonita_bpmengine_connector_pending_connectors

  • The total number of executed connector works (since the last start of Bonita runtime), under the logical key name bonita_bpmengine_connector_executed_connectors_total

  • The total number of BPMN message couples executed (since the last start of Bonita runtime), under the logical key name bonita_bpmengine_message_executed_messages_total

  • The total number of BPMN message couples potentially matched (since the last start of Bonita runtime), under the logical key name bonita_bpmengine_message_potential_messages_total (starting from 7.10.3)

  • The total number of BPMN message matching tasks retriggered (since the last start of Bonita runtime), under the logical key name bonita_bpmengine_message_retriggeredtasks_messages_matching_tasks_total (starting from 7.10.3)

Technical metrics

The following available metrics are disabled by default and can be enabled.

  • Several metrics related to JVM memory, under the logical key names jvm.memory.* and jvm.buffer.*

  • Several metrics related to JVM threads, under the logical key name jvm.threads.*

  • Several metrics related to JVM garbage collection, under the logical key name jvm.gc.*

  • Several metrics related to Worker / Connector thread pools, under the logical key name executor.*

  • Several metrics related to Hibernate statistics, under the logical key name hibernate.*

  • Several metrics related to Tomcat, under the logical key name tomcat.*

When Bonita is deployed in a cluster (Enterprise and Performance editions only), HTTP sessions are shared between all the nodes of the cluster, so the metric tomcat.sessions.active.current represents the number of active sessions over all the cluster. The other metrics remain relative to each node of the cluster.

How to retrieve those metrics

Those metrics are published on publishers. Publishers are responsible for exposing the activated metrics. They are channels on which metrics are published. Provided metric publishers are JMX, Log files, Prometheus.

JMX Publisher

The JMX publisher publishes each metric using MBeans. All those MBeans are in the domain metrics.

It can be enabled using the property org.bonitasoft.engine.monitoring.publisher.jmx.enable set to true.

Metrics exposed by the JMX publisher can be consulted by any JMX tool, like the JDK-provided JMX Console.

Log file Publisher

The log file publisher publishes to a file using the logger com.bonitasoft.engine.monitoring.LoggingMeterRegistry with the log level INFO.

It can be enabled using the property org.bonitasoft.engine.monitoring.publisher.logging.enable set to true.

Metrics are logged every 1 minute by default. It can be changed using the property org.bonitasoft.engine.monitoring.logging.step.

Prometheus Publisher

The Prometheus publisher publishes to a REST endpoint in the Prometheus format, that can easily be consumed by Prometheus and then displayed by graphical tools like Grafana, etc.

The endpoint is exposed at:

http://<SERVER_URL>/bonita/metrics

Use this URL to configure your installed Prometheus configuration in order to record and display the metrics. The default URL can be changed in the web.xml file of the tomcat bundle.

Sample extract of exposed Prometheus data:

# HELP jvm_buffer_memory_used_bytes An estimate of the memory that the Java virtual machine is using for this buffer pool
# TYPE jvm_buffer_memory_used_bytes gauge
jvm_buffer_memory_used_bytes{id="direct",} 565248.0
jvm_buffer_memory_used_bytes{id="mapped",} 0.0
# HELP bonita_bpmengine_connector_pending
# TYPE bonita_bpmengine_connector_pending gauge
bonita_bpmengine_connector_pending{tenant="1",} 0.0
# HELP bonita_bpmengine_connector_executed_total
# TYPE bonita_bpmengine_connector_executed_total counter
bonita_bpmengine_connector_executed_total{tenant="1",} 0.0
# HELP bonita_bpmengine_work_running
# TYPE bonita_bpmengine_work_running gauge
bonita_bpmengine_work_running{tenant="1",} 0.0
# HELP jvm_gc_max_data_size_bytes Max size of old generation memory pool
# TYPE jvm_gc_max_data_size_bytes gauge
jvm_gc_max_data_size_bytes 7.16177408E8
# HELP bonita_bpmengine_work_pending
# TYPE bonita_bpmengine_work_pending gauge
bonita_bpmengine_work_pending{tenant="1",} 0.0
# HELP tomcat_servlet_request_max_seconds
# TYPE tomcat_servlet_request_max_seconds gauge
tomcat_servlet_request_max_seconds{name="default",} 0.0
tomcat_servlet_request_max_seconds{name="dispatcherServlet",} 0.104
...

This endpoint is protected with Basic access authentication to protect against DOS attacks.
Thus, when reaching this endpoint, you will have to manually enter the configured username and password information for your access to be granted.

These credentials can be consulted and modified:

Configuration

Retrieve current configuration by running:

./setup/setup.sh pull

Edit file ./setup/platform_conf/current/platform_engine/bonita-platform-sp-custom.properties

You will see, in the # MONITORING section, a series of properties with their default value:

In the first section, PUBLISHERS can be activated / deactivated and configured.

# PUBLISHERS = where to publish?
# publish metrics to Prometheus
com.bonitasoft.engine.plugin.monitoring.publisher.prometheus.enable=true
# publish metrics to JMX:
org.bonitasoft.engine.monitoring.publisher.jmx.enable=true
# periodically print metrics to logs (bonita related only):
org.bonitasoft.engine.monitoring.publisher.logging.enable=false
# print to logs every minute by default (ISO-8601 duration):
org.bonitasoft.engine.monitoring.publisher.logging.step=PT1M

In the second section, metrics can be activated.

# METRICS = what to publish?
# Note: Bonita-related metrics are automatically published.
# They are active by default and cannot be disabled.
#
# publish technical metrics related to Worker / Connector thread pools:
org.bonitasoft.engine.monitoring.metrics.executors.enable=false
# publish technical metrics related to HIBERNATE statistics
# To activate, simply set property (in file 'bonita-platform-community-custom.properties') 'bonita.platform.persistence.generate_statistics=true'
# publish metrics related to JVM memory:
org.bonitasoft.engine.monitoring.metrics.jvm.memory.enable=false
# publish metrics related to JVM Threads:
org.bonitasoft.engine.monitoring.metrics.jvm.threads.enable=false
# publish metrics related to JVM garbage collection:
org.bonitasoft.engine.monitoring.metrics.jvm.gc.enable=false
# publish technical metrics related to Tomcat (if in a Tomcat context):
org.bonitasoft.engine.monitoring.metrics.tomcat.enable=false

To change any value, uncomment the line by removing the # character, and change the true / false value.
Then push your configuration changes to database:

./setup/setup.sh push

Then restart the Tomcat server for the changes to take effect.