<commit_before>.. _realtime_monitoring:

###################
Realtime monitoring
###################

Gatling provides live statistics via the Graphite protocol so that you don't have to wait for the generation of the final report to analyse the simulation.
The graphite protocol is widely suppported by a number of tools. This includes both serverside monitoring and analytics databases.

In this way you can also monitor what happens in Gatling AND the system under test. All the data can be collected in one central repository for correlation.

The sections below describe both systems that collect data (Gatling, collectd, "Powershell functions", etc) and tools that recieve and process the data (Graphite, InfluxDB, and other timeseries databases).

The data the gatling pumps out via the graphite protocol can also be used to customize, tailor to your specific needs, the console output see below.

Metrics
=======

Two types of metrics are provided by Gatling  :
 * Users metrics
 * Requests metrics

Gatling pushes this data to Graphite every second by default, but the push frequency can be changed by setting the "writeInterval" in the GraphiteDataWriter section of gatling.conf

User metrics
------------

Users metrics give you, for each scenario of your simulation (or all scenarios using *allUsers*) :

* *waiting* : # of users waiting to start the scenario
* *active* : # of users currently running the scenario
* *done* : # of users who have completed the scenario

The metric path for users metrics is *gatling.scenarioName.users.metric*, where :

* *scenarioName* is the name of your scenario
* *metric* is one of the metrics described above

Request metrics
---------------

Requests metrics give you, for each request (or all requests using _allRequests_) and by status (OK, KO and both) :

* *count* : requests/sec
* *min* and *max* : Min and Max response time for the request
* *percentilesXX* :  1st, 2nd, 3rd and 4th percentiles, as defined in gatling.conf (defaults are 95th and 99th percentiles)

The metric path for requests metrics is *gatling.simulationId.requestName.status.metric*, where :

* *simulationId* is a sanitized named computed from the name of your Simulation, or the one you set in the command line prompt
* *requestName* is the name of your request
* *status* is either **ok** (for successful requests), **ko** (for failed requests) or **all** (for both successful and failed requests)
* *metric* is one of the metrics described above

System under test metrics
-------------------------

The system under test can send realtime data as follows to provide good visibility. This could be anything from cpu utilisation to database reads.
Following the "unix philosophy" sending the data to timeseries database and charting engines provides high quality monitoring and allows Gatling to focus on the load generation.

* For *Linux* collectd can collect system metrics and has plugins for a number of products such as mysql.
* For *Windows* "Graphite-PowerShell-Functions" on Github exposes windows performance counters to the graphite protocol.

For a complete list of tools that support sending data using the graphite protocol see: http://graphite.readthedocs.org/en/latest/tools.html


Configuration
=============

Gatling needs to be configured to send metrics.
In addition the tool that recieves and processes the data needs to be configured. For example one of Graphite, InfluxDB or other timeseries database that supports the Graphite protocol.


Gatling Configuration
---------------------

In ``$GATLING_HOME/conf/gatling.conf``, be sure to :

* have the GraphiteDataWriter in the list of writers
* have the correct host and port for Graphite

::

  data {
    writers = "console, file, graphite"
    reader = file

    graphite {
      host = "192.168.56.101"
      port = 2003
      #light = false              # only send the all* stats
      #protocol = "tcp"           # The protocol used to send data to Carbon (currently supported : "tcp", "udp")
      #rootPathPrefix = "gatling" # The common prefix of all metrics sent to Graphite<commit_msg>Fix writers format in conf sample in realtime monitoring page, close #2590<commit_after>.. _realtime_monitoring:

###################
Realtime monitoring
###################

Gatling provides live statistics via the Graphite protocol so that you don't have to wait for the generation of the final report to analyse the simulation.
The graphite protocol is widely suppported by a number of tools. This includes both serverside monitoring and analytics databases.

In this way you can also monitor what happens in Gatling AND the system under test. All the data can be collected in one central repository for correlation.

The sections below describe both systems that collect data (Gatling, collectd, "Powershell functions", etc) and tools that recieve and process the data (Graphite, InfluxDB, and other timeseries databases).

The data the gatling pumps out via the graphite protocol can also be used to customize, tailor to your specific needs, the console output see below.

Metrics
=======

Two types of metrics are provided by Gatling  :
 * Users metrics
 * Requests metrics

Gatling pushes this data to Graphite every second by default, but the push frequency can be changed by setting the "writeInterval" in the GraphiteDataWriter section of gatling.conf

User metrics
------------

Users metrics give you, for each scenario of your simulation (or all scenarios using *allUsers*) :

* *waiting* : # of users waiting to start the scenario
* *active* : # of users currently running the scenario
* *done* : # of users who have completed the scenario

The metric path for users metrics is *gatling.scenarioName.users.metric*, where :

* *scenarioName* is the name of your scenario
* *metric* is one of the metrics described above

Request metrics
---------------

Requests metrics give you, for each request (or all requests using _allRequests_) and by status (OK, KO and both) :

* *count* : requests/sec
* *min* and *max* : Min and Max response time for the request
* *percentilesXX* :  1st, 2nd, 3rd and 4th percentiles, as defined in gatling.conf (defaults are 95th and 99th percentiles)

The metric path for requests metrics is *gatling.simulationId.requestName.status.metric*, where :

* *simulationId* is a sanitized named computed from the name of your Simulation, or the one you set in the command line prompt
* *requestName* is the name of your request
* *status* is either **ok** (for successful requests), **ko** (for failed requests) or **all** (for both successful and failed requests)
* *metric* is one of the metrics described above

System under test metrics
-------------------------

The system under test can send realtime data as follows to provide good visibility. This could be anything from cpu utilisation to database reads.
Following the "unix philosophy" sending the data to timeseries database and charting engines provides high quality monitoring and allows Gatling to focus on the load generation.

* For *Linux* collectd can collect system metrics and has plugins for a number of products such as mysql.
* For *Windows* "Graphite-PowerShell-Functions" on Github exposes windows performance counters to the graphite protocol.

For a complete list of tools that support sending data using the graphite protocol see: http://graphite.readthedocs.org/en/latest/tools.html


Configuration
=============

Gatling needs to be configured to send metrics.
In addition the tool that recieves and processes the data needs to be configured. For example one of Graphite, InfluxDB or other timeseries database that supports the Graphite protocol.


Gatling Configuration
---------------------

In ``$GATLING_HOME/conf/gatling.conf``, be sure to :

* have the GraphiteDataWriter in the list of writers
* have the correct host and port for Graphite

::

  data {
    writers = [console, file, graphite]
    reader = file

    graphite {
      host = "192.168.56.101"
      port = 2003
      #light = false              # only send the all* stats
      #protocol = "tcp"           # The protocol used to send data to Carbon (currently supported : "tcp", "udp")
      #rootPathPrefix = "gatling" # The common prefix of all metrics sent to Graphite
{'fraction_non_alphanumeric': 0.08471499455403607, 'fraction_numerical': 0.0060510710395740045, 'mean_word_length': 3.9425837320574164, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 2, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6802731', 'n_tokens_mistral': 2134, 'n_tokens_neox': 2031, 'n_words': 1124}