Reporting

The Gatling DSE plugin comes with a dedicated reporting component. This page explains how it works, its limits and how to use it.

HDR Histograms

HDR histograms are a data structure created to store response times. It has become a standard when it comes to benchmarking. It allows to record every single latency in constant space.

To use them, one must provide a maximum trackable value and a resolution. The resolution is the number of significant digits that should be recorded.

For instance, let’s record a latency of 1.234ms with 3 significants digits. The HDR histogram will store a latency of 1.230ms. This results in a ±1% different between the actual and the recorded latency. This trade-off is what makes the constant space feature possible.

Gatling support

Out of the box, Gatling does not support HDR histograms. It can only record latencies in files, or percentiles in a Graphite server.

To compensate this, the Gatling DSE plugins comes with its own reporting. It is able to write HDR histograms per query, per group and globally. For instance, let’s consider a benchmark that has the following queries:

• Group Admin, query Publish blog post

• Group User, query Read blog post

• Group User, query Comment blog post

With the "per query" reporting, three HDR histograms will be created. One for Publish blog post, one for Read post and one for Comment. With the "per group" reporting, two more HDR histograms will be created. One for the Admin group and one for the User group. Finally, with the "global" reporting, one last HDR histogram will be created. It will store all the latencies, regardless of the group/query.

Note that failures (KO) are reported in separate HDR histograms.

Per-second latency

Latencies are reported with one HDR histogram per second. They are indexed by request send time. This is important to keep in mind when correlating latencies with events.

For example, let’s consider a request r that was sent at t=60s. The response was received 3 seconds after r was sent. As a result, the histogram for t=60s will contain one latency equal to 3s.

Configuration

The reporting component can be configured in a dse-plugin.conf file. This file must reside at the root of the classpath.

metrics {
  hgrm {
    enabled = true                 # Enable HDR reporting (default: true)
    directory = hgrms              # Target subdirectory in results folder

    logWriter {
      warmUp = 0ms                 # Don't record anything during the fist ...s
      delay = 10s                  # Delay writing each latency by ...s
      interval = 5s                # Write per-second histograms every ...s
    }

    default {                      # Default values for all histograms
      enabled = false
      highestTrackableValue = 10m  # Highest response time for CQL/Graph
      resolution = 3               # Keep 3 significant digits
    }
    query {
      enabled = true               # Always record per-query latencies
      #highestTrackableValue = 10m
      #resolution = 3
    }
    group {
      #enabled = false
      #highestTrackableValue = 10m
      #resolution = 3
    }
    global {
      #enabled = false
      #highestTrackableValue = 10m
      #resolution = 3
    }
  }
}

The most important parameters are:

• metrics.hgrm.logWriter.warmUp defines how many seconds at the start of the benchmark to ignore. This may corresponds to the duration of a warm-up group in your simulation.

• metrics.hgrm.logWriter.delay defines the time to wait before considering a histogram complete.

• metrics.hgrm.*.highestTrackableValue defines the biggest latency that can be measured. Latencies higher than that value will be truncated. This is in order to not crash Gatling during a potentially long benchmark.