statsd-instrument 2.9.2 → 3.0.2

Sign up to get free protection for your applications and to get access to all the features.
Files changed (68) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/ci.yml +16 -23
  3. data/.rubocop.yml +3 -13
  4. data/CHANGELOG.md +33 -0
  5. data/Gemfile +8 -0
  6. data/README.md +3 -3
  7. data/Rakefile +1 -1
  8. data/benchmark/send-metrics-to-dev-null-log +5 -2
  9. data/benchmark/send-metrics-to-local-udp-receiver +8 -6
  10. data/bin/rake +29 -0
  11. data/bin/rubocop +29 -0
  12. data/lib/statsd/instrument.rb +80 -144
  13. data/lib/statsd/instrument/assertions.rb +200 -208
  14. data/lib/statsd/instrument/capture_sink.rb +23 -19
  15. data/lib/statsd/instrument/client.rb +414 -320
  16. data/lib/statsd/instrument/datagram.rb +69 -65
  17. data/lib/statsd/instrument/datagram_builder.rb +81 -77
  18. data/lib/statsd/instrument/dogstatsd_datagram.rb +76 -72
  19. data/lib/statsd/instrument/dogstatsd_datagram_builder.rb +68 -64
  20. data/lib/statsd/instrument/environment.rb +79 -98
  21. data/lib/statsd/instrument/expectation.rb +96 -96
  22. data/lib/statsd/instrument/helpers.rb +10 -35
  23. data/lib/statsd/instrument/log_sink.rb +20 -16
  24. data/lib/statsd/instrument/matchers.rb +86 -71
  25. data/lib/statsd/instrument/null_sink.rb +12 -8
  26. data/lib/statsd/instrument/railtie.rb +11 -11
  27. data/lib/statsd/instrument/statsd_datagram_builder.rb +12 -8
  28. data/lib/statsd/instrument/strict.rb +12 -123
  29. data/lib/statsd/instrument/udp_sink.rb +50 -46
  30. data/lib/statsd/instrument/version.rb +1 -1
  31. data/statsd-instrument.gemspec +2 -8
  32. data/test/assertions_test.rb +46 -12
  33. data/test/capture_sink_test.rb +8 -8
  34. data/test/client_test.rb +62 -51
  35. data/test/datagram_builder_test.rb +29 -29
  36. data/test/datagram_test.rb +1 -1
  37. data/test/dogstatsd_datagram_builder_test.rb +28 -28
  38. data/test/environment_test.rb +10 -46
  39. data/test/helpers/rubocop_helper.rb +11 -8
  40. data/test/helpers_test.rb +5 -5
  41. data/test/integration_test.rb +10 -25
  42. data/test/log_sink_test.rb +2 -2
  43. data/test/matchers_test.rb +36 -36
  44. data/test/null_sink_test.rb +2 -2
  45. data/test/rubocop/metric_return_value_test.rb +3 -3
  46. data/test/rubocop/metric_value_keyword_argument_test.rb +1 -1
  47. data/test/rubocop/positional_arguments_test.rb +10 -10
  48. data/test/statsd_instrumentation_test.rb +97 -122
  49. data/test/statsd_test.rb +50 -75
  50. data/test/test_helper.rb +7 -5
  51. data/test/udp_sink_test.rb +8 -8
  52. metadata +7 -125
  53. data/.rubocop-https---shopify-github-io-ruby-style-guide-rubocop-yml +0 -1027
  54. data/benchmark/datagram-client +0 -40
  55. data/lib/statsd/instrument/backend.rb +0 -18
  56. data/lib/statsd/instrument/backends/capture_backend.rb +0 -32
  57. data/lib/statsd/instrument/backends/logger_backend.rb +0 -20
  58. data/lib/statsd/instrument/backends/null_backend.rb +0 -9
  59. data/lib/statsd/instrument/backends/udp_backend.rb +0 -152
  60. data/lib/statsd/instrument/legacy_client.rb +0 -301
  61. data/lib/statsd/instrument/metric.rb +0 -155
  62. data/test/assertions_on_legacy_client_test.rb +0 -344
  63. data/test/capture_backend_test.rb +0 -26
  64. data/test/compatibility/dogstatsd_datagram_compatibility_test.rb +0 -161
  65. data/test/deprecations_test.rb +0 -139
  66. data/test/logger_backend_test.rb +0 -22
  67. data/test/metric_test.rb +0 -47
  68. data/test/udp_backend_test.rb +0 -228
