sensu 0.17.0.beta → 0.17.0.beta.1

data/lib/sensu/client/socket.rb

@@ -0,0 +1,226 @@
+require "multi_json"
+
+module Sensu
+  module Client
+    # EventMachine connection handler for the Sensu client"s socket.
+    #
+    # The Sensu client listens on localhost, port 3030 (by default), for
+    # UDP and TCP traffic. This allows software running on the host to
+    # push check results (that may contain metrics) into Sensu, without
+    # needing to know anything about Sensu"s internal implementation.
+    #
+    # The socket only accepts 7-bit ASCII-encoded data.
+    #
+    # Although the Sensu client accepts UDP and TCP traffic, you must be
+    # aware of the UDP protocol limitations. Any data you send over UDP
+    # must fit in a single datagram and you will not receive a response
+    # (no confirmation).
+    #
+    # == UDP Protocol ==
+    #
+    # If the socket receives a message containing whitespace and the
+    # string +"ping"+, it will ignore it.
+    #
+    # The socket assumes all other messages will contain a single,
+    # complete, JSON hash. The hash must be a valid JSON check result.
+    # Deserialization failures will be logged at the ERROR level by the
+    # Sensu client, but the sender of the invalid data will not be
+    # notified.
+    #
+    # == TCP Protocol ==
+    #
+    # If the socket receives a message containing whitespace and the
+    # string +"ping"+, it will respond with the message +"pong"+.
+    #
+    # The socket assumes any other stream will be a single, complete,
+    # JSON hash. A deserialization failure will be logged at the WARN
+    # level by the Sensu client and respond with the message
+    # +"invalid"+. An +"ok"+ response indicates the Sensu client
+    # successfully received the JSON hash and will publish the check
+    # result.
+    #
+    # Streams can be of any length. The socket protocol does not require
+    # any headers, instead the socket tries to parse everything it has
+    # been sent each time a chunk of data arrives. Once the JSON parses
+    # successfully, the Sensu client publishes the result. After
+    # +WATCHDOG_DELAY+ (default is 500 msec) since the most recent chunk
+    # of data was received, the agent will give up on the sender, and
+    # instead respond +"invalid"+ and close the connection.
+    class Socket < EM::Connection
+      class DataError < StandardError; end
+
+      attr_accessor :logger, :settings, :transport, :protocol
+
+      # The number of seconds that may elapse between chunks of data
+      # from a sender before it is considered dead, and the connection
+      # is close.
+      WATCHDOG_DELAY = 0.5
+
+      #
+      # Sensu::Socket operating mode enum.
+      #
+
+      # ACCEPT mode. Append chunks of data to a buffer and test to see
+      # whether the buffer contents are valid JSON.
+      MODE_ACCEPT = :ACCEPT
+
+      # REJECT mode. No longer receiving data from sender. Discard
+      # chunks of data in this mode, the connection is being closed.
+      MODE_REJECT = :REJECT
+
+      # Initialize instance variables that will be used throughout the
+      # lifetime of the connection. This method is called when the
+      # network connection has been established, and immediately after
+      # responding to a sender.
+      def post_init
+        @protocol ||= :tcp
+        @data_buffer = ""
+        @parse_error = nil
+        @watchdog = nil
+        @mode = MODE_ACCEPT
+      end
+
+      # Send a response to the sender, close the
+      # connection, and call post_init().
+      #
+      # @param [String] data to send as a response.
+      def respond(data)
+        if @protocol == :tcp
+          send_data(data)
+          close_connection_after_writing
+        end
+        post_init
+      end
+
+      # Cancel the current connection watchdog.
+      def cancel_watchdog
+        if @watchdog
+          @watchdog.cancel
+        end
+      end
+
+      # Reset (or start) the connection watchdog.
+      def reset_watchdog
+        cancel_watchdog
+        @watchdog = EM::Timer.new(WATCHDOG_DELAY) do
+          @mode = MODE_REJECT
+          @logger.warn("discarding data buffer for sender and closing connection", {
+            :data => @data_buffer,
+            :parse_error => @parse_error
+          })
+          respond("invalid")
+        end
+      end
+
+      # Validate check result attributes.
+      #
+      # @param [Hash] check result to validate.
+      def validate_check_result(check)
+        unless check[:name] =~ /^[\w\.-]+$/
+          raise DataError, "check name must be a string and cannot contain spaces or special characters"
+        end
+        unless check[:output].is_a?(String)
+          raise DataError, "check output must be a string"
+        end
+        unless check[:status].is_a?(Integer)
+          raise DataError, "check status must be an integer"
+        end
+      end
+
+      # Publish a check result to the Sensu transport.
+      #
+      # @param [Hash] check result.
+      def publish_check_result(check)
+        payload = {
+          :client => @settings[:client][:name],
+          :check => check.merge(:issued => Time.now.to_i)
+        }
+        @logger.info("publishing check result", {
+          :payload => payload
+        })
+        @transport.publish(:direct, "results", MultiJson.dump(payload))
+      end
+
+      # Process a check result. Set check result attribute defaults,
+      # validate the attributes, publish the check result to the Sensu
+      # transport, and respond to the sender with the message +"ok"+.
+      #
+      # @param [Hash] check result to be validated and published.
+      # @raise [DataError] if +check+ is invalid.
+      def process_check_result(check)
+        check[:status] ||= 0
+        validate_check_result(check)
+        publish_check_result(check)
+        respond("ok")
+      end
+
+      # Parse a JSON check result. For UDP, immediately raise a parser
+      # error. For TCP, record parser errors, so the connection
+      # +watchdog+ can report them.
+      #
+      # @param [String] data to parse for a check result.
+      def parse_check_result(data)
+        begin
+          check = MultiJson.load(data)
+          cancel_watchdog
+          process_check_result(check)
+        rescue MultiJson::ParseError, ArgumentError => error
+          if @protocol == :tcp
+            @parse_error = error.to_s
+          else
+            raise error
+          end
+        end
+      end
+
+      # Process the data received. This method validates the data
+      # encoding, provides ping/pong functionality, and passes potential
+      # check results on for further processing.
+      #
+      # @param [String] data to be processed.
+      def process_data(data)
+        if data.bytes.find { |char| char > 0x80 }
+          @logger.warn("socket received non-ascii characters")
+          respond("invalid")
+        elsif data.strip == "ping"
+          @logger.debug("socket received ping")
+          respond("pong")
+        else
+          @logger.debug("socket received data", {
+            :data => data
+          })
+          begin
+            parse_check_result(data)
+          rescue => error
+            @logger.error("failed to process check result from socket", {
+              :data => data,
+              :error => error.to_s
+            })
+            respond("invalid")
+          end
+        end
+      end
+
+      # This method is called whenever data is received. For UDP, it
+      # will only be called once, the original data length can be
+      # expected. For TCP, this method may be called several times, data
+      # received is buffered. TCP connections require a +watchdog+.
+      #
+      # @param [String] data received from the sender.
+      def receive_data(data)
+        unless @mode == MODE_REJECT
+          case @protocol
+          when :udp
+            process_data(data)
+          when :tcp
+            if EM.reactor_running?
+              reset_watchdog
+            end
+            @data_buffer << data
+            process_data(@data_buffer)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sensu/constants.rb

