- More config doc and related cleanup

lib/logstash/outputs/beanstalk.rb

@@ -5,22 +5,25 @@ require "beanstalk-client"
 class LogStash::Outputs::Beanstalk < LogStash::Outputs::Base
 
   config_name "beanstalk"
+
+  # The address of the beanstalk server
   config :host, :validate => :string, :required => true
-  config :port, :validate => :number
+
+  # The port of your beanstalk server
+  config :port, :validate => :number, :default => 11300
+
+  # The name of the beanstalk tube
   config :tube, :validate => :string, :required => true
-  config :priority, :validate => :number
-  config :delay, :validate => :number
-  config :ttr, :validate => :number
 
-  public
-  def initialize(params)
-    super
+  # The message priority (see beanstalk docs)
+  config :priority, :validate => :number, :default => 65536
 
-    @port ||= 11300
-    @priority ||= 65536
-    @delay ||= 0
-    @ttr ||= 300
-  end
+  # The message delay (see beanstalk docs)
+  config :delay, :validate => :number, :default => 0
+
+  # TODO(sissel): Document this
+  # See beanstalk documentation
+  config :ttr, :validate => :number, :default => 300
 
   public
   def register

lib/logstash/outputs/elasticsearch.rb

@@ -3,24 +3,33 @@ require "logstash/outputs/base"
 
 # TODO(sissel): find a better way of declaring where the elasticsearch
 # libraries are
-Dir["/home/jls/build/elasticsearch-0.15.0//lib/*.jar"].each do |jar|
-  require jar
-end
-
+# TODO(sissel): can skip this step if we're running from a jar.
 jarpath = File.join(File.dirname(__FILE__), "../../../vendor/**/*.jar")
 Dir[jarpath].each do |jar|
     require jar
 end
 
-
+# TODO(sissel): Remove old cruft from pre-jruby
+# TODO(sissel): Support river again?
 class LogStash::Outputs::Elasticsearch < LogStash::Outputs::Base
 
   # http://host/index/type
   config_name "elasticsearch"
+
+  # ElasticSearch server name. This is optional if your server is discoverable.
   config :host, :validate => :string
-  config :index, :validate => :string
-  config :type, :validate => :string
+
+  # The index to write events to. This can be dynamic using the %{foo} syntax.
+  config :index, :validate => :string, :default => "logstash"
+
+  # The type to write events to. Generally you should try to write only similar
+  # events to the same 'type'. String expansion '%{foo}' works here.
+  config :type, :validate => :string, :default => "%{@type}"
+
+  # The name of your cluster if you set it on the ElasticSearch side. Useful
+  # for discovery.
   config :cluster, :validate => :string
+
   # TODO(sissel): Config for river?
 
   public

lib/logstash/outputs/gelf.rb

@@ -1,32 +1,29 @@
-# GELF output
-# http://www.graylog2.org/about/gelf
-#
-# This class doesn't currently use 'eventmachine'-style code, so it may
-# block things. Whatever, we can fix that later ;)
-
 require "gelf" # rubygem 'gelf'
 require "logstash/namespace"
 require "logstash/outputs/base"
 
+# GELF output. This is most useful if you want to use logstash
+# to output events to graylog2.
+#
+# http://www.graylog2.org/about/gelf
 class LogStash::Outputs::Gelf < LogStash::Outputs::Base
 
   config_name "gelf"
+  
+  # graylog2 server address
   config :host, :validate => :string, :required => true
-  config :port, :validate => :number
-  config :chunksize, :validate => :number
-  config :level, :validate => :number
-  config :facility, :validate => :string
 
-  public
-  def initialize(params)
-    super
+  # graylog2 server port
+  config :port, :validate => :number, :default => 12201
 
-    @port ||= 12201
-    @chunksize ||= 1420
-    @level ||= 1
-    @facility ||= 'logstash-gelf'
+  # The GELF chunksize
+  config :chunksize, :validate => :number, :default => 1420
 
-  end
+  # The GELF message level
+  config :level, :validate => :number, :default => 1
+
+  # The GELF facility.
+  config :facility, :validate => :string, :default => "logstash-gelf"
 
   public
   def register

lib/logstash/outputs/mongodb.rb

@@ -6,18 +6,19 @@ class LogStash::Outputs::Mongodb < LogStash::Outputs::Base
 
   config_name "mongodb"
 
+  # your mongdob host
   config :host, :validate => :string, :required => true
-  config :port, :validate => :number
+
+  # the mongodb port
+  config :port, :validate => :number, :default => Mongo::Connection::DEFAULT_PORT
+
+  # The database to use
   config :database, :validate => :string, :required => true
+
+  # The collection to use. This value can use %{foo} values to dynamically
+  # select a collection based on data in th eevent.
   config :collection, :validate => :string, :required => true
 
-  public
-  def initialize(params)
-    super
-
-    @port ||= Mongo::Connection::DEFAULT_PORT
-  end
-
   public
   def register
     # TODO(petef): support authentication
@@ -27,6 +28,6 @@ class LogStash::Outputs::Mongodb < LogStash::Outputs::Base
 
   public
   def receive(event)
-    @mongodb.collection(@collection).insert(event.to_hash)
+    @mongodb.collection(event.sprintf(@collection)).insert(event.to_hash)
   end # def receive
 end # class LogStash::Outputs::Mongodb

lib/logstash/outputs/nagios.rb

@@ -1,19 +1,51 @@
 require "logstash/namespace"
 require "logstash/outputs/base"
 