@@ -1,348 +1,442 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require 'statsd/instrument/datagram'
4
- require 'statsd/instrument/dogstatsd_datagram'
5
- require 'statsd/instrument/datagram_builder'
6
- require 'statsd/instrument/statsd_datagram_builder'
7
- require 'statsd/instrument/dogstatsd_datagram_builder'
8
- require 'statsd/instrument/null_sink'
9
- require 'statsd/instrument/udp_sink'
10
- require 'statsd/instrument/capture_sink'
11
- require 'statsd/instrument/log_sink'
12
-
13
- # The Client is the main interface for using StatsD.
14
- #
15
- # @note This new Client implementation is intended to become the new default in the
16
- # next major release of this library. While this class may already be functional,
17
- # we provide no guarantees about the API and the behavior may change.
18
- class StatsD::Instrument::Client
19
- class << self
20
- def from_env(
21
- env = StatsD::Instrument::Environment.current,
22
- prefix: env.statsd_prefix,
23
- default_sample_rate: env.statsd_sample_rate,
24
- default_tags: env.statsd_default_tags,
25
- implementation: env.statsd_implementation,
26
- sink: env.default_sink_for_environment,
27
- datagram_builder_class: datagram_builder_class_for_implementation(implementation)
28
- )
29
- new(
30
- prefix: prefix,
31
- default_sample_rate: default_sample_rate,
32
- default_tags: default_tags,
33
- implementation: implementation,
34
- sink: sink,
35
- datagram_builder_class: datagram_builder_class,
36
- )
37
- end
38
-
39
- # @private
40
- def datagram_builder_class_for_implementation(implementation)
41
- case implementation.to_s
42
- when 'statsd'
43
- StatsD::Instrument::StatsDDatagramBuilder
44
- when 'datadog', 'dogstatsd'
45
- StatsD::Instrument::DogStatsDDatagramBuilder
46
- else
47
- raise NotImplementedError, "No implementation for #{statsd_implementation}"
3
+ module StatsD
4
+ module Instrument
5
+ # The Client is the main interface for using StatsD. It defines the metric
6
+ # methods that you would normally call from your application.
7
+ #
8
+ # The client set to {StatsD.singleton_client} will handle all metric calls made
9
+ # against the StatsD singleton, e.g. `StatsD.increment`.
10
+ #
11
+ # We recommend that the configuration of the StatsD setup is provided through
12
+ # environment variables
13
+ #
14
+ # You are encouraged to instantiate multiple clients, and instantiate variants
15
+ # of an existing clients using {#clone_with_options}. We recommend instantiating
16
+ # a separate client for every logical component of your application using
17
+ # `clone_with_options`, and setting a different metric `prefix`.
18
+ #
19
+ # @see StatsD.singleton_client
20
+ # @see #clone_with_options
21
+ class Client
22
+ class << self
23
+ # Instantiates a StatsD::Instrument::Client using configuration values provided in
24
+ # environment variables.
25
+ #
26
+ # @see StatsD::Instrument::Environment
27
+ def from_env(
28
+ env = StatsD::Instrument::Environment.current,
29
+ prefix: env.statsd_prefix,
30
+ default_sample_rate: env.statsd_sample_rate,
31
+ default_tags: env.statsd_default_tags,
32
+ implementation: env.statsd_implementation,
33
+ sink: env.default_sink_for_environment,
34
+ datagram_builder_class: datagram_builder_class_for_implementation(implementation)
35
+ )
36
+ new(
37
+ prefix: prefix,
38
+ default_sample_rate: default_sample_rate,
39
+ default_tags: default_tags,
40
+ implementation: implementation,
41
+ sink: sink,
42
+ datagram_builder_class: datagram_builder_class,
43
+ )
44
+ end
45
+
46
+ # Finds the right DatagramBuilder class for a given implementation.
47
+ # @private
48
+ # @param [Symbol, String] implementation The name of the implementation, e.g.
49
+ # `"statsd"` or `:datadog`.
50
+ # @return [Class] The subclass of {StatsD::Instrument::DatagramBuilder}
51
+ # builder to use to generate UDP datagrams for the given implementation.
52
+ # @raise `NotImplementedError` if the implementation is not recognized or
53
+ # supported.
54
+ def datagram_builder_class_for_implementation(implementation)
55
+ case implementation.to_s
56
+ when 'statsd'
57
+ StatsD::Instrument::StatsDDatagramBuilder
58
+ when 'datadog', 'dogstatsd'
59
+ StatsD::Instrument::DogStatsDDatagramBuilder
60
+ else
61
+ raise NotImplementedError, "Implementation named #{implementation} could not be found"
62
+ end
63
+ end
48
64
  end
49
- end
50
- end
51
-
52
- attr_reader :sink, :datagram_builder_class, :prefix, :default_tags, :default_sample_rate
53
65
 
