elasticsearch input

lib/logstash/inputs/elasticsearch.rb

@@ -3,49 +3,52 @@
 require "logstash/namespace"
 require "logstash/util/socket_peer"
 
-# Read from elasticsearch.
-#
-# This is useful for replay testing logs, reindexing, etc.
+# Read from an Elasticsearch cluster, based on search query results.
+# This is useful for replaying test logs, reindexing, etc.
 #
 # Example:
 #
 #     input {
-#       # Read all documents from elasticsearch matching the given query
+#       # Read all documents from Elasticsearch matching the given query
 #       elasticsearch {
 #         host => "localhost"
 #         query => "ERROR"
 #       }
 #     }
 #
-# * TODO(sissel): configurable scroll timeout
+# This would create an Elasticsearch query with the following format:
+#
+#     http://localhost:9200/logstash-*/_search?q=ERROR&scroll=1m&size=1000
+#
 # * TODO(sissel): Option to keep the index, type, and doc id so we can do reindexing?
 class LogStash::Inputs::Elasticsearch < LogStash::Inputs::Base
   config_name "elasticsearch"
   milestone 1
 
   default :codec, "json"
 
-  # The address of your elasticsearch server
+  # The IP address or hostname of your Elasticsearch server.
   config :host, :validate => :string, :required => true
 
-  # The http port of your elasticsearch server's REST interface
+  # The HTTP port of your Elasticsearch server's REST interface.
   config :port, :validate => :number, :default => 9200
 
-  # The index to search
+  # The index or alias to search.
   config :index, :validate => :string, :default => "logstash-*"
 
-  # The query to use
+  # The query to be executed.
   config :query, :validate => :string, :default => "*"
 
-  # Enable the scan search_type.
-  # This will disable sorting but increase speed and performance.
+  # Enable the Elasticsearch "scan" search type.  This will disable
+  # sorting but increase speed and performance.
   config :scan, :validate => :boolean, :default => true
 
-  # This allows you to set the number of items you get back per scroll
+  # This allows you to set the maximum number of hits returned per scroll.
   config :size, :validate => :number, :default => 1000
 
-  # this parameter controls the keep alive time of the scrolling request and initiates the scrolling process.
-  # The timeout applies per round trip (i.e. between the previous scan scroll request, to the next).
+  # This parameter controls the keepalive time in seconds of the scrolling
+  # request and initiates the scrolling process. The timeout applies per
+  # round trip (i.e. between the previous scan scroll request, to the next).
   config :scroll, :validate => :string, :default => "1m"
 
   public