+# The nagios output is used for sending passive check results to nagios via the
+# nagios command file. 
+#
+# For this output to work, your event must have the following fields:
+#   "nagios_host"
+#   "nagios_service"
+#
+# This field is supported, but optional:
+#   "nagios_annotation"
+#
+# The easiest way to use this output is with the grep filter.
+# Presumably, you only want certain events matching a given pattern
+# to send events to nagios. So use grep to match and also to add the required
+# fields.
+#
+#     filters {
+#       grep {
+#         type => "linux-syslog"
+#         match => [ "@message", "(error|ERROR|CRITICAL)" ]
+#         add_tag => [ "nagios-update" ]
+#         add_fields => [
+#           "nagios_host", "%{@source_host}",
+#           "nagios_service", "the name of your nagios service check"
+#         ]
+#      }
+#    }
+#    
+#    outputs {
+#      nagios { 
+#        # only process events with this tag
+#        tags => "nagios-update"
+#      }
+#    }
 class LogStash::Outputs::Nagios < LogStash::Outputs::Base
   NAGIOS_CRITICAL = 2
   NAGIOS_WARN = 1
 
   config_name "nagios"
-  config :commandfile, :validate => :string
 
-  public
-  def initialize(params)
-    super
+  # The path to your nagios command file
+  config :commandfile, :validate => :string, :default => "/var/lib/nagios3/rw/nagios.cmd"
 
-    @commandfile ||= "/var/lib/nagios3/rw/nagios.cmd"
-  end # def initialize
+  # Only handle events with any of these tags. Optional.
+  # If not specified, will process all events.
+  config :tags, :validate => :array, :default => []
 
   public
   def register
@@ -22,6 +54,13 @@ class LogStash::Outputs::Nagios < LogStash::Outputs::Base
 
   public
   def receive(event)
+    if !@tags.empty?
+      if (event.tags - @tags).size == 0
+        # Skip events that have no tags in common with what we were configured
+        return
+      end
+    end
+
     if !File.exists?(@commandfile)
       @logger.warn(["Skipping nagios output; command file is missing",
                    {"commandfile" => @commandfile, "missed_event" => event}])
@@ -65,7 +104,7 @@ class LogStash::Outputs::Nagios < LogStash::Outputs::Base
     begin
       File.open(@commandfile, "r+") do |f|
         f.puts(cmd)
-        f.flush
+        f.flush # TODO(sissel): probably don't need this.
       end
     rescue
       @logger.warn(["Skipping nagios output; error writing to command file",

lib/logstash/outputs/stdout.rb

@@ -10,6 +10,8 @@ class LogStash::Outputs::Stdout < LogStash::Outputs::Base
   end
 
   config_name "stdout"
+
+  # Enable debugging. Tries to pretty-print the entire event object.
   config :debug, :validate => :boolean
 
   public

lib/logstash/outputs/stomp.rb

@@ -3,20 +3,28 @@ require "logstash/namespace"
 
 class LogStash::Outputs::Stomp < LogStash::Outputs::Base
   config_name "stomp"
+
+  
+  # The address of the STOMP server.
   config :host, :validate => :string
-  config :port, :validate => :number
-  config :user, :validate => :string
-  config :password, :validate => :string
+
+  # The port to connet to on your STOMP server.
+  config :port, :validate => :number, :default => 61613
+
+  # The username to authenticate with.
+  config :user, :validate => :string, :default => ""
+
+  # The password to authenticate with.
+  config :password, :validate => :password, :default => ""
+
+  # The destination to read events from. Supports string expansion, meaning
+  # %{foo} values will expand to the field value.
+  #
+  # Example: "/topic/logstash"
   config :destination, :validate => :string
-  config :debug, :validate => :boolean
 
-  public
-  def initialize(params)
-    super
-
-    @debug ||= false
-    @port ||= 61613
-  end # def initialize
+  # Enable debugging output?
+  config :debug, :validate => :boolean, :default => false
 
   public
   def register
@@ -27,6 +35,6 @@ class LogStash::Outputs::Stomp < LogStash::Outputs::Base
   public
   def receive(event)
     @logger.debug(["stomp sending event", { :host => @host, :event => event }])
-    @client.publish(@destination, event.to_json)
+    @client.publish(event.sprintf(@destination), event.to_json)
   end # def receive
 end # class LogStash::Outputs::Stomp

lib/logstash/outputs/tcp.rb

@@ -1,11 +1,18 @@
 require "logstash/outputs/base"
 require "logstash/namespace"
 
+# This output writes each event in json format to 
+# the specified host:port over tcp.
+#
+# Each event json is separated by a newline.
 class LogStash::Outputs::Tcp < LogStash::Outputs::Base
 
   config_name "tcp"
 
+  # The host to connect to
   config :host, :validate => :string, :required => true
+
+  # The port to connect to
   config :port, :validate => :number, :required => true
 
   public

lib/logstash/outputs/websocket.rb

@@ -2,8 +2,14 @@ require "em-websocket" # rubygem 'em-websocket'
 require "logstash/namespace"
 require "logstash/outputs/base"
 
+# TODO(sissel): THIS IS NOT SUPPORTED IN JRUBY YET
 class LogStash::Outputs::Websocket < LogStash::Outputs::Base
-  config :address, :validate => :string
+
+  # The address to serve websocket data from
+  config :host, :validate => :string, :default => "0.0.0.0"
+
+  # The port to serve websocket data from
+  config :port, :validate => :number, :default => 3232
 
   public
   def register