logstash-filter-throttle 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDViZWUyMDc0NzZhYzQ1MDgxNzRmNDQ4MmU0MzJjYzA4NzMwMzQwMQ==
+  data.tar.gz: !binary |-
+    ZmQzZTQwYThjODVhZmMzZTVjODI1NWU1ZDc2ZWIzY2ZmOTcxZjc5Zg==
+SHA512:
+  metadata.gz: !binary |-
+    NjQ0ZDBmNjc0ZjcyODFhOTFlZDMxNThkODE4NzM1MTM1ZWZhMDc4NWQ4NzVj
+    ODg2NjQ0OGQyMzQwNWE0YjQxZDIwNjNmMTY3N2NiZDc4Y2IyNDM1ODEzYjhh
+    ZTU4NDZhYjk2NmJmNDBkNTdhNzIxM2Y3OWUzYzVhYzRmZWJjNWQ=
+  data.tar.gz: !binary |-
+    ZjVmNTE1YTkxMjEwYTlmOGEyYzBjNTE2MDhkOGU1N2UzNzU3MmI2MWQ0NTVh
+    ZmI0MGNjYzgzZjk2MDVkYWZjZTg1MWNjODZlYzI3MDA5YTJjMjE3OGUyNzQ4
+    YzczMjk5Y2EzOGU1ZTM0ZDhjMDI0NjVlMTdkYjU5NzI0ZmFkMzg=

data/.gitignore

@@ -0,0 +1,4 @@
+*.gem
+Gemfile.lock
+.bundle
+vendor

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+gem 'rake'
+gem 'gem_publisher'
+gem 'archive-tar-minitar'

data/Rakefile

@@ -0,0 +1,6 @@
+@files=[]
+
+task :default do
+  system("rake -T")
+end
+

data/lib/logstash/filters/throttle.rb

