class StatsD::Instrument::Metric
The Metric
class represents a metric sample to be send by a backend.
@!attribute type
@return [Symbol] The metric type. Must be one of {StatsD::Instrument::Metric::TYPES}
@!attribute name
@return [String] The name of the metric. {StatsD#prefix} will automatically be applied to the metric in the constructor, unless the <tt>:no_prefix</tt> option is set or is overridden by the <tt>:prefix</tt> option. Note that <tt>:no_prefix</tt> has greater precedence than <tt>:prefix</tt>.
@!attribute value
@see #default_value @return [Numeric, String] The value to collect for the metric. Depending on the metric type, <tt>value</tt> can be a string, integer, or float.
@!attribute sample_rate
The sample rate to use for the metric. How the sample rate is handled differs per backend. The UDP backend will actually sample metric submissions based on the sample rate, while the logger backend will just include the sample rate in its output for debugging purposes. @see StatsD#default_sample_rate @return [Float] The sample rate to use for this metric. This should be a value between 0 and 1. If not set, it will use the default sample rate set to {StatsD#default_sample_rate}.
@!attribute tags
The tags to associate with the metric. @note Only the Datadog implementation supports tags. @see .normalize_tags @return [Array<String>, Hash<String, String>, nil] the tags to associate with the metric. You can either specify the tags as an array of strings, or a Hash of key/value pairs.
@see StatsD
The StatsD
module contains methods that generate metric instances. @see StatsD::Instrument::Backend
A StatsD::Instrument::Backend
is used to collect metrics.
Constants
- TYPES
The metric types that are supported by this library. Note that every
StatsD
server implementation only supports a subset of them.
Attributes
Public Class Methods
The default value for this metric, which will be used if it is not set.
A default value is only defined for counter metrics (1
). For all other metric types, this method will raise an ArgumentError
.
A default value is only defined for counter metrics (1
). For all other metric types, this method will raise an ArgumentError
.
@return [Numeric, String] The default value for this metric. @raise ArgumentError if the metric type doesn't have a default value
# File lib/statsd/instrument/metric.rb, line 65 def self.default_value(type) case type when :c then 1 else raise ArgumentError, "A value is required for metric type #{type.inspect}." end end
# File lib/statsd/instrument/metric.rb, line 46 def self.new(type:, name:, value: default_value(type), tags: nil, metadata: nil, sample_rate: StatsD.legacy_singleton_client.default_sample_rate) # pass keyword arguments as positional arguments for performance reasons, # since MRI's C implementation of new turns keyword arguments into a hash super(type, name, value, sample_rate, tags, metadata) end
Initializes a new metric instance. Normally, you don't want to call this method directly, but use one of the metric collection methods on the {StatsD} module.
@param type [Symbol] The type of the metric. @option name [String] :name The name of the metric without prefix. @option value [Numeric, String, nil] The value to collect for the metric. @option sample_rate
[Numeric, nil] The sample rate to use. If not set, it will use
{StatsD#default_sample_rate}.
@option tags [Array<String>, Hash<String, String>, nil] :tags The tags to apply to this metric.
See {.normalize_tags} for more information.
# File lib/statsd/instrument/metric.rb, line 85 def initialize(type, name, value, sample_rate, tags, metadata) # rubocop:disable Metrics/ParameterLists raise ArgumentError, "Metric :type is required." unless type raise ArgumentError, "Metric :name is required." unless name raise ArgumentError, "Metric :value is required." unless value @type = type @name = normalize_name(name) @value = value @sample_rate = sample_rate @tags = StatsD::Instrument::Metric.normalize_tags(tags) if StatsD.legacy_singleton_client.default_tags @tags = Array(@tags) + StatsD.legacy_singleton_client.default_tags end @metadata = metadata end
Public Instance Methods
@private @return [String]
# File lib/statsd/instrument/metric.rb, line 112 def inspect "#<StatsD::Instrument::Metric #{self}>" end
Strip metric names of special characters used by StatsD
line protocol, replace with underscore
@param name [String] @return [String]
# File lib/statsd/instrument/metric.rb, line 132 def normalize_name(name) # fast path when no normalization is needed to avoid copying the string return name unless /[:|@]/.match?(name) name.tr(':|@', '_') end
@private @return [String]
# File lib/statsd/instrument/metric.rb, line 103 def to_s str = +"#{name}:#{value}|#{type}" str << "|@#{sample_rate}" if sample_rate && sample_rate != 1.0 str << "|#" << tags.join(',') if tags && !tags.empty? str end