| Antoine Musso | a8eea7d | 2013-10-05 16:08:00 +0200 | [diff] [blame^] | 1 | :title: Statsd reporting |
| 2 | |
| 3 | Statsd reporting |
| 4 | ================ |
| 5 | |
| 6 | Zuul comes with support for the statsd protocol, when enabled and configured |
| 7 | (see below), the Zuul scheduler will emit raw metrics to a Statsd receiver |
| 8 | which let you in turn generate nice graphics. An example is OpenStack Zuul |
| 9 | status page: http://status.openstack.org/zuul/ |
| 10 | |
| 11 | Configuration |
| 12 | ------------- |
| 13 | |
| 14 | Statsd support uses the statsd python module. Note that Zuul will start without |
| 15 | the statsd python module, so an existing Zuul installation may be missing it. |
| 16 | |
| 17 | The configuration is done via environnement variables STATSD_HOST and |
| 18 | STATSD_PORT. They are interpreted by the statsd module directly and there is no |
| 19 | such paremeter in zuul.conf yet. Your init script will have to initialize both |
| 20 | of them before launching Zuul. |
| 21 | |
| 22 | Your init script most probably loads a configuration file named |
| 23 | ``/etc/default/zuul`` which would contain the environment variables:: |
| 24 | |
| 25 | $ cat /etc/default/zuul |
| 26 | STATSD_HOST=10.0.0.1 |
| 27 | STATSD_PORT=8125 |
| 28 | |
| 29 | Metrics |
| 30 | ------- |
| 31 | |
| 32 | The metrics are emitted by the Zuul scheduler (`zuul/scheduler.py`): |
| 33 | |
| 34 | **gerrit.events.<type> (counters)** |
| 35 | Gerrit emits different kind of message over its `stream-events` interface. As |
| 36 | a convenience, Zuul emits metrics to statsd which save you from having to use |
| 37 | a different daemon to measure Gerrit events. |
| 38 | The Gerrit events have different types defined by Gerrit itself, Zuul will |
| 39 | relay any type of event reusing the name defined by Gerrit. Some of the |
| 40 | events emitted are: |
| 41 | |
| 42 | * patchset-created |
| 43 | * draft-published |
| 44 | * change-abandonned |
| 45 | * change-restored |
| 46 | * change-merged |
| 47 | * merge-failed |
| 48 | * comment-added |
| 49 | * ref-updated |
| 50 | * reviewer-added |
| 51 | |
| 52 | Refer to your Gerrit installation documentation for an exhaustive list of |
| 53 | Gerrit event types. |
| 54 | |
| 55 | **zuul.pipeline.** |
| 56 | Holds metrics specific to jobs. The hierarchy is: |
| 57 | |
| 58 | #. **<pipeline name>** as defined in your `layout.yaml` file (ex: `gate`, |
| 59 | `test`, `publish`). It contains: |
| 60 | |
| 61 | #. **all_jobs** counter of jobs triggered by the pipeline. |
| 62 | #. **current_changes** A gauge for the number of Gerrit changes being |
| 63 | processed by this pipeline. |
| 64 | #. **job** subtree detailing per jobs statistics: |
| 65 | |
| 66 | #. **<jobname>** The triggered job name. |
| 67 | #. **<build result>** Result as defined in your triggering system. For |
| 68 | Jenkins that would be SUCCESS, FAILURE, UNSTABLE, LOST. The |
| 69 | metrics holds both an increasing counter and a timing reporting |
| 70 | the duration of the build. Whenever the result is a SUCCESS or |
| 71 | FAILURE, Zuul will additionally report the duration of the |
| 72 | build as a timing event. |
| 73 | |
| 74 | #. **resident_time** timing representing how long the Change has been |
| 75 | known by Zuul (which includes build time and Zuul overhead). |
| 76 | #. **total_changes** counter of the number of change proceeding since |
| 77 | Zuul started. |
| 78 | |
| 79 | Additionally, the `zuul.pipeline.<pipeline name>` hierarchy contains |
| 80 | `current_changes` and `resident_time` metrics for each projects. The slash |
| 81 | separator used in Gerrit name being replaced by dots. |
| 82 | |
| 83 | As an example, given a job named `myjob` triggered by the `gate` pipeline |
| 84 | which took 40 seconds to build, the Zuul scheduler will emit the following |
| 85 | statsd events: |
| 86 | |
| 87 | * `zuul.pipeline.gate.job.myjob.SUCCESS` +1 |
| 88 | * `zuul.pipeline.gate.job.myjob` 40 seconds |
| 89 | * `zuul.pipeline.gate.all_jobs` +1 |