Table of contents


The benchmark configuration file is one of the required configuration files necessary to run a Caliper benchmark. In contrast to the runtime configurations, used for tweaking the internal behavior of Caliper, the benchmark configuration pertains only to the execution of the benchmark workload and collection of the results.

Note: In theory, a benchmark configuration is independent of the system under test (SUT) and the internal configuration of Caliper. However, this independence might be limited by the implementation details of the benchmark workload module, which could target only a single SUT type.

The benchmark configuration consists of three main parts:

For a complete benchmark configuration example, refer to the last section.

Note: The configuration file can be either a YAML or JSON file, conforming to the format described below. The benchmark configuration file path can be specified for the manager and worker processes using the caliper-benchconfig setting key.

Benchmark test settings

The settings related to the benchmark workload all reside under the root test attribute, which has some general child attributes, and the important rounds attribute.

Attribute Description Short name of the benchmark to display in the report.
test.description Detailed description of the benchmark to display in the report.
test.workers Object of worker-related configurations.
test.workers.type Currently unused.
test.workers.number Specifies the number of worker processes to use for executing the workload.
test.rounds Array of objects, each describing the settings of a round.
test.rounds[i].label A short name of the rounds, usually corresponding to the types of submitted TXs.
test.rounds[i].txNumber The number of TXs Caliper should submit during the round.
test.rounds[i].txDuration The length of the round in seconds during which Caliper will submit TXs.
test.rounds[i].rateControl The object describing the rate controller to use for the round.
test.rounds[i].workload The object describing the workload module used for the round.
test.rounds[i].workload.module The path to the benchmark workload module implementation that will construct the TXs to submit
test.rounds[i].workload.arguments Arbitrary object that will be passed to the workload module as configuration.

A benchmark configuration with the above structure will define a benchmark run that consists of multiple rounds. Each round is associated with a rate controller that is responsible for the scheduling of TXs, and a workload module that will generate the actual content of the scheduled TXs.

Monitoring settings

The monitoring configuration determines what kind of metrics the manager process can gather and from where. The configuration resides under the monitors attribute. Refer to the monitors configuration page for the details.


The example configuration below says the following:

  • Perform the benchmark run using 5 worker processes.
  • There will be two rounds.
  • The first init round will submit 500 TXs at a fixed 25 TPS send rate.
  • The content of the TXs are determined by the init.js workload module.
  • The second query round will submit TXs for 60 seconds at a fixed 5 TPS send rate.
  • The content of the TXs are determined by the query.js workload module.
  • The manager process will allow a Prometheus server to scrape information on port 3000 with a default scrape url of /metrics
  • The manager process should include the predefined metrics of all local Docker containers in the report.
  • The manager process should include the custom metric Endorse Time (s) based on the provided query for every available (peer) instance.
    number: 5
    - label: init
      txNumber: 500
        type: fixed-rate
          tps: 25
        module: benchmarks/samples/fabric/marbles/init.js
    - label: query
      txDuration: 60
        type: fixed-rate
          tps: 5
        module: benchmarks/samples/fabric/marbles/query.js
  - module: prometheus
  - module: docker
      interval: 1
      containers: ['all']
  - module: prometheus
      url: "http://prometheus:9090"
        include: [dev-.*, couch, peer, orderer]
        - name: Endorse Time (s)
          query: rate(endorser_propsal_duration_sum{chaincode="marbles:v0"}[5m])/rate(endorser_propsal_duration_count{chaincode="marbles:v0"}[5m])
          step: 1
          label: instance
          statistic: avg


The Caliper codebase is released under the Apache 2.0 license. Any documentation developed by the Caliper Project is licensed under the Creative Commons Attribution 4.0 International License. You may obtain a copy of the license, titled CC-BY-4.0, at