blob: f789d612a1437ea7aa2ad708ac6cb5cf26e31826 [file] [log] [blame]
Antoine Mussoa8eea7d2013-10-05 16:08:00 +02001:title: Statsd reporting
2
3Statsd reporting
4================
5
6Zuul comes with support for the statsd protocol, when enabled and configured
Michael Prokop526926a2013-10-24 16:16:57 +02007(see below), the Zuul scheduler will emit raw metrics to a statsd receiver
Antoine Mussoa8eea7d2013-10-05 16:08:00 +02008which let you in turn generate nice graphics. An example is OpenStack Zuul
9status page: http://status.openstack.org/zuul/
10
11Configuration
12-------------
13
14Statsd support uses the statsd python module. Note that Zuul will start without
15the statsd python module, so an existing Zuul installation may be missing it.
16
Michael Prokop526926a2013-10-24 16:16:57 +020017The configuration is done via environment variables STATSD_HOST and
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020018STATSD_PORT. They are interpreted by the statsd module directly and there is no
Michael Prokop526926a2013-10-24 16:16:57 +020019such parameter in zuul.conf yet. Your init script will have to initialize both
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020020of them before launching Zuul.
21
22Your 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
29Metrics
30-------
31
32The 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
Joshua Heskethe8987162014-03-13 13:05:33 +110069 metrics holds both an increasing counter and a timing
70 reporting the duration of the build. Whenever the result is a
71 SUCCESS or FAILURE, Zuul will additionally report the duration
72 of the build as a timing event.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020073
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