statsd-instrument 2.9.2 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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