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 table ACT_RU_METER_LOG as natural numbers in the Java long range and count the occurrence of specific events. Single metric entries consist of a metric identifier, a value that the metric took in a certain timespan and a name identifying the metric reporter. 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 .

*Some enterprise agreements require annual reports of some metrics. Please store those metrics for at least 15 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.

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) {
  }

}

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.

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 property:

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

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