54
- def initialize(
55
- prefix: nil,
56
- default_sample_rate: 1.0,
57
- default_tags: nil,
58
- implementation: 'datadog',
59
- sink: StatsD::Instrument::NullSink.new,
60
- datagram_builder_class: self.class.datagram_builder_class_for_implementation(implementation)
61
- )
62
- @sink = sink
63
- @datagram_builder_class = datagram_builder_class
64
-
65
- @prefix = prefix
66
- @default_tags = default_tags
67
- @default_sample_rate = default_sample_rate
66
+ # The class to use to build StatsD datagrams. To build the actual datagrams,
67
+ # the class will be instantiated, potentially multiple times, by the client.
68
+ #
69
+ # @return [Class] A subclass of {StatsD::Instrument::DatagramBuilder}
70
+ # @see .datagram_builder_class_for_implementation
71
+ attr_reader :datagram_builder_class
72
+
73
+ # The sink to send UDP datagrams to.
74
+ #
75
+ # This can be set to any object that responds to the following methods:
76
+ #
77
+ # - `sample?` which should return true if the metric should be sampled, i.e.
78
+ # actually sent to the sink.
79
+ # - `#<<` which takes a UDP datagram as string to emit the datagram. This
80
+ # method will only be called if `sample?` returned `true`.
81
+ #
82
+ # Generally, you should use an instance of one of the following classes that
83
+ # ship with this library:
84
+ #
85
+ # - {StatsD::Instrument::UDPSink} A sink that will actually emit the provided
86
+ # datagrams over UDP.
87
+ # - {StatsD::Instrument::NullSink} A sink that will simply swallow every
88
+ # datagram. This sink is for use when testing your application.
89
+ # - {StatsD::Instrument::LogSink} A sink that log all provided datagrams to
90
+ # a Logger, normally {StatsD.logger}.
91
+ #
92
+ # @return [#sample?, #<<]
93
+ attr_reader :sink
94
+
95
+ # The prefix to prepend to the metric names that are emitted through this
96
+ # client, using a dot (`.`) as namespace separator. E.g. when the prefix is
97
+ # set to `foo`, and you emit a metric named `bar`, the metric name will be
98
+ # `foo.bar`.
99
+ #
100
+ # Generally all the metrics you emit to the same StatsD server will share a
101
+ # single, global namespace. If you are emitting metrics from multiple
102
+ # applications, using a prefix is recommended to prevent metric name
103
+ # collisions.
104
+ #
105
+ # You can also leave this value to be `nil` if you don't want to prefix your
106
+ # metric names.
107
+ #
108
+ # @return [String, nil]
109
+ #
110
+ # @note The `prefix` can be overridden by any metric call by setting the
111
+ # `no_prefix` keyword argument to `true`. We recommend against doing this,
112
+ # but this behavior is retained for backwards compatibility.
113
+ # Rather, when you feel the need to do this, we recommend instantiating
114
+ # a new client without prefix (using {#clone_with_options}), and using it
115
+ # to emit the metric.
116
+ attr_reader :prefix
117
+
118
+ # The tags to apply to all the metrics emitted through this client.
119
+ #
120
+ # The tags can be supplied in normal form: an array of strings. You can also
121
+ # provide a hash, which will be turned into normal form by concatanting the
122
+ # key and the value using a colon. To not use any default tags, set to `nil`.
123
+ # Note that other components of your StatsD metric pipeline may also add tags
124
+ # to metrics. E.g. the DataDog agent may add add tags like `hostname`.
125
+ #
126
+ # We generally recommend to not use default tags, or use them sparingly.
127
+ # Adding tags to every metric easily introduces carninality explosions, which
128
+ # will make metrics less precise due to the lossy nature of aggregation. It
129
+ # also makes your infrastructure more expsnive to run, and the user interface
130
+ # of your metric explorer less responsive.
131
+ #
132
+ # @return [Array<String>, Hash, nil]
133
+ attr_reader :default_tags
134
+
135
+ # The default sample rate to use for metrics that are emitted without a
136
+ # sample rate set. This should be a value between 0 (never emit a metric) and
137
+ # 1.0 (always emit). If it is not set, the default value 1.0 is used.
138
+ #
139
+ # We generally recommend setting sample rates on individual metrics based
140
+ # on their frequency, rather than changing the default sample rate.
141
+ #
142
+ # @return [Float] (default: 1.0) A value between 0.0 and 1.0.
143
+ attr_reader :default_sample_rate
144
+
145
+ # Instantiates a new client.
146
+ # @see .from_env to instantiate a client using environment variables.
147
+ def initialize(
148
+ prefix: nil,
149
+ default_sample_rate: 1.0,
150
+ default_tags: nil,
151
+ implementation: 'datadog',
152
+ sink: StatsD::Instrument::NullSink.new,
153
+ datagram_builder_class: self.class.datagram_builder_class_for_implementation(implementation)
154
+ )
155
+ @sink = sink
156
+ @datagram_builder_class = datagram_builder_class
68
157
 
69
- @datagram_builder = { false => nil, true => nil }
70
- end
158
+ @prefix = prefix
159
+ @default_tags = default_tags
160
+ @default_sample_rate = default_sample_rate
71
161
 
