blob: 9c699608844fe94641730707a13d55cb244014ac [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -07001:title: Monitoring
2
3Monitoring
4==========
Antoine Mussoa8eea7d2013-10-05 16:08:00 +02005
6Statsd reporting
James E. Blaireff5a9d2017-06-20 00:00:37 -07007----------------
Antoine Mussoa8eea7d2013-10-05 16:08:00 +02008
9Zuul comes with support for the statsd protocol, when enabled and configured
Michael Prokop526926a2013-10-24 16:16:57 +020010(see below), the Zuul scheduler will emit raw metrics to a statsd receiver
James E. Blaireff5a9d2017-06-20 00:00:37 -070011which let you in turn generate nice graphics.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020012
13Configuration
James E. Blaireff5a9d2017-06-20 00:00:37 -070014~~~~~~~~~~~~~
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020015
16Statsd support uses the statsd python module. Note that Zuul will start without
17the statsd python module, so an existing Zuul installation may be missing it.
18
Michael Prokop526926a2013-10-24 16:16:57 +020019The configuration is done via environment variables STATSD_HOST and
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020020STATSD_PORT. They are interpreted by the statsd module directly and there is no
Michael Prokop526926a2013-10-24 16:16:57 +020021such parameter in zuul.conf yet. Your init script will have to initialize both
Paul Belanger174a8272017-03-14 13:20:10 -040022of them before executing Zuul.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020023
24Your init script most probably loads a configuration file named
25``/etc/default/zuul`` which would contain the environment variables::
26
27 $ cat /etc/default/zuul
28 STATSD_HOST=10.0.0.1
29 STATSD_PORT=8125
30
31Metrics
James E. Blaireff5a9d2017-06-20 00:00:37 -070032~~~~~~~
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020033
James E. Blair91c9dde2017-08-04 11:10:24 -070034The metrics are emitted by the Zuul :ref:`scheduler`:
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020035
James E. Blair91c9dde2017-08-04 11:10:24 -070036.. stat:: gerrit.event.<type>
37 :type: counter
James E. Blaireff5a9d2017-06-20 00:00:37 -070038
James E. Blair91c9dde2017-08-04 11:10:24 -070039 Gerrit emits different kind of message over its `stream-events`
40 interface. Zuul will report counters for each type of event it
41 receives from Gerrit.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020042
James E. Blair91c9dde2017-08-04 11:10:24 -070043 Refer to your Gerrit installation documentation for a complete
44 list of Gerrit event types.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020045
James E. Blair91c9dde2017-08-04 11:10:24 -070046.. stat:: zuul.pipeline
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020047
James E. Blair91c9dde2017-08-04 11:10:24 -070048 Holds metrics specific to jobs. This hierarchy includes:
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020049
James E. Blair91c9dde2017-08-04 11:10:24 -070050 .. stat:: <pipeline name>
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020051
James E. Blair91c9dde2017-08-04 11:10:24 -070052 A set of metrics for each pipeline named as defined in the Zuul
53 config.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020054
James E. Blair91c9dde2017-08-04 11:10:24 -070055 .. stat:: all_jobs
56 :type: counter
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020057
James E. Blair91c9dde2017-08-04 11:10:24 -070058 Number of jobs triggered by the pipeline.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020059
James E. Blair91c9dde2017-08-04 11:10:24 -070060 .. stat:: current_changes
61 :type: gauge
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020062
James E. Blair91c9dde2017-08-04 11:10:24 -070063 The number of items currently being processed by this
64 pipeline.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +020065
James E. Blair91c9dde2017-08-04 11:10:24 -070066 .. stat:: job
67
68 Subtree detailing per jobs statistics:
69
70 .. stat:: <jobname>
71
72 The triggered job name.
73
74 .. stat:: <result>
75 :type: counter, timer
76
77 A counter for each type of result (e.g., ``SUCCESS`` or
78 ``FAILURE``, ``ERROR``, etc.) for the job. If the
79 result is ``SUCCESS`` or ``FAILURE``, Zuul will
80 additionally report the duration of the build as a
81 timer.
82
83 .. stat:: resident_time
84 :type: timer
85
86 A timer metric reporting how long each item has been in the
87 pipeline.
88
89 .. stat:: total_changes
90 :type: counter
91
92 The number of change processed by the pipeline since Zuul
93 started.
94
95 .. stat:: wait_time
96 :type: timer
97
98 How long each item spent in the pipeline before its first job
99 started.
100
101 .. stat:: <project>
102
103 This hierarchy holds more specific metrics for each project
104 participating in the pipeline. If the project name contains
105 a ``/`` character, it will be replaced with a ``.``.
106
107 .. stat:: current_changes
108 :type: gauge
109
110 The number of items of this project currently being
111 processed by this pipeline.
112
113 .. stat:: resident_time
114 :type: timer
115
116 A timer metric reporting how long each item for this
117 project has been in the pipeline.
118
119 .. stat:: total_changes
120 :type: counter
121
122 The number of change for this project processed by the
123 pipeline since Zuul started.
124
125As an example, given a job named `myjob` triggered by the `gate` pipeline
126which took 40 seconds to build, the Zuul scheduler will emit the following
127statsd events:
128
129 * ``zuul.pipeline.gate.job.myjob.SUCCESS`` +1
130 * ``zuul.pipeline.gate.job.myjob`` 40 seconds
131 * ``zuul.pipeline.gate.all_jobs`` +1