@@ -1,9 +1,12 @@
 module Sensu
   unless defined?(Sensu::VERSION)
-    VERSION = '0.17.0.beta'
+    # Sensu release version.
+    VERSION = "0.17.0.beta.1"
 
+    # Sensu check severities.
     SEVERITIES = %w[ok warning critical unknown]
 
+    # Process signals that trigger a Sensu process stop.
     STOP_SIGNALS = %w[INT TERM]
   end
 end

data/lib/sensu/daemon.rb

@@ -1,53 +1,69 @@
-require 'rubygems'
+require "rubygems"
 
-gem 'multi_json', '1.10.1'
+gem "multi_json", "1.10.1"
+gem "eventmachine", "1.0.3"
 
-gem 'sensu-em', '2.4.1'
-gem 'sensu-logger', '1.0.0'
-gem 'sensu-settings', '1.2.0'
-gem 'sensu-extension', '1.0.0'
-gem 'sensu-extensions', '1.0.0'
-gem 'sensu-transport', '2.4.0'
-gem 'sensu-spawn', '1.1.0'
+gem "sensu-em", "2.4.1"
+gem "sensu-logger", "1.0.0"
+gem "sensu-settings", "1.2.0"
+gem "sensu-extension", "1.1.2"
+gem "sensu-extensions", "1.1.0"
+gem "sensu-transport", "2.4.0"
+gem "sensu-spawn", "1.1.0"
 