@@ -0,0 +1,261 @@
+require "logstash/filters/base"
+require "logstash/namespace"
+
+# The throttle filter is for throttling the number of events received. The filter
+# is configured with a lower bound, the before_count, and upper bound, the after_count,
+# and a period of time. All events passing through the filter will be counted based on 
+# a key. As long as the count is less than the before_count or greater than the 
+# after_count, the event will be "throttled" which means the filter will be considered 
+# successful and any tags or fields will be added.
+#
+# For example, if you wanted to throttle events so you only receive an event after 2 
+# occurrences and you get no more than 3 in 10 minutes, you would use the 
+# configuration:
+#     period => 600
+#     before_count => 3
+#     after_count => 5
+#
+# Which would result in:
+#     event 1 - throttled (successful filter, period start)
+#     event 2 - throttled (successful filter)
+#     event 3 - not throttled
+#     event 4 - not throttled
+#     event 5 - not throttled
+#     event 6 - throttled (successful filter)
+#     event 7 - throttled (successful filter)
+#     event x - throttled (successful filter)
+#     period end
+#     event 1 - throttled (successful filter, period start)
+#     event 2 - throttled (successful filter)
+#     event 3 - not throttled
+#     event 4 - not throttled
+#     event 5 - not throttled
+#     event 6 - throttled (successful filter)
+#     ...
+# 
+# Another example is if you wanted to throttle events so you only receive 1 event per 
+# hour, you would use the configuration:
+#     period => 3600
+#     before_count => -1
+#     after_count => 1
+#
+# Which would result in:
+#     event 1 - not throttled (period start)
+#     event 2 - throttled (successful filter)
+#     event 3 - throttled (successful filter)
+#     event 4 - throttled (successful filter)
+#     event x - throttled (successful filter)
+#     period end
+#     event 1 - not throttled (period start)
+#     event 2 - throttled (successful filter)
+#     event 3 - throttled (successful filter)
+#     event 4 - throttled (successful filter)
+#     ...
+# 
+# A common use case would be to use the throttle filter to throttle events before 3 and 
+# after 5 while using multiple fields for the key and then use the drop filter to remove 
+# throttled events. This configuration might appear as:
+# 
+#     filter {
+#       throttle {
+#         before_count => 3
+#         after_count => 5
+#         period => 3600
+#         key => "%{host}%{message}"
+#         add_tag => "throttled"
+#       }
+#       if "throttled" in [tags] {
+#         drop { }
+#       }
+#     }
+#
+# Another case would be to store all events, but only email non-throttled 
+# events so the op's inbox isn't flooded with emails in the event of a system error. 
+# This configuration might appear as:
+#
+#     filter {
+#       throttle {
+#         before_count => 3
+#         after_count => 5
+#         period => 3600
+#         key => "%{message}"
+#         add_tag => "throttled"
+#       }
+#     }
+#     output {
+#       if "throttled" not in [tags] {
+#         email {
+#    	    from => "logstash@mycompany.com"
+#    	    subject => "Production System Alert"
+#    	    to => "ops@mycompany.com"
+#    	    via => "sendmail"
+#    	    body => "Alert on %{host} from path %{path}:\n\n%{message}"
+#    	    options => { "location" => "/usr/sbin/sendmail" }
+#         }
+#       }
+#       elasticsearch_http {
+#         host => "localhost"
+#         port => "19200"
+#       }
+#     }
+#
+# The event counts are cleared after the configured period elapses since the 
+# first instance of the event. That is, all the counts don't reset at the same 
+# time but rather the throttle period is per unique key value.
+#
+# Mike Pilone (@mikepilone)
+# 
+class LogStash::Filters::Throttle < LogStash::Filters::Base
+
+  # The name to use in configuration files.
+  config_name "throttle"
+
+  # New plugins should start life at milestone 1.
+  milestone 1
+
+  # The key used to identify events. Events with the same key will be throttled
+  # as a group.  Field substitutions are allowed, so you can combine multiple
+  # fields.
+  config :key, :validate => :string, :required => true
+  
+  # Events less than this count will be throttled. Setting this value to -1, the 
+  # default, will cause no messages to be throttled based on the lower bound.
+  config :before_count, :validate => :number, :default => -1, :required => false
+  
+  # Events greater than this count will be throttled. Setting this value to -1, the 
+  # default, will cause no messages to be throttled based on the upper bound.
+  config :after_count, :validate => :number, :default => -1, :required => false
+  
+  # The period in seconds after the first occurrence of an event until the count is 
+  # reset for the event. This period is tracked per unique key value.  Field
+  # substitutions are allowed in this value.  They will be evaluated when the _first_
+  # event for a given key is seen.  This allows you to specify that certain kinds
+  # of events throttle for a specific period.
+  config :period, :validate => :string, :default => "3600", :required => false
+  
+  # The maximum number of counters to store before the oldest counter is purged. Setting 
+  # this value to -1 will prevent an upper bound no constraint on the number of counters  
+  # and they will only be purged after expiration. This configuration value should only 
+  # be used as a memory control mechanism and can cause early counter expiration if the 
+  # value is reached. It is recommended to leave the default value and ensure that your 
+  # key is selected such that it limits the number of counters required (i.e. don't 
+  # use UUID as the key!)
+  config :max_counters, :validate => :number, :default => 100000, :required => false
+
+  # Performs initialization of the filter.
+  public
+  def register
+    @threadsafe = false
+  
+    @event_counters = Hash.new
+    @next_expiration = nil
+  end # def register
+
+  # Filters the event. The filter is successful if the event should be throttled.
+  public
+  def filter(event)
+      	  
+    # Return nothing unless there's an actual filter event
+    return unless filter?(event)
+    	  
+    now = Time.now
+    key = event.sprintf(@key)
+    
+    # Purge counters if too large to prevent OOM.
+    if @max_counters != -1 && @event_counters.size > @max_counters then
+      purgeOldestEventCounter()
+    end
+    
+    # Expire existing counter if needed
+    if @next_expiration.nil? || now >= @next_expiration then
+    	expireEventCounters(now)
+    end
+    
+    @logger.debug? and @logger.debug(
+      	  "filters/#{self.class.name}: next expiration", 
+      	  { "next_expiration" => @next_expiration })
+    
+    # Create new counter for this event if this is the first occurrence
+    counter = nil
+    if !@event_counters.include?(key) then
+      period = event.sprintf(@period).to_i
+      period = 3600 if period == 0
+      expiration = now + period
+      @event_counters[key] = { :count => 0, :expiration => expiration }
+      
+      @logger.debug? and @logger.debug("filters/#{self.class.name}: new event", 
+      	  { :key => key, :expiration => expiration })
+    end
+    
+    # Fetch the counter
+    counter = @event_counters[key]
+    
+    # Count this event
+    counter[:count] = counter[:count] + 1;
+    
+    @logger.debug? and @logger.debug("filters/#{self.class.name}: current count", 
+      	  { :key => key, :count => counter[:count] })
+    
+    # Throttle if count is < before count or > after count
+    if ((@before_count != -1 && counter[:count] < @before_count) || 
+       (@after_count != -1 && counter[:count] > @after_count)) then
+      @logger.debug? and @logger.debug(
+      	  "filters/#{self.class.name}: throttling event", { :key => key })
+      	
+      filter_matched(event)
+    end
+        
+  end # def filter
+  
+  # Expires any counts where the period has elapsed. Sets the next expiration time 
+  # for when this method should be called again.
+  private
+  def expireEventCounters(now) 
+    
+    @next_expiration = nil
+    
+    @event_counters.delete_if do |key, counter|
+      expiration = counter[:expiration]
+      expired = expiration <= now
+    
+      if expired then
+      	@logger.debug? and @logger.debug(
+      	  "filters/#{self.class.name}: deleting expired counter", 
+      	  { :key => key })
+      	  
+      elsif @next_expiration.nil? || (expiration < @next_expiration)
+      	@next_expiration = expiration
+      end
+      
+      expired
+    end
+  
+  end # def expireEventCounters
+  
+  # Purges the oldest event counter. This operation is for memory control only 
+  # and can cause early period expiration and thrashing if invoked.
+  private
+  def purgeOldestEventCounter()
+    
+    # Return unless we have something to purge
+    return unless @event_counters.size > 0
+    
+    oldestCounter = nil
+    oldestKey = nil
+    
+    @event_counters.each do |key, counter|
+      if oldestCounter.nil? || counter[:expiration] < oldestCounter[:expiration] then
+        oldestKey = key;
+        oldestCounter = counter;
+      end
+    end
+    
+    @logger.warn? and @logger.warn(
+      "filters/#{self.class.name}: Purging oldest counter because max_counters " +
+      "exceeded. Use a better key to prevent too many unique event counters.", 
+      { :key => oldestKey, :expiration => oldestCounter[:expiration] })
+      	  
+    @event_counters.delete(oldestKey)
+    
+  end
+end # class LogStash::Filters::Throttle