72
- # @!group Metric Methods
73
-
74
- # Emits a counter metric.
75
- #
76
- # You should use a counter metric to count the frequency of something happening. As a
77
- # result, the value should generally be set to 1 (the default), unless you reporting
78
- # about a batch of activity. E.g. `increment('messages.processed', messages.size)`
79
- # For values that are not frequencies, you should use another metric type, e.g.
80
- # {#histogram} or {#distribution}.
81
- #
82
- # @param name [String] The name of the metric.
83
- #
84
- # - We recommend using `snake_case.metric_names` as naming scheme.
85
- # - A `.` should be used for namespacing, e.g. `foo.bar.baz`
86
- # - A metric name should not include the following characters: `|`, `@`, and `:`.
87
- # The library will convert these characters to `_`.
88
- #
89
- # @param value [Integer] (default: 1) The value to increment the counter by.
90
- #
91
- # You should not compensate for the sample rate using the counter increment. E.g., if
92
- # your sample rate is set to `0.01`, you should not use 100 as increment to compensate
93
- # for it. The sample rate is part of the packet that is being sent to the server, and
94
- # the server should know how to compensate for it.
95
- #
96
- # @param [Float] sample_rate (default: `#default_sample_rate`) The rate at which to sample
97
- # this metric call. This value should be between 0 and 1. This value can be used to reduce
98
- # the amount of network I/O (and CPU cycles) is being used for very frequent metrics.
99
- #
100
- # - A value of `0.1` means that only 1 out of 10 calls will be emitted; the other 9 will
101
- # be short-circuited.
102
- # - When set to `1`, every metric will be emitted.
103
- # - If this parameter is not set, the default sample rate for this client will be used.
104
- #
105
- # @param [Hash<Symbol, String>, Array<String>] tags (default: nil)
106
- # @return [void]
107
- def increment(name, value = 1, sample_rate: nil, tags: nil, no_prefix: false)
108
- sample_rate ||= @default_sample_rate
109
- return StatsD::Instrument::VOID unless sample?(sample_rate)
110
- emit(datagram_builder(no_prefix: no_prefix).c(name, value, sample_rate, tags))
111
- end
162
+ @datagram_builder = { false => nil, true => nil }
163
+ end
112
164
 
113
- # Emits a timing metric.
114
- #
115
- # @param name (see #increment)
116
- # @param [Numeric] value The duration to record, in milliseconds.
117
- # @param sample_rate (see #increment)
118
- # @param tags (see #increment)
119
- # @return [void]
120
- def measure(name, value = nil, sample_rate: nil, tags: nil, no_prefix: false, &block)
121
- if block_given?
122
- return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :ms, no_prefix: no_prefix, &block)
123
- end
165
+ # @!group Metric Methods
166
+
167
+ # Emits a counter metric.
168
+ #
169
+ # You should use a counter metric to count the frequency of something happening. As a
170
+ # result, the value should generally be set to 1 (the default), unless you reporting
171
+ # about a batch of activity. E.g. `increment('messages.processed', messages.size)`
172
+ # For values that are not frequencies, you should use another metric type, e.g.
173
+ # {#histogram} or {#distribution}.
174
+ #
175
+ # @param name [String] The name of the metric.
176
+ #
177
+ # - We recommend using `snake_case.metric_names` as naming scheme.
178
+ # - A `.` should be used for namespacing, e.g. `foo.bar.baz`
179
+ # - A metric name should not include the following characters: `|`, `@`, and `:`.
180
+ # The library will convert these characters to `_`.
181
+ #
182
+ # @param value [Integer] (default: 1) The value to increment the counter by.
183
+ #
184
+ # You should not compensate for the sample rate using the counter increment. E.g., if
185
+ # your sample rate is set to `0.01`, you should not use 100 as increment to compensate
186
+ # for it. The sample rate is part of the packet that is being sent to the server, and
187
+ # the server should know how to compensate for it.
188
+ #
189
+ # @param [Float] sample_rate (default: `#default_sample_rate`) The rate at which to sample
190
+ # this metric call. This value should be between 0 and 1. This value can be used to reduce
191
+ # the amount of network I/O (and CPU cycles) is being used for very frequent metrics.
192
+ #
193
+ # - A value of `0.1` means that only 1 out of 10 calls will be emitted; the other 9 will
194
+ # be short-circuited.
195
+ # - When set to `1`, every metric will be emitted.
196
+ # - If this parameter is not set, the default sample rate for this client will be used.
197
+ #
198
+ # @param [Hash<Symbol, String>, Array<String>] tags (default: nil)
199
+ # @return [void]
200
+ def increment(name, value = 1, sample_rate: nil, tags: nil, no_prefix: false)
201
+ sample_rate ||= @default_sample_rate
202
+ return StatsD::Instrument::VOID unless sample?(sample_rate)
203
+ emit(datagram_builder(no_prefix: no_prefix).c(name, value, sample_rate, tags))
204
+ end
124
205
 