-require 'time'
-require 'uri'
+require "time"
+require "uri"
 
-require 'sensu/logger'
-require 'sensu/settings'
-require 'sensu/extensions'
-require 'sensu/transport'
-require 'sensu/spawn'
+require "sensu/logger"
+require "sensu/settings"
+require "sensu/extensions"
+require "sensu/transport"
+require "sensu/spawn"
 
-require 'sensu/constants'
-require 'sensu/utilities'
-require 'sensu/cli'
-require 'sensu/redis'
+require "sensu/constants"
+require "sensu/utilities"
+require "sensu/cli"
+require "sensu/redis"
 
+# Symbolize hash keys when parsing JSON.
 MultiJson.load_options = {:symbolize_keys => true}
 
 module Sensu
   module Daemon
     include Utilities
 
-    attr_reader :state
-
+    # Initialize the Sensu process. Set the initial service state, set
+    # up the logger, load settings, load extensions, and optionally
+    # daemonize the process and/or create a PID file. A subclass may
+    # override this method.
+    #
+    # @param options [Hash]
     def initialize(options={})
       @state = :initializing
-      @timers = {
-        :run => Array.new
-      }
+      @timers = {:run => []}
       setup_logger(options)
       load_settings(options)
       load_extensions(options)
       setup_process(options)
     end
 
+    # Set up the Sensu logger and its process signal traps for log
+    # rotation and debug log level toggling. This method creates the
+    # logger instance variable: `@logger`.
+    #
+    # https://github.com/sensu/sensu-logger
+    #
+    # @param options [Hash]
     def setup_logger(options={})
       @logger = Logger.get(options)
       @logger.setup_signal_traps
     end
 
+    # Log setting or extension loading concerns, sensitive information
+    # is redacted.
+    #
+    # @param concerns [Array] to be logged.
+    # @param level [Symbol] to log the concerns at.
     def log_concerns(concerns=[], level=:warn)
       concerns.each do |concern|
         message = concern.delete(:message)
@@ -55,18 +71,34 @@ module Sensu
       end
     end
 
+    # Load Sensu settings and validate them. If there are validation
+    # failures, log them (concerns), then cause the Sensu process to
+    # exit (2). This method creates the settings instance variable:
+    # `@settings`.
+    #
+    # https://github.com/sensu/sensu-settings
+    #
+    # @param options [Hash]
     def load_settings(options={})
       @settings = Settings.get(options)
       log_concerns(@settings.warnings)
       failures = @settings.validate
       unless failures.empty?
-        @logger.fatal('invalid settings')
+        @logger.fatal("invalid settings")
         log_concerns(failures, :fatal)
-        @logger.fatal('SENSU NOT RUNNING!')
+        @logger.fatal("SENSU NOT RUNNING!")
         exit 2
       end
     end
 