data/logstash-filter-throttle.gemspec

@@ -0,0 +1,26 @@
+Gem::Specification.new do |s|
+
+  s.name            = 'logstash-filter-throttle'
+  s.version         = '0.1.0'
+  s.licenses        = ['Apache License (2.0)']
+  s.summary         = "The throttle filter is for throttling the number of events received."
+  s.description     = "The throttle filter is for throttling the number of events received."
+  s.authors         = ["Elasticsearch"]
+  s.email           = 'richard.pijnenburg@elasticsearch.com'
+  s.homepage        = "http://logstash.net/"
+  s.require_paths = ["lib"]
+
+  # Files
+  s.files = `git ls-files`.split($\)
+
+  # Tests
+  s.test_files = s.files.grep(%r{^(test|spec|features)/})
+
+  # Special flag to let us know this is actually a logstash plugin
+  s.metadata = { "logstash_plugin" => "true", "group" => "filter" }
+
+  # Gem dependencies
+  s.add_runtime_dependency 'logstash', '>= 1.4.0', '< 2.0.0'
+
+end
+

data/rakelib/publish.rake

@@ -0,0 +1,9 @@
+require "gem_publisher"
+
+desc "Publish gem to RubyGems.org"
+task :publish_gem do |t|
+  gem_file = Dir.glob(File.expand_path('../*.gemspec',File.dirname(__FILE__))).first
+  gem = GemPublisher.publish_if_updated(gem_file, :rubygems)
+  puts "Published #{gem}" if gem
+end
+

data/rakelib/vendor.rake

