class LogStash::Outputs::Statsd

statsd is a network daemon for aggregating statistics, such as counters and timers, and shipping over UDP to backend services, such as Graphite or Datadog. The general idea is that you send metrics to statsd and every few seconds it will emit the aggregated values to the backend. Example aggregates are sums, average and maximum values, their standard deviation, etc. This plugin makes it easy to send such metrics based on data in Logstash events.

You can learn about statsd here:

Typical examples of how this can be used with Logstash include counting HTTP hits by response code, summing the total number of bytes of traffic served, and tracking the 50th and 95th percentile of the processing time of requests.

Each metric emitted to statsd has a dot-separated path, a type, and a value. The metric path is built from the `namespace` and `sender` options together with the metric name that's picked up depending on the type of metric. All in all, the metric path will follow this pattern:

namespace.sender.metric

With regards to this plugin, the default namespace is “logstash”, the default sender is the `host` field, and the metric name depends on what is set as the metric name in the `increment`, `decrement`, `timing`, `count`, `set` or `gauge` options. In metric paths, colons (“:”), pipes (“|”) and at signs (“@”) are reserved and will be replaced by underscores (“_”).

Example:

source,ruby

output {

statsd {
  host => "statsd.example.org"
  count => {
    "http.bytes" => "%{bytes}"
  }
}

}

If run on a host named hal9000 the configuration above will send the following metric to statsd if the current event has 123 in its `bytes` field:

logstash.hal9000.http.bytes:123|c

Constants

RESERVED_CHARACTERS_REGEX

Regex stolen from statsd code

Public Instance Methods

build_stat(metric, sender=@sender) click to toggle source
# File lib/logstash/outputs/statsd.rb, line 136
def build_stat(metric, sender=@sender)
  sender = sender.to_s.gsub('::','.')
  sender.gsub!(RESERVED_CHARACTERS_REGEX, '_')
  sender.gsub!(".", "_")
  metric = metric.to_s.gsub('::','.')
  metric.gsub!(RESERVED_CHARACTERS_REGEX, '_')
  @logger.debug? and @logger.debug("Formatted value", :sender => sender, :metric => metric)
  return "#{sender}.#{metric}"
end
receive(event) click to toggle source
# File lib/logstash/outputs/statsd.rb, line 105
def receive(event)
  
  @client.namespace = event.sprintf(@namespace) if not @namespace.empty?
  @logger.debug? and @logger.debug("Original sender: #{@sender}")
  sender = event.sprintf(@sender)
  @logger.debug? and @logger.debug("Munged sender: #{sender}")
  @logger.debug? and @logger.debug("Event: #{event}")
  @increment.each do |metric|
    @client.increment(build_stat(event.sprintf(metric), sender), @sample_rate)
  end
  @decrement.each do |metric|
    @client.decrement(build_stat(event.sprintf(metric), sender), @sample_rate)
  end
  @count.each do |metric, val|
    @client.count(build_stat(event.sprintf(metric), sender),
                  event.sprintf(val), @sample_rate)
  end
  @timing.each do |metric, val|
    @client.timing(build_stat(event.sprintf(metric), sender),
                   event.sprintf(val), @sample_rate)
  end
  @set.each do |metric, val|
    @client.set(build_stat(event.sprintf(metric), sender),
                  event.sprintf(val), @sample_rate)
  end
  @gauge.each do |metric, val|
    @client.gauge(build_stat(event.sprintf(metric), sender),
                  event.sprintf(val), @sample_rate)
  end
end
register() click to toggle source
# File lib/logstash/outputs/statsd.rb, line 99
def register
  require "statsd"
  @client = Statsd.new(@host, @port, @protocol.to_sym)
end