+    # Load Sensu extensions and log any concerns. Set the logger and
+    # settings for each extension instance. This method creates the
+    # extensions instance variable: `@extensions`.
+    #
+    # https://github.com/sensu/sensu-extensions
+    # https://github.com/sensu/sensu-extension
+    #
+    # @param options [Hash]
     def load_extensions(options={})
       @extensions = Extensions.get(options)
       log_concerns(@extensions.warnings)
@@ -77,35 +109,49 @@ module Sensu
       end
     end
 
+    # Manage the current process, optionally daemonize and/or write
+    # the current process ID to a PID file.
+    #
+    # @param options [Hash]
     def setup_process(options)
-      if options[:daemonize]
-        daemonize
-      end
-      if options[:pid_file]
-        write_pid(options[:pid_file])
-      end
+      daemonize if options[:daemonize]
+      write_pid(options[:pid_file]) if options[:pid_file]
     end
 
+    # Start the Sensu service and set the service state to `:running`.
+    # This method will likely be overridden by a subclass.
     def start
       @state = :running
     end
 
+    # Pause the Sensu service and set the service state to `:paused`.
+    # This method will likely be overridden by a subclass.
     def pause
       @state = :paused
     end
 
+    # Resume the paused Sensu service and set the service state to
+    # `:running`. This method will likely be overridden by a subclass.
     def resume
       @state = :running
     end
 
+    # Stop the Sensu service and set the service state to `:stopped`.
+    # This method will likely be overridden by a subclass. This method
+    # should stop the EventMachine event loop.
     def stop
       @state = :stopped
-      @logger.warn('stopping reactor')
+      @logger.warn("stopping reactor")
       EM::stop_event_loop
     end
 
+    # Set up process signal traps. This method uses the `STOP_SIGNALS`
+    # constant to determine which process signals will result in a
+    # graceful service stop. A periodic timer must be used to poll for
+    # received signals, as Mutex#lock cannot be used within the
+    # context of `trap()`.
     def setup_signal_traps
-      @signals = Array.new
+      @signals = []
       STOP_SIGNALS.each do |signal|
         Signal.trap(signal) do
           @signals << signal
@@ -114,103 +160,109 @@ module Sensu
       EM::PeriodicTimer.new(1) do
         signal = @signals.shift
         if STOP_SIGNALS.include?(signal)
-          @logger.warn('received signal', {
-            :signal => signal
-          })
+          @logger.warn("received signal", :signal => signal)
           stop
         end
       end
     end
 
+    # Set up the Sensu transport connection. Sensu uses a transport
+    # API, allowing it to use various message brokers. By default,
+    # Sensu will use the built-in "rabbitmq" transport. The Sensu
+    # service will stop gracefully in the event of a transport error,
+    # and pause/resume in the event of connectivity issues. This
+    # method creates the transport instance variable: `@transport`.
+    #
+    # https://github.com/sensu/sensu-transport
     def setup_transport
-      transport_name = @settings[:transport][:name] || 'rabbitmq'
+      transport_name = @settings[:transport][:name] || "rabbitmq"
       transport_settings = @settings[transport_name]