@@ -0,0 +1,169 @@
+require "net/http"
+require "uri"
+require "digest/sha1"
+
+def vendor(*args)
+  return File.join("vendor", *args)
+end
+
+directory "vendor/" => ["vendor"] do |task, args|
+  mkdir task.name
+end
+
+def fetch(url, sha1, output)
+
+  puts "Downloading #{url}"
+  actual_sha1 = download(url, output)
+
+  if actual_sha1 != sha1
+    fail "SHA1 does not match (expected '#{sha1}' but got '#{actual_sha1}')"
+  end
+end # def fetch
+
+def file_fetch(url, sha1)
+  filename = File.basename( URI(url).path )
+  output = "vendor/#{filename}"
+  task output => [ "vendor/" ] do
+    begin
+      actual_sha1 = file_sha1(output)
+      if actual_sha1 != sha1
+        fetch(url, sha1, output)
+      end
+    rescue Errno::ENOENT
+      fetch(url, sha1, output)
+    end
+  end.invoke
+
+  return output
+end
+
+def file_sha1(path)
+  digest = Digest::SHA1.new
+  fd = File.new(path, "r")
+  while true
+    begin
+      digest << fd.sysread(16384)
+    rescue EOFError
+      break
+    end
+  end
+  return digest.hexdigest
+ensure
+  fd.close if fd
+end
+
+def download(url, output)
+  uri = URI(url)
+  digest = Digest::SHA1.new
+  tmp = "#{output}.tmp"
+  Net::HTTP.start(uri.host, uri.port, :use_ssl => (uri.scheme == "https")) do |http|
+    request = Net::HTTP::Get.new(uri.path)
+    http.request(request) do |response|
+      fail "HTTP fetch failed for #{url}. #{response}" if [200, 301].include?(response.code)
+      size = (response["content-length"].to_i || -1).to_f
+      count = 0
+      File.open(tmp, "w") do |fd|
+        response.read_body do |chunk|
+          fd.write(chunk)
+          digest << chunk
+          if size > 0 && $stdout.tty?
+            count += chunk.bytesize
+            $stdout.write(sprintf("\r%0.2f%%", count/size * 100))
+          end
+        end
+      end
+      $stdout.write("\r      \r") if $stdout.tty?
+    end
+  end
+
+  File.rename(tmp, output)
+
+  return digest.hexdigest
+rescue SocketError => e
+  puts "Failure while downloading #{url}: #{e}"
+  raise
+ensure
+  File.unlink(tmp) if File.exist?(tmp)
+end # def download
+
+def untar(tarball, &block)
+  require "archive/tar/minitar"
+  tgz = Zlib::GzipReader.new(File.open(tarball))
+  # Pull out typesdb
+  tar = Archive::Tar::Minitar::Input.open(tgz)
+  tar.each do |entry|
+    path = block.call(entry)
+    next if path.nil?
+    parent = File.dirname(path)
+    
+    mkdir_p parent unless File.directory?(parent)
+
+    # Skip this file if the output file is the same size
+    if entry.directory?
+      mkdir path unless File.directory?(path)
+    else
+      entry_mode = entry.instance_eval { @mode } & 0777
+      if File.exists?(path)
+        stat = File.stat(path)
+        # TODO(sissel): Submit a patch to archive-tar-minitar upstream to
+        # expose headers in the entry.
+        entry_size = entry.instance_eval { @size }
+        # If file sizes are same, skip writing.
+        next if stat.size == entry_size && (stat.mode & 0777) == entry_mode
+      end
+      puts "Extracting #{entry.full_name} from #{tarball} #{entry_mode.to_s(8)}"
+      File.open(path, "w") do |fd|
+        # eof? check lets us skip empty files. Necessary because the API provided by
+        # Archive::Tar::Minitar::Reader::EntryStream only mostly acts like an
+        # IO object. Something about empty files in this EntryStream causes
+        # IO.copy_stream to throw "can't convert nil into String" on JRuby
+        # TODO(sissel): File a bug about this.
+        while !entry.eof?
+          chunk = entry.read(16384)
+          fd.write(chunk)
+        end
+          #IO.copy_stream(entry, fd)
+      end
+      File.chmod(entry_mode, path)
+    end
+  end
+  tar.close
+  File.unlink(tarball) if File.file?(tarball)
+end # def untar
+
+def ungz(file)
+
+  outpath = file.gsub('.gz', '')
+  tgz = Zlib::GzipReader.new(File.open(file))
+  begin
+    File.open(outpath, "w") do |out|
+      IO::copy_stream(tgz, out)
+    end
+    File.unlink(file)
+  rescue
+    File.unlink(outpath) if File.file?(outpath)
+   raise
+  end
+  tgz.close
+end
+
+desc "Process any vendor files required for this plugin"
+task "vendor" do |task, args|
+
+  @files.each do |file| 
+    download = file_fetch(file['url'], file['sha1'])
+    if download =~ /.tar.gz/
+      prefix = download.gsub('.tar.gz', '').gsub('vendor/', '')
+      untar(download) do |entry|
+        if !file['files'].nil?
+          next unless file['files'].include?(entry.full_name.gsub(prefix, ''))
+          out = entry.full_name.split("/").last
+        end
+        File.join('vendor', out)
+      end
+    elsif download =~ /.gz/
+      ungz(download)
+    end
+  end
+
+end

data/spec/filters/throttle_spec.rb

