Add more examples and doc improvements

lib/logstash/filters/kv.rb

@@ -7,12 +7,21 @@ require "logstash/namespace"
 # For example, if you have a log message which contains 'ip=1.2.3.4
 # error=REFUSED', you can parse those automatically by doing:
 #
-#
 #     filter {
 #       kv { }
 #     }
 #
-# And you will get field 'ip' == "1.2.3.4" etc.
+# The above will result in a message of "ip=1.2.3.4 error=REFUSED" having
+# the fields:
+#
+# * ip: 1.2.3.4
+# * error: REFUSED
+#
+# This is great for postfix, iptables, and other types of logs that
+# tend towards 'key=value' syntax. 
+#
+# Further, this can often be used to parse query parameters like
+# 'foo=bar&baz=fizz' by setting the field_split to "&"
 class LogStash::Filters::KV < LogStash::Filters::Base
   config_name "kv"
   plugin_status "beta"
@@ -26,17 +35,35 @@ class LogStash::Filters::KV < LogStash::Filters::Base
   #
   # Example, to strip '<' '>' and ',' characters from values:
   # 
-  #     filter { kv { trim => "<>," } }
+  #     filter { 
+  #       kv { 
+  #         trim => "<>,"
+  #       }
+  #     }
   config :trim, :validate => :string
 
 
   # A string of characters to use as delimiters for parsing out key-value pairs.
   #
-  # Example, to split out the args from a string such as
+  # #### Example with URL Query Strings
+  #
+  # Example, to split out the args from a url query string such as
   # '?pin=12345~0&d=123&e=foo@bar.com&oq=bobo&ss=12345':
   #
-  # Default to space character for backward compatibility
-  #     filter { kv { field_split => "&?" } }
+  #     filter {
+  #       kv {
+  #         field_split => "&?" 
+  #       }
+  #     }
+  #
+  # The above splits on both "&" and "?" characters, giving you the following
+  # fields:
+  #
+  # * pin: 12345~0
+  # * d: 123
+  # * e: foo@bar.com
+  # * oq: bobo
+  # * ss: 12345
   config :field_split, :validate => :string, :default => ' '