125
- sample_rate ||= @default_sample_rate
126
- return StatsD::Instrument::VOID unless sample?(sample_rate)
127
- emit(datagram_builder(no_prefix: no_prefix).ms(name, value, sample_rate, tags))
128
- end
206
+ # Emits a timing metric.
207
+ #
208
+ # @param name (see #increment)
209
+ # @param [Numeric] value The duration to record, in milliseconds.
210
+ # @param sample_rate (see #increment)
211
+ # @param tags (see #increment)
212
+ # @return [void]
213
+ def measure(name, value = nil, sample_rate: nil, tags: nil, no_prefix: false, &block)
214
+ if block_given?
215
+ return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :ms, no_prefix: no_prefix, &block)
216
+ end
217
+
218
+ sample_rate ||= @default_sample_rate
219
+ return StatsD::Instrument::VOID unless sample?(sample_rate)
220
+ emit(datagram_builder(no_prefix: no_prefix).ms(name, value, sample_rate, tags))
221
+ end
129
222
 
130
- # Emits a gauge metric.
131
- #
132
- # You should use a gauge if you are reporting the current value of
133
- # something that can only have one value at the time. E.g., the
134
- # speed of your car. A newly reported value will replace the previously
135
- # reported value.
136
- #
137
- #
138
- # @param name (see #increment)
139
- # @param [Numeric] value The gauged value.
140
- # @param sample_rate (see #increment)
141
- # @param tags (see #increment)
142
- # @return [void]
143
- def gauge(name, value, sample_rate: nil, tags: nil, no_prefix: false)
144
- sample_rate ||= @default_sample_rate
145
- return StatsD::Instrument::VOID unless sample?(sample_rate)
146
- emit(datagram_builder(no_prefix: no_prefix).g(name, value, sample_rate, tags))
147
- end
223
+ # Emits a gauge metric.
224
+ #
225
+ # You should use a gauge if you are reporting the current value of
226
+ # something that can only have one value at the time. E.g., the
227
+ # speed of your car. A newly reported value will replace the previously
228
+ # reported value.
229
+ #
230
+ #
231
+ # @param name (see #increment)
232
+ # @param [Numeric] value The gauged value.
233
+ # @param sample_rate (see #increment)
234
+ # @param tags (see #increment)
235
+ # @return [void]
236
+ def gauge(name, value, sample_rate: nil, tags: nil, no_prefix: false)
237
+ sample_rate ||= @default_sample_rate
238
+ return StatsD::Instrument::VOID unless sample?(sample_rate)
239
+ emit(datagram_builder(no_prefix: no_prefix).g(name, value, sample_rate, tags))
240
+ end
148
241
 
149
- # Emits a set metric, which counts distinct values.
150
- #
151
- # @param name (see #increment)
152
- # @param [Numeric, String] value The value to count for distinct occurrences.
153
- # @param sample_rate (see #increment)
154
- # @param tags (see #increment)
155
- # @return [void]
156
- def set(name, value, sample_rate: nil, tags: nil, no_prefix: false)
157
- sample_rate ||= @default_sample_rate
158
- return StatsD::Instrument::VOID unless sample?(sample_rate)
159
- emit(datagram_builder(no_prefix: no_prefix).s(name, value, sample_rate, tags))
160
- end
242
+ # Emits a set metric, which counts distinct values.
243
+ #
244
+ # @param name (see #increment)
245
+ # @param [Numeric, String] value The value to count for distinct occurrences.
246
+ # @param sample_rate (see #increment)
247
+ # @param tags (see #increment)
248
+ # @return [void]
249
+ def set(name, value, sample_rate: nil, tags: nil, no_prefix: false)
250
+ sample_rate ||= @default_sample_rate
251
+ return StatsD::Instrument::VOID unless sample?(sample_rate)
252
+ emit(datagram_builder(no_prefix: no_prefix).s(name, value, sample_rate, tags))
253
+ end
161
254
 
162
- # Emits a distribution metric, which builds a histogram of the reported
163
- # values.
164
- #
165
- # @note The distribution metric type is not available on all implementations.
166
- # A `NotImplementedError` will be raised if you call this method, but
167
- # the active implementation does not support it.
168
- #
169
- # @param name (see #increment)
170
- # @param [Numeric] value The value to include in the distribution histogram.
171
- # @param sample_rate (see #increment)
172
- # @param tags (see #increment)
173
- # @return [void]
174
- def distribution(name, value = nil, sample_rate: nil, tags: nil, no_prefix: false, &block)
175
- if block_given?
176
- return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :d, no_prefix: no_prefix, &block)
177
- end
255
+ # Emits a distribution metric, which builds a histogram of the reported
256
+ # values.
257
+ #
258
+ # @note The distribution metric type is not available on all implementations.
259
+ # A `NotImplementedError` will be raised if you call this method, but
260
+ # the active implementation does not support it.
261
+ #
262
+ # @param name (see #increment)
263
+ # @param [Numeric] value The value to include in the distribution histogram.
264
+ # @param sample_rate (see #increment)
265
+ # @param tags (see #increment)
266
+ # @return [void]
267
+ def distribution(name, value = nil, sample_rate: nil, tags: nil, no_prefix: false, &block)
268
+ if block_given?
269
+ return latency(name, sample_rate: sample_rate, tags: tags, metric_type: :d, no_prefix: no_prefix, &block)
270
+ end
271
+
272
+ sample_rate ||= @default_sample_rate
273
+ return StatsD::Instrument::VOID unless sample?(sample_rate)
274
+ emit(datagram_builder(no_prefix: no_prefix).d(name, value, sample_rate, tags))
275
+ end
178
276
 
