Merge branch 'master' into 1.4.x

* master:
  correct email config hash options
  minor updates, submitting two PRs as one
  put the pencil to graphite
  touch up email doc

lib/logstash/outputs/email.rb

@@ -2,100 +2,104 @@
 require "logstash/outputs/base"
 require "logstash/namespace"
 
-# Send email when any event is received.
+# Send email when an output is received. Alternatively, you may include or
+# exclude the email output execution using conditionals. 
 class LogStash::Outputs::Email < LogStash::Outputs::Base
 
   config_name "email"
   milestone 1
 
-  # This setting is deprecated in favor of logstash's "conditionals" feature
+  # This setting is deprecated in favor of Logstash's "conditionals" feature
   # If you were using this setting previously, please use conditionals instead.
   #
   # If you need help converting your older 'match' setting to a conditional,
   # I welcome you to join the #logstash irc channel on freenode or to email
   # the [email protected] mailling list and ask for help! :)
   config :match, :validate => :hash, :deprecated => true
 
-  # Who to send this email to?
-  # A fully qualified email address to send to
+  # The fully-qualified email address to send the email to.
   #
-  # This field also accept a comma separated list of emails like 
+  # This field also accepts a comma-separated string of addresses, for example: 
   # "[email protected], [email protected]"
   #
-  # You can also use dynamic field from the event with the %{fieldname} syntax.
+  # You can also use dynamic fields from the event with the %{fieldname} syntax.
   config :to, :validate => :string, :required => true
 
-  # The From setting for email - fully qualified email address for the From:
+  # The fully-qualified email address for the From: field in the email.
   config :from, :validate => :string, :default => "[email protected]"
 
-  # The Reply-To setting for email - fully qualified email address is required
-  # here.
+  # The fully qualified email address for the Reply-To: field.
   config :replyto, :validate => :string
 
-  # Who to CC on this email?
+  # The fully-qualified email address(es) to include as cc: address(es).
   #
-  # See "to" setting for what is valid here.
+  # This field also accepts a comma-separated string of addresses, for example: 
+  # "[email protected], [email protected]"
   config :cc, :validate => :string
 
-  # how to send email: either smtp or sendmail - default to 'smtp'
+  # How Logstash should send the email, either via SMTP or by invoking sendmail.
   config :via, :validate => :string, :default => "smtp"
 
-  # the options to use:
-  # smtp: address, port, enable_starttls_auto, user_name, password, authentication(bool), domain
-  # sendmail: location, arguments
-  # If you do not specify anything, you will get the following equivalent code set in
+  # Specify the options to use:
+  #
+  # Via SMTP: smtpIporHost, port, domain, userName, password, authenticationType, starttls
+  #
+  # Via sendmail: location, arguments
+  #
+  # If you do not specify any `options`, you will get the following equivalent code set in
   # every new mail object:
   #
-  #   Mail.defaults do
-  #     delivery_method :smtp, { :address              => "localhost",
-  #                              :port                 => 25,
-  #                              :domain               => 'localhost.localdomain',
-  #                              :user_name            => nil,
-  #                              :password             => nil,
-  #                              :authentication       => nil,(plain, login and cram_md5)
-  #                              :enable_starttls_auto => true  }
+  #     Mail.defaults do
+  #       delivery_method :smtp, { :smtpIporHost         => "localhost",
+  #                                :port                 => 25,
+  #                                :domain               => 'localhost.localdomain',
+  #                                :userName             => nil,
+  #                                :password             => nil,
+  #                                :authenticationType   => nil,(plain, login and cram_md5)
+  #                                :starttls             => true  }
   #
-  #     retriever_method :pop3, { :address             => "localhost",
-  #                               :port                => 995,
-  #                               :user_name           => nil,
-  #                               :password            => nil,
-  #                               :enable_ssl          => true }
-  #   end
+  #       retriever_method :pop3, { :address             => "localhost",
+  #                                 :port                => 995,
+  #                                 :user_name           => nil,
+  #                                 :password            => nil,
+  #                                 :enable_ssl          => true }
   #
-  #   Mail.delivery_method.new  #=> Mail::SMTP instance
-  #   Mail.retriever_method.new #=> Mail::POP3 instance
+  #       Mail.delivery_method.new  #=> Mail::SMTP instance
+  #       Mail.retriever_method.new #=> Mail::POP3 instance
+  #     end
   #
-  # Each mail object inherits the default set in Mail.delivery_method, however, on
+  # Each mail object inherits the defaults set in Mail.delivery_method. However, on
   # a per email basis, you can override the method:
   #
-  #   mail.delivery_method :sendmail
+  #     mail.delivery_method :sendmail
   #
   # Or you can override the method and pass in settings:
   #
-  #   mail.delivery_method :sendmail, { :address => 'some.host' }
+  #     mail.delivery_method :sendmail, { :address => 'some.host' }
   #
   # You can also just modify the settings:
   #
-  #   mail.delivery_settings = { :address => 'some.host' }
+  #     mail.delivery_settings = { :address => 'some.host' }
   #
-  # The passed in hash is just merged against the defaults with +merge!+ and the result
-  # assigned the mail object.  So the above example will change only the :address value
-  # of the global smtp_settings to be 'some.host', keeping all other values
+  # The hash you supply is just merged against the defaults with "merge!" and the result
+  # assigned to the mail object.  For instance, the above example will change only the
+  # `:address` value of the global `smtp_settings` to be 'some.host', retaining all other values.
   config :options, :validate => :hash, :default => {}
 