-      @logger.debug('connecting to transport', {
+      @logger.debug("connecting to transport", {
         :name => transport_name,
         :settings => transport_settings
       })
       Transport.logger = @logger
       @transport = Transport.connect(transport_name, transport_settings)
       @transport.on_error do |error|
-        @logger.fatal('transport connection error', {
-          :error => error.to_s
-        })
+        @logger.fatal("transport connection error", :error => error.to_s)
         stop
       end
       @transport.before_reconnect do
         unless testing?
-          @logger.warn('reconnecting to transport')
+          @logger.warn("reconnecting to transport")
           pause
         end
       end
       @transport.after_reconnect do
-        @logger.info('reconnected to transport')
+        @logger.info("reconnected to transport")
         resume
       end
     end
 
+    # Set up the Redis connection. Sensu uses Redis as a data store,
+    # to store the client registry, current events, etc. The Sensu
+    # service will stop gracefully in the event of a Redis error, and
+    # pause/resume in the event of connectivity issues. This method
+    # creates the Redis instance variable: `@redis`.
     def setup_redis
-      @logger.debug('connecting to redis', {
-        :settings => @settings[:redis]
-      })
+      @logger.debug("connecting to redis", :settings => @settings[:redis])
       @redis = Redis.connect(@settings[:redis])
       @redis.on_error do |error|
-        @logger.fatal('redis connection error', {
-          :error => error.to_s
-        })
+        @logger.fatal("redis connection error", :error => error.to_s)
         stop
       end
       @redis.before_reconnect do
         unless testing?
-          @logger.warn('reconnecting to redis')
+          @logger.warn("reconnecting to redis")
           pause
         end
       end
       @redis.after_reconnect do
-        @logger.info('reconnected to redis')
+        @logger.info("reconnected to redis")
         resume
       end
     end
 
     private
 
+    # Write the current process ID (PID) to a file (PID file). This
+    # method will cause the Sensu service to exit (2) if the PID file
+    # cannot be written to.
+    #
+    # @param file [String] to write the current PID to.
     def write_pid(file)
       begin
-        File.open(file, 'w') do |pid_file|
+        File.open(file, "w") do |pid_file|
           pid_file.puts(Process.pid)
         end
       rescue
-        @logger.fatal('could not write to pid file', {
-          :pid_file => file
-        })
-        @logger.fatal('SENSU NOT RUNNING!')
+        @logger.fatal("could not write to pid file", :pid_file => file)
+        @logger.fatal("SENSU NOT RUNNING!")
         exit 2
       end
     end
 
+    # Daemonize the current process. Seed the random number generator,
+    # fork (& exit), detach from controlling terminal, ignore SIGHUP,
+    # fork (& exit), use root '/' as the current working directory,
+    # and close STDIN/OUT/ERR since the process is no longer attached
+    # to a terminal.
     def daemonize
       Kernel.srand
-      if Kernel.fork
-        exit
-      end
+      exit if Kernel.fork
       unless Process.setsid
-        @logger.fatal('cannot detach from controlling terminal')
-        @logger.fatal('SENSU NOT RUNNING!')
+        @logger.fatal("cannot detach from controlling terminal")
+        @logger.fatal("SENSU NOT RUNNING!")
         exit 2
       end
-      Signal.trap('SIGHUP', 'IGNORE')
-      if Kernel.fork
-        exit
-      end
-      Dir.chdir('/')
+      Signal.trap("SIGHUP", "IGNORE")
+      exit if Kernel.fork
+      Dir.chdir("/")
       ObjectSpace.each_object(IO) do |io|
         unless [STDIN, STDOUT, STDERR].include?(io)
           begin
-            unless io.closed?
-              io.close
-            end
-          rescue
-          end
+            io.close unless io.closed?
+          rescue; end
         end
       end
     end

data/lib/sensu/redis.rb

@@ -1,16 +1,21 @@
-gem 'em-redis-unified', '0.5.0'
+gem "em-redis-unified", "0.5.0"
 
-require 'em-redis'
+require "em-redis"
 
 module Sensu
   class Redis
+    # Connect to Redis and ensure that the Redis version is at least
+    # 1.3.14, in order to support certain commands.
+    #
+    # @param options [Hash]
+    # @return [Object] Redis connection object.
     def self.connect(options={})
-      options ||= Hash.new
+      options ||= {}
       connection = EM::Protocols::Redis.connect(options)
       connection.info do |info|
-        if info[:redis_version] < '1.3.14'
+        if info[:redis_version] < "1.3.14"
           klass = EM::Protocols::Redis::RedisError
-          message = 'redis version must be >= 2.0 RC 1'
+          message = "redis version must be >= 2.0 RC 1"
           connection.error(klass, message)
         end
       end