1Net::Statsd(3) User Contributed Perl Documentation Net::Statsd(3)
2
6 Net::Statsd - Perl client for Etsy's statsd daemon
7
9 version 0.12
10
12 # Configure where to send events
13 # That's where your statsd daemon is listening.
14 $Net::Statsd::HOST = 'localhost'; # Default
15 $Net::Statsd::PORT = 8125; # Default
16 #
18 # Keep track of events as counters
19 #
20 Net::Statsd::increment('site.logins');
21 Net::Statsd::increment('database.connects');
22 #
24 # Log timing of events, ex. db queries
25 #
26 use Time::HiRes;
27 my $start_time = [ Time::HiRes::gettimeofday ];
28 # do the complex database query
30 # note: time value sent to timing should
31 # be in milliseconds.
32 Net::Statsd::timing(
33 'database.complexquery',
34 Time::HiRes::tv_interval($start_time) * 1000
35 );
36 #
38 # Log metric values
39 #
40 Net::Statsd::gauge('core.temperature' => 55);
41
43 This module implement a UDP client for the statsd statistics collector
44 daemon in use at Etsy.com.
45 You want to use this module to track statistics in your Perl
47 application, such as how many times a certain event occurs (user logins
48 in a web application, or database queries issued), or you want to time
49 and then graph how long certain events take, like database queries
50 execution time or time to download a certain file, etc...
51 If you're uncertain whether you'd want to use this module or statsd,
53 then you can read some background information here:
54 http://codeascraft.etsy.com/2011/02/15/measure-anything-measure-everything/
56 The github repository for statsd is:
58 http://github.com/etsy/statsd
60 By default the client will try to send statistic metrics to
62 "localhost:8125", but you can change the default hostname and port
63 with:
64 $Net::Statsd::HOST = 'your.statsd.hostname.net';
66 $Net::Statsd::PORT = 9999;
67 just after including the "Net::Statsd" module.
69
71 A note about sample rate: A sample rate of < 1 instructs this library
72 to send only the specified percentage of the samples to the server. As
73 such, the application code should call this module for every occurence
74 of each metric and allow this library to determine which specific
75 measurements to deliver, based on the sample_rate value. (e.g. a sample
76 rate of 0.5 would indicate that approximately only half of the metrics
77 given to this module would actually be sent to statsd).
78
80 "timing($name, $time, $sample_rate = 1)"
81 Log timing information. Time is assumed to be in milliseconds (ms).
82 Net::Statsd::timing('some.timer', 500);
84 "increment($counter, $sample_rate=1)"
86 "increment(\@counter, $sample_rate=1)"
87 Increments one or more stats counters
88 # +1 on 'some.int'
90 Net::Statsd::increment('some.int');
91 # 0.5 = 50% sampling
93 Net::Statsd::increment('some.int', 0.5);
94 To increment more than one counter at a time, you can pass an array
96 reference:
97 Net::Statsd::increment(['grue.dinners', 'room.lamps'], 1);
99 You can also use "inc()" instead of "increment()" to type less.
101 "decrement($counter, $sample_rate=1)"
103 Same as increment, but decrements. Yay.
104 Net::Statsd::decrement('some.int')
106 You can also use "dec()" instead of "decrement()" to type less.
108 "update_stats($stats, $delta=1, $sample_rate=1)"
110 Updates one or more stats counters by arbitrary amounts
111 Net::Statsd::update_stats('some.int', 10)
113 equivalent to:
115 Net::Statsd::update_stats('some.int', 10, 1)
117 A sampling rate less than 1 means only update the stats every x number
119 of times (0.1 = 10% of the times).
120 "gauge($name, $value)"
122 Log arbitrary values, as a temperature, or server load.
123 Net::Statsd::gauge('core.temperature', 55);
125 Statsd interprets gauge values with "+" or "-" sign as
127 increment/decrement. Therefore, to explicitly set a gauge to a
128 negative number it has to be set to zero first.
129 However, if either the zero or the actual negative value is lost in UDP
131 transport to statsd server because of e.g. network congestion or packet
132 loss, your gauge will become skewed.
133 To ensure network problems will not skew your data,
135 Net::Statsd::gauge() supports packing multiple values in single UDP
136 packet sent to statsd:
137 Net::Statsd::gauge(
139 'core.temperature' => 55,
140 'freezer.temperature' => -18
141 );
142 Make sure you don't supply too many values, or you might risk exceeding
144 the MTU of the network interface and cause the resulting UDP packet to
145 be dropped.
146 In general, a safe limit should be 512 bytes. Related to the example
148 above, "core.temperature" of 55 will be likely packed as a string:
149 core.temperature:55|g
151 which is 21 characters, plus a newline used as delimiter (22). Using
153 this example, you can pack at least 20 distinct gauge values without
154 problems. That will result in a UDP message of 440 bytes (22 times 20),
155 which is well below the safe threshold of 512.
156 In reality, if the communication happens on a local interface, or over
158 a 10G link, you are allowed much more than that.
159 "send(\%data, $sample_rate = 1)"
161 Squirt the metrics over UDP.
162 Net::Statsd::send({ 'some.int' => 1 });
164 "_sample_data(\%data, $sample_rate = 1)"
166 This method is used internally, it's not part of the public interface.
167 Takes care of transforming a hash of metrics data into a sampled hash
169 of metrics data, according to the given $sample_rate.
170 If "$sample_rate == 1", then sampled data is exactly the incoming data.
172 If "$sample_rate = 0.2", then every metric value will be marked with
174 the given sample rate, so the Statsd server will automatically scale
175 it. For example, with a sample rate of 0.2, the metric values will be
176 multiplied by 5.
177
179 Cosimo Streppone <cosimo@cpan.org>
180
182 This software is copyright (c) 2016 by Cosimo Streppone.
183 This is free software; you can redistribute it and/or modify it under
185 the same terms as the Perl 5 programming language system itself.
186perl v5.36.0 2023-01-20 Net::Statsd(3)