-  # subject for email
+  # Subject: for the email.
   config :subject, :validate => :string, :default => ""
 
-  # body for email - just plain text
+  # Body for the email - plain text only.
   config :body, :validate => :string, :default => ""
 
-  # body for email - can contain html markup
+  # HTML Body for the email, which may contain HTML markup.
   config :htmlbody, :validate => :string, :default => ""
 
-  # attachments - has of name of file and file location
+  # Attachments - specify the name(s) and location(s) of the files.
   config :attachments, :validate => :array, :default => []
 
-  # contenttype : for multipart messages, set the content type and/or charset of the html part
+  # contenttype : for multipart messages, set the content-type and/or charset of the HTML part.
+  # NOTE: this may not be functional (KH)
   config :contenttype, :validate => :string, :default => "text/html; charset=UTF-8"
 
   public

lib/logstash/outputs/graphite.rb

@@ -4,11 +4,11 @@
 require "socket"
 
 # This output allows you to pull metrics from your logs and ship them to
-# graphite. Graphite is an open source tool for storing and graphing metrics.
+# Graphite. Graphite is an open source tool for storing and graphing metrics.
 #
-# An example use case: At loggly, some of our applications emit aggregated
-# stats in the logs every 10 seconds. Using the grok filter and this output,
-# I can capture the metric values from the logs and emit them to graphite.
+# An example use case: Some applications emit aggregated stats in the logs
+# every 10 seconds. Using the grok filter and this output, it is possible to
+# capture the metric values from the logs and emit them to Graphite.
 class LogStash::Outputs::Graphite < LogStash::Outputs::Base
   config_name "graphite"
   milestone 2
@@ -18,46 +18,49 @@ class LogStash::Outputs::Graphite < LogStash::Outputs::Base
   DEFAULT_METRICS_FORMAT = "*"
   METRIC_PLACEHOLDER = "*"
 
-  # The address of the graphite server.
+  # The hostname or IP address of the Graphite server.
   config :host, :validate => :string, :default => "localhost"
 
-  # The port to connect on your graphite server.
+  # The port to connect to on the Graphite server.
   config :port, :validate => :number, :default => 2003
 
-  # Interval between reconnect attempts to Carbon
+  # Interval between reconnect attempts to Carbon.
   config :reconnect_interval, :validate => :number, :default => 2
 
-  # Should metrics be resend on failure?
+  # Should metrics be resent on failure?
   config :resend_on_failure, :validate => :boolean, :default => false
 
   # The metric(s) to use. This supports dynamic strings like %{host}
   # for metric names and also for values. This is a hash field with key 
-  # of the metric name, value of the metric value. Example:
+  # being the metric name, value being the metric value. Example:
   #
   #     [ "%{host}/uptime", "%{uptime_1m}" ]
   #
   # The value will be coerced to a floating point value. Values which cannot be
-  # coerced will zero (0)
+  # coerced will be set to zero (0). You may use either `metrics` or `fields_are_metrics`,
+  # but not both.
   config :metrics, :validate => :hash, :default => {}
 
-  # Indicate that the event @fields should be treated as metrics and will be sent as is to graphite
+  # An array indicating that these event fields should be treated as metrics
+  # and will be sent verbatim to Graphite. You may use either `fields_are_metrics`
+  # or `metrics`, but not both.
   config :fields_are_metrics, :validate => :boolean, :default => false
 
-  # Include only regex matched metric names
+  # Include only regex matched metric names.
   config :include_metrics, :validate => :array, :default => [ ".*" ]
 
-  # Exclude regex matched metric names, by default exclude unresolved %{field} strings
+  # Exclude regex matched metric names, by default exclude unresolved %{field} strings.
   config :exclude_metrics, :validate => :array, :default => [ "%\{[^}]+\}" ]
 
-  # Enable debug output
+  # Enable debug output.
   config :debug, :validate => :boolean, :default => false, :deprecated => "This setting was never used by this plugin. It will be removed soon."
 
-  # Defines format of the metric string. The placeholder '*' will be
+  # Defines the format of the metric string. The placeholder '*' will be
   # replaced with the name of the actual metric.
   #
   #     metrics_format => "foo.bar.*.sum"
   #
-  # NOTE: If no metrics_format is defined the name of the metric will be used as fallback.
+  # NOTE: If no metrics_format is defined, the name of the metric will be used as fallback.
   config :metrics_format, :validate => :string, :default => DEFAULT_METRICS_FORMAT
 
   def register
@@ -74,7 +77,7 @@ def register
   end # def register
 
   def connect
-    # TODO(sissel): Test error cases. Catch exceptions. Find fortune and glory.
+    # TODO(sissel): Test error cases. Catch exceptions. Find fortune and glory. Retire to yak farm.
     begin
       @socket = TCPSocket.new(@host, @port)
     rescue Errno::ECONNREFUSED => e
@@ -121,7 +124,7 @@ def receive(event)
     end
 
     if messages.empty?
-      @logger.debug("Message is empty, not sending anything to graphite", :messages => messages, :host => @host, :port => @port)
+      @logger.debug("Message is empty, not sending anything to Graphite", :messages => messages, :host => @host, :port => @port)
     else
       message = messages.join("\n")
       @logger.debug("Sending carbon messages", :messages => messages, :host => @host, :port => @port)