- Add config docs

- add more defaults and clean up any unnecessary initialize methods

lib/logstash/inputs/amqp.rb

@@ -1,12 +1,16 @@
 require "logstash/inputs/base"
 require "logstash/namespace"
 
+# Pull events from an AMQP exchange.
+#
+# 
+# TODO(sissel): Document where to learn more about AMQP and brokers.
 class LogStash::Inputs::Amqp < LogStash::Inputs::Base
   MQTYPES = [ "fanout", "direct", "topic" ]
 
   config_name "amqp"
 
-  # The host to connect to
+  # Your amqp server address
   config :host, :validate => :string, :required => true, :default => "localhost"
 
   # The AMQP port to connect on

lib/logstash/inputs/base.rb

@@ -12,6 +12,14 @@ class LogStash::Inputs::Base
   # Label this input with a type.
   config :type, :validate => :string, :required => true
 
+  # Set this to true to enable debugging on an input.
+  config :debug, :validate => :boolean, :default => false
+
+  # Add any number of arbitrary tags to your event.
+  #
+  # This can help with processing later.
+  # TODO(sissel): do we really care what the value of this field is?
+  #   can we just validate as an array of strings and call it done?
   config :tags, :validate => (lambda do |value|
     re = /^[A-Za-z0-9_]+$/
     value.each do |v|

lib/logstash/inputs/beanstalk.rb

@@ -2,20 +2,22 @@ require "logstash/inputs/base"
 require "logstash/namespace"
 require "beanstalk-client"
 
+# Pull events from a beanstalk tube.
+#
+# TODO(sissel): Document where to learn more about beanstalk.
 class LogStash::Inputs::Beanstalk < LogStash::Inputs::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
 
-  public
-  def initialize(params)
-    super
-
-    @port ||= 11300
-  end # def initialize
-
   public
   def register
     # TODO(petef): support pools of beanstalkd servers

lib/logstash/inputs/stdin.rb

@@ -2,6 +2,10 @@ require "logstash/inputs/base"
 require "logstash/namespace"
 require "socket" # for Socket.gethostname
 
+# Read events from standard input.
+#
+# By default, each event is assumed to be one line. If you
+# want to join lines, you'll want to use the multiline filter.
 class LogStash::Inputs::Stdin < LogStash::Inputs::Base
 
   config_name "stdin"

lib/logstash/inputs/stomp.rb

@@ -1,26 +1,34 @@
 require "logstash/inputs/base"
 require "logstash/namespace"
 
-# TODO(sissel): This class doesn't work yet in JRuby. Haven't debugged it much.
+# TODO(sissel): This class doesn't work yet in JRuby. Google for
+# 'execution expired stomp jruby' and you'll find the ticket.
 
+# Stream events from a STOMP broker.
+#
+# TODO(sissel): Include info on where to learn about STOMP
 class LogStash::Inputs::Stomp < LogStash::Inputs::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.
+  #
+  # Example: "/topic/logstash"
   config :destination, :validate => :string
-  config :debug, :validate => :boolean
 
-  public
-  def initialize(params)
-    super
-
-    @debug ||= false
-    @port ||= 61613
-    @user ||= ''
-    @password ||= ''
-  end # def initialize
+  # Enable debugging output?
+  config :debug, :validate => :boolean, :default => false
 
   public
   def register

lib/logstash/inputs/syslog.rb

@@ -4,21 +4,20 @@ require "logstash/namespace"
 require "logstash/time" # should really use the filters/date.rb bits
 require "socket"
 
+# Read syslog messages as events over the network.
+#
+# This input is a good choice if you already use syslog today.
+# It is also a good choice if you want to receive logs from
+# appliances and network devices where you cannot run your own
+# log collector.
 class LogStash::Inputs::Syslog < LogStash::Inputs::Base
-
   config_name "syslog"
 
-  # TCP listen configuration
-  config :host, :validate => :string
-  config :port, :validate => :number
+  # The address to listen on
+  config :host, :validate => :string, :default => "0.0.0.0"
 
-  public
-  def initialize(params)
-    super
-
-    @host ||= "0.0.0.0"
-    @port ||= 514
-  end
+  # The port to listen on
+  config :port, :validate => :number, :default => 514
 
   public
   def register

lib/logstash/inputs/tcp.rb

@@ -3,21 +3,23 @@ require "logstash/namespace"
 require "socket"
 require "timeout"
 
+# Read events over a TCP socket.
+#
+# Like stdin and file inputs, each event is assumed to be one line of text.
 class LogStash::Inputs::Tcp < LogStash::Inputs::Base
 
   config_name "tcp"
 
-  config :host, :validate => :string
+  # The address to listen on
+  config :host, :validate => :string, :default => "0.0.0.0"
+  
+  # the port to listen on
   config :port, :validate => :number, :required => true
-  config :data_timeout, :validate => :number
 
-  public
-  def initialize(params)
-    super
-
-    @host ||= "0.0.0.0"
-    @data_timeout ||= 5
-  end
+  # Read timeout in seconds. If a particular tcp connection is
+  # idle for more than this timeout period, we will assume 
+  # it is dead and close it.
+  config :data_timeout, :validate => :number, :default => 5
 
   public
   def register
@@ -38,6 +40,7 @@ class LogStash::Inputs::Tcp < LogStash::Inputs::Base
             buf = nil
             # NOTE(petef): the timeout only hits after the line is read
             # or socket dies
+            # TODO(sissel): Why do we have a timeout here? What's the point?
             Timeout::timeout(@data_timeout) do
               buf = s.readline
             end

lib/logstash/inputs/twitter.rb

@@ -7,16 +7,9 @@ class LogStash::Inputs::Twitter < LogStash::Inputs::Base
   config_name "twitter"
   config :user, :validate => :string, :required => true
   config :password, :validate => :password, :required => true
-  config :debug, :validate => :boolean
 
   config :keywords, :validate => :array, :required => true
 
-  public
-  def initialize(params)
-    super
-    @debug ||= false
-  end # def initialize
-
   def register
     # nothing to do
   end