179
- sample_rate ||= @default_sample_rate
180
- return StatsD::Instrument::VOID unless sample?(sample_rate)
181
- emit(datagram_builder(no_prefix: no_prefix).d(name, value, sample_rate, tags))
182
- end
277
+ # Emits a histogram metric, which builds a histogram of the reported values.
278
+ #
279
+ # @note The histogram metric type is not available on all implementations.
280
+ # A `NotImplementedError` will be raised if you call this method, but
281
+ # the active implementation does not support it.
282
+ #
283
+ # @param name (see #increment)
284
+ # @param [Numeric] value The value to include in the histogram.
285
+ # @param sample_rate (see #increment)
286
+ # @param tags (see #increment)
287
+ # @return [void]
288
+ def histogram(name, value, sample_rate: nil, tags: nil, no_prefix: false)
289
+ sample_rate ||= @default_sample_rate
290
+ return StatsD::Instrument::VOID unless sample?(sample_rate)
291
+ emit(datagram_builder(no_prefix: no_prefix).h(name, value, sample_rate, tags))
292
+ end
183
293
 
184
- # Emits a histogram metric, which builds a histogram of the reported values.
185
- #
186
- # @note The histogram metric type is not available on all implementations.
187
- # A `NotImplementedError` will be raised if you call this method, but
188
- # the active implementation does not support it.
189
- #
190
- # @param name (see #increment)
191
- # @param [Numeric] value The value to include in the histogram.
192
- # @param sample_rate (see #increment)
193
- # @param tags (see #increment)
194
- # @return [void]
195
- def histogram(name, value, sample_rate: nil, tags: nil, no_prefix: false)
196
- sample_rate ||= @default_sample_rate
197
- return StatsD::Instrument::VOID unless sample?(sample_rate)
198
- emit(datagram_builder(no_prefix: no_prefix).h(name, value, sample_rate, tags))
199
- end
294
+ # @!endgroup
295
+
296
+ # Measures the latency of the given block in milliseconds, and emits it as a metric.
297
+ #
298
+ # @param name (see #increment)
299
+ # @param sample_rate (see #increment)
300
+ # @param tags (see #increment)
301
+ # @param [Symbol] metric_type The metric type to use. If not specified, we will
302
+ # use the preferred metric type of the implementation. The default is `:ms`.
303
+ # Generally, you should not have to set this.
304
+ # @yield The latency (execution time) of the block
305
+ # @return The return value of the provided block will be passed through.
306
+ def latency(name, sample_rate: nil, tags: nil, metric_type: nil, no_prefix: false)
307
+ start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
308
+ begin
309
+ yield
310
+ ensure
311
+ stop = Process.clock_gettime(Process::CLOCK_MONOTONIC)
312
+
313
+ sample_rate ||= @default_sample_rate
314
+ if sample?(sample_rate)
315
+ metric_type ||= datagram_builder(no_prefix: no_prefix).latency_metric_type
316
+ latency_in_ms = 1000.0 * (stop - start)
317
+ emit(datagram_builder(no_prefix: no_prefix).send(metric_type, name, latency_in_ms, sample_rate, tags))
318
+ end
319
+ end
320
+ end
200
321
 
