blob: fb6989ef41f27f96ddbb90c683934f1ddc0d84f1 [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
Paul Belanger174a8272017-03-14 13:20:10 -040020of them before executing Zuul.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020021
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
Bruno Tavaresf9af4cd2015-10-15 14:55:51 -030034**gerrit.event.<type> (counters)**
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020035 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
Bruno Tavaresf9af4cd2015-10-15 14:55:51 -030055**zuul.node_type.**
56 Holds metrics specifc to build nodes per label. The hierarchy is:
57
58 #. **<build node label>** each of the labels associated to a build in
59 Jenkins. It contains:
60
61 #. **job.<jobname>** subtree detailing per job statistics:
62
63 #. **wait_time** counter and timer of the wait time, with the
Paul Belanger174a8272017-03-14 13:20:10 -040064 difference of the job start time and the execute time, in
Bruno Tavaresf9af4cd2015-10-15 14:55:51 -030065 milliseconds.
66
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020067**zuul.pipeline.**
68 Holds metrics specific to jobs. The hierarchy is:
69
70 #. **<pipeline name>** as defined in your `layout.yaml` file (ex: `gate`,
71 `test`, `publish`). It contains:
72
73 #. **all_jobs** counter of jobs triggered by the pipeline.
74 #. **current_changes** A gauge for the number of Gerrit changes being
75 processed by this pipeline.
76 #. **job** subtree detailing per jobs statistics:
77
78 #. **<jobname>** The triggered job name.
79 #. **<build result>** Result as defined in your triggering system. For
80 Jenkins that would be SUCCESS, FAILURE, UNSTABLE, LOST. The
Joshua Heskethe8987162014-03-13 13:05:33 +110081 metrics holds both an increasing counter and a timing
82 reporting the duration of the build. Whenever the result is a
83 SUCCESS or FAILURE, Zuul will additionally report the duration
84 of the build as a timing event.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020085
86 #. **resident_time** timing representing how long the Change has been
87 known by Zuul (which includes build time and Zuul overhead).
88 #. **total_changes** counter of the number of change proceeding since
89 Zuul started.
Bruno Tavaresf9af4cd2015-10-15 14:55:51 -030090 #. **wait_time** counter and timer of the wait time, with the difference
Paul Belanger174a8272017-03-14 13:20:10 -040091 of the job start time and the execute time, in milliseconds.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020092
93 Additionally, the `zuul.pipeline.<pipeline name>` hierarchy contains
Bruno Tavaresf9af4cd2015-10-15 14:55:51 -030094 `current_changes` (gauge), `resident_time` (timing) and `total_changes`
95 (counter) metrics for each projects. The slash separator used in Gerrit name
96 being replaced by dots.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020097
98 As an example, given a job named `myjob` triggered by the `gate` pipeline
99 which took 40 seconds to build, the Zuul scheduler will emit the following
100 statsd events:
101
102 * `zuul.pipeline.gate.job.myjob.SUCCESS` +1
103 * `zuul.pipeline.gate.job.myjob` 40 seconds
104 * `zuul.pipeline.gate.all_jobs` +1