Gitiles
Code Review Sign In
gerrit.cesnet.cz / github / openstack-infra / zuul / e19e88a66a50b152f3a9b8165065e02992184ce5 / . / doc / source / admin / monitoring.rst
blob: 9c699608844fe94641730707a13d55cb244014ac [file] [log] [blame]
James E. Blaireff5a9d2017-06-20 00:00:37 -0700[diff] [blame]1:title: Monitoring
2
3Monitoring
4==========
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]5
6Statsd reporting
James E. Blaireff5a9d2017-06-20 00:00:37 -0700[diff] [blame]7----------------
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]8
9Zuul comes with support for the statsd protocol, when enabled and configured
Michael Prokop526926a2013-10-24 16:16:57 +0200[diff] [blame]10(see below), the Zuul scheduler will emit raw metrics to a statsd receiver
James E. Blaireff5a9d2017-06-20 00:00:37 -0700[diff] [blame]11which let you in turn generate nice graphics.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]12
13Configuration
James E. Blaireff5a9d2017-06-20 00:00:37 -0700[diff] [blame]14~~~~~~~~~~~~~
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]15
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 +0200[diff] [blame]19The configuration is done via environment variables STATSD_HOST and
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]20STATSD_PORT. They are interpreted by the statsd module directly and there is no
Michael Prokop526926a2013-10-24 16:16:57 +0200[diff] [blame]21such parameter in zuul.conf yet. Your init script will have to initialize both
Paul Belanger174a8272017-03-14 13:20:10 -0400[diff] [blame]22of them before executing Zuul.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]23
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 -0700[diff] [blame]32~~~~~~~
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]33
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]34The metrics are emitted by the Zuul :ref:`scheduler`:
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]35
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]36.. stat:: gerrit.event.<type>
37 :type: counter
James E. Blaireff5a9d2017-06-20 00:00:37 -0700[diff] [blame]38
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]39 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 +0200[diff] [blame]42
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]43 Refer to your Gerrit installation documentation for a complete
44 list of Gerrit event types.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]45
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]46.. stat:: zuul.pipeline
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]47
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]48 Holds metrics specific to jobs. This hierarchy includes:
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]49
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]50 .. stat:: <pipeline name>
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]51
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]52 A set of metrics for each pipeline named as defined in the Zuul
53 config.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]54
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]55 .. stat:: all_jobs
56 :type: counter
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]57
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]58 Number of jobs triggered by the pipeline.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]59
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]60 .. stat:: current_changes
61 :type: gauge
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]62
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]63 The number of items currently being processed by this
64 pipeline.
Antoine Mussoa8eea7d2013-10-05 16:08:00 +0200[diff] [blame]65
James E. Blair91c9dde2017-08-04 11:10:24 -0700[diff] [blame]66 .. 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