201
- # @!endgroup
202
-
203
- # Measures the latency of the given block in milliseconds, and emits it as a metric.
204
- #
205
- # @param name (see #increment)
206
- # @param sample_rate (see #increment)
207
- # @param tags (see #increment)
208
- # @param [Symbol] metric_type The metric type to use. If not specified, we will
209
- # use the preferred metric type of the implementation. The default is `:ms`.
210
- # Generally, you should not have to set this.
211
- # @yield The latency (execution time) of the block
212
- # @return The return value of the provided block will be passed through.
213
- def latency(name, sample_rate: nil, tags: nil, metric_type: nil, no_prefix: false)
214
- start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
215
- begin
216
- yield
217
- ensure
218
- stop = Process.clock_gettime(Process::CLOCK_MONOTONIC)
219
-
220
- sample_rate ||= @default_sample_rate
221
- if sample?(sample_rate)
222
- metric_type ||= datagram_builder(no_prefix: no_prefix).latency_metric_type
223
- latency_in_ms = 1000.0 * (stop - start)
224
- emit(datagram_builder(no_prefix: no_prefix).send(metric_type, name, latency_in_ms, sample_rate, tags))
322
+ # Emits a service check. Services Checks allow you to characterize the status
323
+ # of a service in order to monitor it within Datadog.
324
+ #
325
+ # @param name (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
326
+ # @param status (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
327
+ # @param timestamp (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
328
+ # @param hostname (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
329
+ # @param tags (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
330
+ # @param message (see StatsD::Instrument::DogStatsDDatagramBuilder#_sc)
331
+ # @return [void]
332
+ #
333
+ # @note Supported by the Datadog implementation only.
334
+ def service_check(name, status, timestamp: nil, hostname: nil, tags: nil, message: nil, no_prefix: false)
335
+ emit(datagram_builder(no_prefix: no_prefix)._sc(name, status,
336
+ timestamp: timestamp, hostname: hostname, tags: tags, message: message))
225
337
  end
226
- end
227
- end
228
338
 
229
- # Emits a service check.
230
- #
231
- # @param [String] title Event title.
232
- # @param [String] text Event description. Newlines are allowed.
233
- # @param [Time] timestamp The of the event. If not provided,
234
- # Datadog will interpret it as the current timestamp.
235
- # @param [String] hostname A hostname to associate with the event.
236
- # @param [String] aggregation_key An aggregation key to group events with the same key.
237
- # @param [String] priority Priority of the event. Either "normal" (default) or "low".
238
- # @param [String] source_type_name The source type of the event.
239
- # @param [String] alert_type Either "error", "warning", "info" (default) or "success".
240
- # @param [Array, Hash] tags Tags to associate with the event.
241
- # @return [void]
242
- #
243
- # @note Supported by the Datadog implementation only.
244
- def service_check(name, status, timestamp: nil, hostname: nil, tags: nil, message: nil, no_prefix: false)
245
- emit(datagram_builder(no_prefix: no_prefix)._sc(name, status,
246
- timestamp: timestamp, hostname: hostname, tags: tags, message: message))
247
- end
339
+ # Emits an event. An event represents any record of activity noteworthy for engineers.
340
+ #
341
+ # @param title (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
342
+ # @param text (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
343
+ # @param timestamp (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
344
+ # @param hostname (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
345
+ # @param aggregation_key (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
346
+ # @param priority (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
347
+ # @param source_type_name (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
348
+ # @param alert_type (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
349
+ # @param tags (see StatsD::Instrument::DogStatsDDatagramBuilder#_e)
350
+ # @return [void]
351
+ #
352
+ # @note Supported by the Datadog implementation only.
353
+ def event(title, text, timestamp: nil, hostname: nil, aggregation_key: nil, priority: nil,
354
+ source_type_name: nil, alert_type: nil, tags: nil, no_prefix: false)
355
+
356
+ emit(datagram_builder(no_prefix: no_prefix)._e(title, text, timestamp: timestamp,
357
+ hostname: hostname, tags: tags, aggregation_key: aggregation_key, priority: priority,
358
+ source_type_name: source_type_name, alert_type: alert_type))
359
+ end
248
360
 
249
- # Emits an event.
250
- #
251
- # @param [String] name Name of the service
252
- # @param [Symbol] status Either `:ok`, `:warning`, `:critical` or `:unknown`
253
- # @param [Time] timestamp The moment when the service was checked. If not provided,
254
- # Datadog will interpret it as the current timestamp.
255
- # @param [String] hostname A hostname to associate with the check.
256
- # @param [Array, Hash] tags Tags to associate with the check.
257
- # @param [String] message A message describing the current state of the service check.
258
- # @return [void]
259
- #
260
- # @note Supported by the Datadog implementation only.
261
- def event(title, text, timestamp: nil, hostname: nil, aggregation_key: nil, priority: nil,
262
- source_type_name: nil, alert_type: nil, tags: nil, no_prefix: false)
263
-
264
- emit(datagram_builder(no_prefix: no_prefix)._e(title, text, timestamp: timestamp,
265
- hostname: hostname, tags: tags, aggregation_key: aggregation_key, priority: priority,
266
- source_type_name: source_type_name, alert_type: alert_type))
267
- end
361
+ # Instantiates a new StatsD client that uses the settings of the current client,
362
+ # except for the provided overrides.
363
+ #
364
+ # @yield [client] A new client will be constructed with the altered settings, and
365
+ # yielded to the block. The original client will not be affected. The new client
366
+ # will be disposed after the block returns
367
+ # @return The return value of the block will be passed on as return value.
368
+ def with_options(
369
+ sink: nil,
370
+ prefix: nil,
371
+ default_sample_rate: nil,
372
+ default_tags: nil,
373
+ datagram_builder_class: nil
374
+ )
375
+ client = clone_with_options(sink: sink, prefix: prefix,
376
+ default_sample_rate: default_sample_rate, default_tags: default_tags,
377
+ datagram_builder_class: datagram_builder_class)
268
378
 