@@ -0,0 +1,196 @@
+require "spec_helper"
+require "logstash/filters/throttle"
+
+describe LogStash::Filters::Throttle do
+
+  describe "no before_count" do
+    config <<-CONFIG
+      filter {
+        throttle {
+          period => 60
+          after_count => 2
+          key => "%{host}"
+          add_tag => [ "throttled" ]
+        }
+      }
+    CONFIG
+
+    event = {
+      "host" => "server1"
+    }
+
+    sample event do
+      insist { subject["tags"] } == nil
+    end
+  end
+  
+  describe "before_count throttled" do
+    config <<-CONFIG
+      filter {
+        throttle {
+          period => 60
+          before_count => 2
+          after_count => 3
+          key => "%{host}"
+          add_tag => [ "throttled" ]
+        }
+      }
+    CONFIG
+
+    event = {
+      "host" => "server1"
+    }
+
+    sample event do
+      insist { subject["tags"] } == [ "throttled" ]
+    end
+  end
+  
+  describe "before_count exceeded" do
+    config <<-CONFIG
+      filter {
+        throttle {
+          period => 60
+          before_count => 2
+          after_count => 3
+          key => "%{host}"
+          add_tag => [ "throttled" ]
+        }
+      }
+    CONFIG
+
+    events = [{
+      "host" => "server1"
+    }, {
+      "host" => "server1"
+    }]
+
+    sample events do
+      insist { subject[0]["tags"] } == [ "throttled" ]
+      insist { subject[1]["tags"] } == nil
+    end
+  end
+  
+  describe "after_count exceeded" do
+    config <<-CONFIG
+      filter {
+        throttle {
+          period => 60
+          before_count => 2
+          after_count => 3
+          key => "%{host}"
+          add_tag => [ "throttled" ]
+        }
+      }
+    CONFIG
+
+    events = [{
+      "host" => "server1"
+    }, {
+      "host" => "server1"
+    }, {
+      "host" => "server1"
+    }, {
+      "host" => "server1"
+    }]
+
+    sample events do
+      insist { subject[0]["tags"] } == [ "throttled" ]
+      insist { subject[1]["tags"] } == nil
+      insist { subject[2]["tags"] } == nil
+      insist { subject[3]["tags"] } == [ "throttled" ]
+    end
+  end
+  
+  describe "different keys" do
+    config <<-CONFIG
+      filter {
+        throttle {
+          period => 60
+          after_count => 2
+          key => "%{host}"
+          add_tag => [ "throttled" ]
+        }
+      }
+    CONFIG
+
+    events = [{
+      "host" => "server1"
+    }, {
+      "host" => "server2"
+    }, {
+      "host" => "server3"
+    }, {
+      "host" => "server4"
+    }]
+
+    sample events do
+      subject.each { | s |
+        insist { s["tags"] } == nil
+      }
+    end
+  end
+  
+  describe "composite key" do
+    config <<-CONFIG
+      filter {
+        throttle {
+          period => 60
+          after_count => 1
+          key => "%{host}%{message}"
+          add_tag => [ "throttled" ]
+        }
+      }
+    CONFIG
+
+    events = [{
+      "host" => "server1",
+      "message" => "foo"
+    }, {
+      "host" => "server1",
+      "message" => "bar"
+    }, {
+      "host" => "server2",
+      "message" => "foo"
+    }, {
+      "host" => "server2",
+      "message" => "bar"
+    }]
+
+    sample events do
+      subject.each { | s |
+        insist { s["tags"] } == nil
+      }
+    end
+  end
+  
+  describe "max_counter exceeded" do
+    config <<-CONFIG
+      filter {
+        throttle {
+          period => 60
+          after_count => 1
+          max_counters => 2
+          key => "%{message}"
+          add_tag => [ "throttled" ]
+        }
+      }
+    CONFIG
+
+    events = [{
+      "message" => "foo"
+    }, {
+      "message" => "bar"
+    }, {
+      "message" => "poo"
+    }, {
+      "message" => "foo"
+    }]
+
+    sample events do
+      insist { subject[3]["tags"] } == nil
+    end
+  end
+
+end # LogStash::Filters::Throttle
+

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: logstash-filter-throttle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Elasticsearch
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logstash
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+    - - <
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+    - - <
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+description: The throttle filter is for throttling the number of events received.
+email: richard.pijnenburg@elasticsearch.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Rakefile
+- lib/logstash/filters/throttle.rb
+- logstash-filter-throttle.gemspec
+- rakelib/publish.rake
+- rakelib/vendor.rake
+- spec/filters/throttle_spec.rb
+homepage: http://logstash.net/
+licenses:
+- Apache License (2.0)
+metadata:
+  logstash_plugin: 'true'
+  group: filter
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.1
+signing_key: 
+specification_version: 4
+summary: The throttle filter is for throttling the number of events received.
+test_files:
+- spec/filters/throttle_spec.rb