1PMDASTATSD(1) General Commands Manual PMDASTATSD(1)
2
6 pmdastatsd - StatsD protocol performance metric domain agent (PMDA)
7
9 $PCP_PMDAS_DIR/statsd/pmdastatsd [-Z maximum udp packet size] [-P port]
10 [-v] [-g] [-o debug output filename] [-s] [-r parser type] [-a port]
11 [-z maximum of unprocessed packets]
12
14 StatsD is simple, text-based UDP protocol for receiving monitoring data
15 of applications in architecture client-server. pmdastatsd is an Per‐
16 formance Metrics Domain Agent that collects StatsD data, aggregates
17 them and makes them available to any Performance Co-Pilot client, which
18 is ideal for easily tracking stats in your application.
19 The statsd PMDA supports Counter, Gauge and Duration (with instances
21 for minimum, maximum, median, average, 90th percentile, 95th per‐
22 centile, 99th percentile, count and standard deviation) metric types,
23 offers multiple parsing options: Ragel or handwritten/custom parser,
24 offers multiple aggregating options for duration metric type: basic
25 histogram or HDR histogram, supports custom form of labels, logging,
26 exports multiple metrics about itself and may be configured either with
27 an ini file or command line options.
28
30 A brief description of the pmdastatsd command line options follows:
31 -Z, --max-udp=<value>
33 Maximum allowed packet size, any larger then this will be thrown
34 away. Default: 1472
35 -P, --port=<value>
37 Which port agent will listen to for incoming trafic. Default:
38 8125
39 -v, --verbose
41 Verbosity level. Prints info about agent execution into logfile.
42 Valid values are 0-2. 0 = Default value, shows config information,
43 read socket state, and first 100 dropped messages. 1 = Shows PMNS
44 and related information. 2 = Most detailed verbosity level, also
45 shows dropped messages above 100. All levels include those be‐
46 lows.
47 -o, --debug-output-filename=<value>
49 You can send USR1 signal that 'asks' agent to output basic infor‐
50 mation about all aggregated metric into a
51 $PCP_LOG_DIR/pmcd/statsd_{name} file. Default: 0
52 -s, --version
54 Flag controlling whether or not to log current agent version on
55 start. Default: 0
56 -p, --parser-type=<value>
58 Flag specifying which parser to use for incoming packets; Basic =
59 0, Ragel = 1. Ragel parser includes better logging when verbose =
60 2. Default: 0
61 -a, --duration-aggregation-type=<value>
63 Flag specifying which aggregation scheme to use for duration met‐
64 rics; basic histogram = 0, HDR histogram = 1. Default: 1
65 -z, -max-unprocessed-packets=<value>
67 Maximum size of packet queue that the agent will save in memory.
68 There are 2 queues: one for packets that are waiting to be parsed
69 and one for parsed packets before they are aggregated. Default:
70 2048
71 The agent also looks for a pmdastatsd.ini file in the $PCP_PM‐
73 DAS_DIR/statsd directory. There, the same options may be specified,
74 albeit with slightly different names as follows:
75 max_udp_packet_size=<value>
77 port=<value>
78 verbose=<value>
79 debug=<value>
80 debug_output_filename=<value>
81 version=<value>
82 parser_type=<value>
83 duration_aggregation_type=<value>
84 max_unprocessed_packets=<value>
85 Should an option be specified in both pmdastatsd.ini and command line,
87 then the latter takes precedence. Most of the time you will want to
88 configure the agent with an ini file, as the agent should never be exe‐
89 cuted directly.
90 Location of the log file. By default, a log file named statsd.log is
92 written in the current directory of pmcd(1) when pmdastatsd is started,
93 i.e. $PCP_LOG_DIR/pmcd. If the log file cannot be created or is not
94 writable, output is written to standard error instead.
95
97 If you want to install the pmdastatsd, do the following as root:
98 # cd $PCP_PMDAS_DIR/statsd
100 # ./Install
101 To uninstall, do the following as root:
103 # cd $PCP_PMDAS_DIR/statsd
105 # ./Remove
106 pmdastatsd is launched by pmcd(1) and should never be executed di‐
108 rectly. The Install and Remove scripts notify pmcd(1) when the agent
109 is installed or removed.
110
112 Once started, pmdastatsd will listen on specified port for any content
113 in a form of:
114 <metricname>:<value>|<type>
116 There may be multiple such messages in single datagram, split by a new‐
118 line character, so this:
119 <metricname>:<value>|<type>\n<metricname>:<value>|<type>
121 is valid as well. Constraints for each of the above variables are:
123 <metricname> = [a-z][a-zA-Z0-9_.]*
125 <value> = described further in each metric type subsection
126 <type> = One of the following: c , g or ms
127 If verbose logging is turned on, agent will log every message parsed
129 and related failures.
130 All recorded metrics will, if parsed and aggregated successfully, be
132 made available under statsd.* namespace.
133 1 Counter metric
135 Stores metrics as simple counters, adding any incoming values to al‐
136 ready existing ones.
137 <metricname>:<value>|c
139 Where value is positive number.
141 Example:
143 After aggregating following messages:
145 metric:20|c
147 metric:10|c
148 metric:3.3|c
149 Value available to PCP will be:
151 # pminfo --fetch statsd.metric
153 inst [0 or '/'] value 33.3
155 2 Gauge metric
157 Stores metrics as modifiable values, with an option to either set, in‐
158 crement or decrement values.
159 <metricname>:<value>|g
161 Where value can be in a form of:
163 '-{value}', when negative value is supplied agent will substract
165 value stored with the value passed
166 '+{value}', when positive value with a leading plus sign is sup‐
168 plied, the agent will add the passed value to the value stored
169 '{value}', when a value without any leading sign is supplied, the
171 agent will set the metric to the passed value.
172 Initial value for metric of gauge type is 0.
174 Example:
176 After aggregating following messages:
178 metric:20|g
180 metric:+10|g
181 metric:-3.3|g
182 Value available to PCP will be:
184 # pminfo --fetch statsd.metric
186 inst [0 or '/'] value 26.7
188 3 Duration metric
190 Aggregates values either via HDR histogram or simply stores all values
191 and then calculates instances from all values received.
192 <metricname>:<value>|ms
194 Where value is a positive number.
196 Example:
198 With larger message count, the values may vary based on selected dura‐
200 tion aggregation scheme.
201 After aggregating following messages:
203 metric:10|ms
205 metric:20|ms
206 Values available to PCP will be:
208 # pminfo --fetch statsd.metric
210 inst[0 or '/min'] value 10
212 inst[1 or '/max'] value 20
213 inst[2 or '/median'] value 10
214 inst[3 or '/average'] value 15
215 inst[4 or '/percentile90'] value 20
216 inst[5 or '/percentile95'] value 20
217 inst[6 or '/percentile99'] value 20
218 inst[7 or '/count'] value 2
219 inst[8 or '/std_deviation'] value 5
220 Note:
222 Once you send given metricname with specified type, the agent will no
224 longer aggregate any messages with same. metricname but different type
225 and will throw them away.
226 4 Labels
228 StatsD datagrams may also contain key:value pairs separated by commas
229 like so:
230 metric,tagX=X,tagW=W:5|c
232 OR
234 metric:5|ms|#tagX:X,tagW:W
236 Where tagX is a key, X is a value and tagW is a key, W is a value.
238 Both key and value of such a pair are [a-ZA-Z0-9_.]{1,}.
240 Both formats are interchangeable and you may combine them together.
242 When key is not unique, right most value takes precendence. This is
243 valid:
244 metric,tagX=1:5|c|#tagX:2
246 Pair with key tagX will have value of 2.
248 You may use these labels to map specific values to some PCP instances.
250 PCP labels are also assigned to these PCP instances. Pairs are ordered
251 by key in resulting instance name and label descriptor.
252 Single label:
254 metric,tagX=X:5|c
256 Such a payload would map to PCP as follows (non-related labels were om‐
258 mited):
259 # pminfo --fetch --labels statsd.metric
261 inst [0 or '/tagX=X'] value 5
263 inst [0 or '/tagX=X'] labels {'tagX':'X'}
264 As shown earlier you may also send payload with multiple labels. When
266 multiple labels are supplied they are split in instance name by '::'.
267 Example:
268 metric,tagX=X,tagW=W:5|c
270 This resolves to:
272 # pminfo --fetch --labels statsd.metric
274 inst [0 or '/tagX=X::tagW=W'] value 5
276 inst [0 or '/tagX=X::tagW=W'] labels {'tagX':'X','tagW':'W'}
277 Note:
279 Be mindful of the fact that duration metric type already maps to in‐
281 stances even without any labels. Sending labeled value to such a met‐
282 ric creates another 9 (as there are that many hardcoded) instances.
283 Example:
285 metric:200|ms
287 metric:100|ms
288 metric,target=cpu2:10|ms
289 metric,target=cpu2:100|ms
290 metric,target=cpu2:1000|ms
291 Creates 18 instances. Duration data type and label name compose in‐
293 stance name in following manner:
294 # pminfo --fetch --labels statsd.metric
296 ...
298 inst [10 or '/max::target=cpu0'] value 1000
299 inst [10 or '/max::target=cpu0'] labels {'target':'cpu0'}
300 ...
301 5 Hardcoded stats
303 Agent also exports metrics about itself:
304 statsd.pmda.received
306 Number of datagrams that the agent has received
307 statsd.pmda.parsed
309 Number of datagrams that were successfully parsed
310 statsd.pmda.dropped
312 Number of datagrams that were dropped
313 statsd.pmda.aggregated
315 Number of datagrams that were aggregated
316 statsd.pmda.metrics_tracked
318 This metric has 3 instances. counter - Number of tracked counter
319 metrics. gauge - Number of tracked gauge metrics. duration -
320 Number of tracked duration metrics. total - Number of tracked
321 metrics total.
322 statsd.pmda.time_spent_parsing
324 Total time in microseconds spent parsing metrics. Includes time
325 spent parsing a datagram and failing midway.
326 statsd.pmda.time_spent_aggregating
328 Total time in microseconds spent aggregating metrics. Includes
329 time spent aggregating a metric and failing midway.
330 statsd.pmda.settings.max_udp_packet_size
332 Maximum UDP packet size
333 statsd.pmda.settings.max_unprocessed_packets
335 Maximum size of unprocessed packets Q
336 statsd.pmda.settings.verbose
338 Verbosity flag
339 statsd.pmda.settings.debug_output_filename
341 Debug output filename
342 statsd.pmda.settings.port
344 Port that is listened to
345 statsd.pmda.settings.parser_type
347 Used parser type
348 statsd.pmda.settings.duration_aggregation_type
350 Used duration aggregation type
351 These names are blocklisted for user usage. No messages with these
353 names will processed. While not yet reserved, the whole statsd.pmda.*
354 namespace is not recommended to use for user metrics.
355
357 $PCP_PMCDCONF_PATH
358 command line options used to launch pmdastatsd
359 $PCP_PMDAS_DIR/statsd/Install
360 installation script for the pmdastatsd agent
361 $PCP_PMDAS_DIR/statsd/Remove
362 undo installation script for the pmdastatsd agent
363 $PCP_LOG_DIR/pmcd/statsd.log
364 default log file for error messages and other information
365 from pmdastatsd
366
368 Environment variables with the prefix PCP_ are used to parameterize the
369 file and directory names used by PCP. On each installation, the file
370 /etc/pcp.conf contains the local values for these variables. The
371 $PCP_CONF variable may be used to specify an alternative configuration
372 file, as described in pcp.conf(5).
373
375 PCPIntro(1), pmcd(1), pcp.conf(5) and pcp.env(5).
376Performance Co-Pilot PCP PMDASTATSD(1)