269
- # Instantiates a new StatsD client that uses the settings of the current client,
270
- # except for the provided overrides.
271
- #
272
- # @yield [client] A new client will be constructed with the altered settings, and
273
- # yielded to the block. The original client will not be affected. The new client
274
- # will be disposed after the block returns
275
- # @return The return value of the block will be passed on as return value.
276
- def with_options(
277
- sink: nil,
278
- prefix: nil,
279
- default_sample_rate: nil,
280
- default_tags: nil,
281
- datagram_builder_class: nil
282
- )
283
- client = clone_with_options(sink: sink, prefix: prefix,
284
- default_sample_rate: default_sample_rate, default_tags: default_tags,
285
- datagram_builder_class: datagram_builder_class)
286
-
287
- yield(client)
288
- end
379
+ yield(client)
380
+ end
289
381
 
290
- def clone_with_options(
291
- sink: nil,
292
- prefix: nil,
293
- default_sample_rate: nil,
294
- default_tags: nil,
295
- datagram_builder_class: nil
296
- )
297
- self.class.new(
298
- sink: sink || @sink,
299
- prefix: prefix || @prefix,
300
- default_sample_rate: default_sample_rate || @default_sample_rate,
301
- default_tags: default_tags || @default_tags,
302
- datagram_builder_class: datagram_builder_class || @datagram_builder_class,
303
- )
304
- end
382
+ def clone_with_options(
383
+ sink: nil,
384
+ prefix: nil,
385
+ default_sample_rate: nil,
386
+ default_tags: nil,
387
+ datagram_builder_class: nil
388
+ )
389
+ self.class.new(
390
+ sink: sink || @sink,
391
+ prefix: prefix || @prefix,
392
+ default_sample_rate: default_sample_rate || @default_sample_rate,
393
+ default_tags: default_tags || @default_tags,
394
+ datagram_builder_class: datagram_builder_class || @datagram_builder_class,
395
+ )
396
+ end
305
397
 
306
- def capture_sink
307
- StatsD::Instrument::CaptureSink.new(
308
- parent: @sink,
309
- datagram_class: datagram_builder_class.datagram_class,
310
- )
311
- end
398
+ def capture_sink
399
+ StatsD::Instrument::CaptureSink.new(
400
+ parent: @sink,
401
+ datagram_class: datagram_builder_class.datagram_class,
402
+ )
403
+ end
312
404
 
313
- def with_capture_sink(capture_sink)
314
- @sink = capture_sink
315
- yield
316
- ensure
317
- @sink = @sink.parent
318
- end
405
+ def with_capture_sink(capture_sink)
406
+ @sink = capture_sink
407
+ yield
408
+ ensure
409
+ @sink = @sink.parent
410
+ end
319
411
 
320
- # Captures metrics that were emitted during the provided block.
321
- #
322
- # @yield During the execution of the provided block, metrics will be captured.
323
- # @return [Array<StatsD::Instagram::Datagram>] The list of metrics that were
324
- # emitted during the block, in the same order in which they were emitted.
325
- def capture(&block)
326
- sink = capture_sink
327
- with_capture_sink(sink, &block)
328
- sink.datagrams
329
- end
412
+ # Captures metrics that were emitted during the provided block.
413
+ #
414
+ # @yield During the execution of the provided block, metrics will be captured.
415
+ # @return [Array<StatsD::Instagram::Datagram>] The list of metrics that were
416
+ # emitted during the block, in the same order in which they were emitted.
417
+ def capture(&block)
418
+ sink = capture_sink
419
+ with_capture_sink(sink, &block)
420
+ sink.datagrams
421
+ end
330
422
 
331
- protected
423
+ protected
332
424
 
333
- def datagram_builder(no_prefix:)
334
- @datagram_builder[no_prefix] ||= @datagram_builder_class.new(
335
- prefix: no_prefix ? nil : prefix,
336
- default_tags: default_tags,
337
- )
338
- end
425
+ def datagram_builder(no_prefix:)
426
+ @datagram_builder[no_prefix] ||= @datagram_builder_class.new(
427
+ prefix: no_prefix ? nil : prefix,
428
+ default_tags: default_tags,
429
+ )
430
+ end
339
431
 
340
- def sample?(sample_rate)
341
- @sink.sample?(sample_rate)
342
- end
432
+ def sample?(sample_rate)
433
+ @sink.sample?(sample_rate)
434
+ end
343
435
 
344
- def emit(datagram)
345
- @sink << datagram
346
- StatsD::Instrument::VOID
436
+ def emit(datagram)
437
+ @sink << datagram
438
+ StatsD::Instrument::VOID
439
+ end
440
+ end
347
441
  end
348
442
  end