The process engine reports runtime metrics to the database that can help draw conclusions about usage, load, and performance of the Camunda Platform. Metrics are reported in the database tables ACT_RU_METER_LOG and ACT_RU_TASK_METER_LOG. Single metric entries in ACT_RU_METER_LOG consist of a metric identifier, a value as natural number in the Java long range that the metric took in a certain timespan and a name identifying the metric reporter. Task metric entries in ACT_RU_TASK_METER_LOG comprise a fixed-length, pseudonymized assignee value and the point in time it was assigned at. There is a set of built-in metrics that are reported by default.

Built-in Metrics

The following table describes the built-in metrics. The identifiers of all built-in metrics are available as constants of the class org.camunda.bpm.engine.management.Metrics .

Heads Up!

If you are an enterprise customer, your license agreement might require you to report some metrics annually. Please store root-process-instance-start, activity-instance-start, executed-decision-instances and executed-decision-elements metrics from ACT_RU_METER_LOG as well as task metrics from ACT_RU_TASK_METER_LOG for at least 18 months until they were reported.

Category Identifier Description
BPMN Execution root-process-instance-start* The number of root process instance executions started. This is also known as Process Instances (PI). A root process instance has no parent process instance, i.e. it is a top-level execution.
activity-instance-start* The number of flow node instances (activity instances) started (FNI).
activity-instance-end The number of flow node instances (activity instances) ended.
DMN Execution executed-decision-instances* The number of evaluated decision instances (DI). A decision instance is a DMN decision table or a DMN Literal Expression.
executed-decision-elements* The number of decision elements executed during evaluation of DMN decision tables. For one table, this is calculated as the number of clauses multiplied by the number of rules.
Job Executor job-successful The number of jobs successfully executed.
job-failed The number of jobs that failed to execute and that were submitted for retry. Every failed attempt to execute a job is counted.
job-acquisition-attempt The number of job acquisition cycles performed.
job-acquired-success The number of jobs that were acquired and successfully locked for execution.
job-acquired-failure The number of jobs that were acquired but could not be locked for execution due to another job executor locking/executing the jobs in parallel.
job-execution-rejected The number of successfully acquired jobs submitted for execution that were rejected due to saturated execution resources. This is an indicator that the execution thread pool's job queue is full.
job-locked-exclusive The number of exclusive jobs that are immediately locked and executed.
Task Metrics unique-task-workers* The number of task users (TU) that have served as assignees.
History Clean up history-cleanup-removed-process-instances The number of process instances removed by history clean up.
history-cleanup-removed-case-instances The number of case instances removed by history clean up.
history-cleanup-removed-decision-instances The number of decision instances removed by history clean up.
history-cleanup-removed-batch-operations The number of batch operations removed by history clean up.
history-cleanup-removed-task-metrics The number of task metrics removed by history clean up.

*Some enterprise agreements require annual reports of some metrics. Please store those metrics for at least 18 months.

Querying

Metrics can be queried by making a MetricsQuery offered by the ManagementService. For example, the following query retrieves the number of all executed activity instances throughout the entire history of reporting:

long numCompletedActivityInstances = managementService
  .createMetricsQuery()
  .name(Metrics.ACTIVTY_INSTANCE_START)
  .sum();

The metrics query offers filters #startDate(Date date) and #endDate(Date date) to restrict the collected metrics to a certain timespan. In addition, by using the filter #reporter(String reporterId) the results can be restricted to metrics collected by a specific reporter. This option can be useful when configuring more than one engine against the same database, for example in a cluster setup.

Task metrics can be queried by using the getUniqueTaskWorkerCount method offered by the ManagementService. This method accepts optional Date values for startTime and endTime to restrict the metric to a certain timespan. For example, the following statement retrieves the number of all unique task workers until now:

long numUniqueTaskWorkers = managementService.getUniqueTaskWorkerCount(null, null);

Configuration

Metrics Reporter

The process engine flushes the collected metrics to the runtime database tables in an interval of 15 minutes. The behavior of metrics reporting can be changed by replacing the dbMetricsReporter instance of the process engine configuration. For example, to change the reporting interval, a process engine plugin replacing the reporter can be employed:

public class MetricsConfigurationPlugin implements ProcessEnginePlugin {

  public void preInit(ProcessEngineConfigurationImpl processEngineConfiguration) {
  }

  public void postInit(ProcessEngineConfigurationImpl processEngineConfiguration) {
    DbMetricsReporter metricsReporter = new DbMetricsReporter(processEngineConfiguration.getMetricsRegistry(),
        processEngineConfiguration.getCommandExecutorTxRequired());
    metricsReporter.setReportingIntervalInSeconds(5);

    processEngineConfiguration.setDbMetricsReporter(metricsReporter);
  }

  public void postProcessEngineBuild(ProcessEngine processEngine) {
  }

}

Note

Task metric entries are created on every assignment of a user task. This behavior cannot be modified and is not in the responsibility of the metrics reporter.

Reporter Identifier

Metrics are reported with an identifier of the reporting party. This identifier allows to attribute reports to individual engine instances when making a metrics query. For example in a cluster, load metrics can be related to individual cluster nodes. By default the process engine generates a reporter id as <local IP>$<engine name>. The generation can be customized by implementing the interface org.camunda.bpm.engine.impl.history.event.HostnameProvider and setting the engine property hostnameProvider to an instance of that class.

Heads Up!

The org.camunda.bpm.engine.impl.metrics.MetricsReporterIdProvider

interface and the corresponding metricsReporterIdProvider engine property have been deprecated.

Disable Reporting

By default, all built-in metrics are reported. For the configuration via XML file (e.g. standalone.xml or bpm-platform.xml) you can disable reporting by adding the properties:

<property name="metricsEnabled">false</property>
<property name="taskMetricsEnabled">false</property>

If you are directly accessing the Java API, you can disable the metrics reporting by using the engine configuration flags isMetricsEnabled and isTaskMetricsEnabled and set them to false.

On this Page: