union_station_hooks_core 1.0.0

data/lib/union_station_hooks_core/lock.rb

@@ -0,0 +1,62 @@
+#  Union Station - https://www.unionstationapp.com/
+#  Copyright (c) 2010-2015 Phusion Holding B.V.
+#
+#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+#  THE SOFTWARE.
+
+
+module UnionStationHooks
+  # A wrapper around a mutex, for use within Connection.
+  #
+  # @private
+  class Lock
+    def initialize(mutex)
+      @mutex = mutex
+      @locked = false
+    end
+
+    def reset(mutex, lock_now = true)
+      unlock if @locked
+      @mutex = mutex
+      lock if lock_now
+    end
+
+    def synchronize
+      lock if !@locked
+      begin
+        yield(self)
+      ensure
+        unlock if @locked
+      end
+    end
+
+    def lock
+      raise if @locked
+      @mutex.lock
+      @locked = true
+    end
+
+    def unlock
+      raise if !@locked
+      @mutex.unlock
+      @locked = false
+    end
+  end
+end

data/lib/union_station_hooks_core/log.rb

@@ -0,0 +1,66 @@
+#  Union Station - https://www.unionstationapp.com/
+#  Copyright (c) 2010-2015 Phusion Holding B.V.
+#
+#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+#  THE SOFTWARE.
+
+
+module UnionStationHooks
+  # Provides methods for `union_station_*` gems to log internal warnings and
+  # debugging messages. This module is *not* to be used by application
+  # developers for the purpose of logging information to Union Station.
+  #
+  # @private
+  module Log
+    @@debugging = false
+    @@warn_callback = nil
+    @@debug_callback = nil
+
+    def self.debugging=(value)
+      @@debugging = value
+    end
+
+    def self.warn(message)
+      if @@warn_callback
+        @@warn_callback.call(message)
+      else
+        STDERR.puts("[UnionStationHooks] #{message}")
+      end
+    end
+
+    def self.debug(message)
+      if @@debugging
+        if @@debug_callback
+          @@debug_callback.call(message)
+        else
+          STDERR.puts("[UnionStationHooks] #{message}")
+        end
+      end
+    end
+
+    def self.warn_callback=(cb)
+      @@warn_callback = cb
+    end
+
+    def self.debug_callback=(cb)
+      @@debug_callback = cb
+    end
+  end
+end

data/lib/union_station_hooks_core/message_channel.rb

@@ -0,0 +1,157 @@
+# encoding: binary
+#  Union Station - https://www.unionstationapp.com/
+#  Copyright (c) 2010-2015 Phusion Holding B.V.
+#
+#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+#  THE SOFTWARE.
+
+
+module UnionStationHooks
+  # This class allows reading and writing structured messages over
+  # I/O channels. This is the Ruby implementation of Passenger's
+  # src/cxx_supportlib/Utils/MessageIO.h; see that file for more information.
+  #
+  # @private
+  class MessageChannel
+    HEADER_SIZE = 2
+    DELIMITER = "\0"
+    DELIMITER_NAME = 'null byte'
+    UINT16_PACK_FORMAT = 'n'
+    UINT32_PACK_FORMAT = 'N'
+
+    class InvalidHashError < StandardError
+    end
+
+    # The wrapped IO object.
+    attr_accessor :io
+
+    # Create a new MessageChannel by wrapping the given IO object.
+    def initialize(io = nil)
+      @io = io
+      # Make it binary just in case.
+      @io.binmode if @io
+    end
+
+    # rubocop:disable Metrics/MethodLength, Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity, Metrics/AbcSize
+
+    # Read an array message from the underlying file descriptor.
+    # Returns the array message as an array, or nil when end-of-stream has
+    # been reached.
+    #
+    # Might raise SystemCallError, IOError or SocketError when something
+    # goes wrong.
+    def read
+      buffer = new_buffer
+      if !@io.read(HEADER_SIZE, buffer)
+        return nil
+      end
+      while buffer.size < HEADER_SIZE
+        tmp = @io.read(HEADER_SIZE - buffer.size)
+        if tmp.empty?
+          return nil
+        else
+          buffer << tmp
+        end
+      end
+
+      chunk_size = buffer.unpack(UINT16_PACK_FORMAT)[0]
+      if !@io.read(chunk_size, buffer)
+        return nil
+      end
+      while buffer.size < chunk_size
+        tmp = @io.read(chunk_size - buffer.size)
+        if tmp.empty?
+          return nil
+        else
+          buffer << tmp
+        end
+      end
+
+      message = []
+      offset = 0
+      delimiter_pos = buffer.index(DELIMITER, offset)
+      while !delimiter_pos.nil?
+        if delimiter_pos == 0
+          message << ''
+        else
+          message << buffer[offset..delimiter_pos - 1]
+        end
+        offset = delimiter_pos + 1
+        delimiter_pos = buffer.index(DELIMITER, offset)
+      end
+      message
+    rescue Errno::ECONNRESET
+      nil
+    end
+
+    # rubocop:enable Metrics/MethodLength, Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity, Metrics/AbcSize
+
+    # Send an array message, which consists of the given elements, over the
+    # underlying file descriptor. _name_ is the first element in the message,
+    # and _args_ are the other elements. These arguments will internally be
+    # converted to strings by calling to_s().
+    #
+    # Might raise SystemCallError, IOError or SocketError when something
+    # goes wrong.
+    def write(name, *args)
+      check_argument(name)
+      args.each do |arg|
+        check_argument(arg)
+      end
+
+      message = "#{name}#{DELIMITER}"
+      args.each do |arg|
+        message << arg.to_s << DELIMITER
+      end
+      @io.write([message.size].pack('n') << message)
+      @io.flush
+    end
+
+    # Send a scalar message over the underlying IO object.
+    #
+    # Might raise SystemCallError, IOError or SocketError when something
+    # goes wrong.
+    def write_scalar(data)
+      @io.write([data.size].pack('N') << data)
+      @io.flush
+    end
+
+  private
+
+    def check_argument(arg)
+      if arg.to_s.index(DELIMITER)
+        raise ArgumentError,
+          "Message name and arguments may not contain #{DELIMITER_NAME}"
+      end
+    end
+
+    if defined?(ByteString)
+      def new_buffer
+        ByteString.new
+      end
+    else
+      def new_buffer
+        ''
+      end
+    end
+  end
+end # module UnionStationHooks

data/lib/union_station_hooks_core/request_reporter.rb

@@ -0,0 +1,141 @@
+#  Union Station - https://www.unionstationapp.com/
+#  Copyright (c) 2010-2015 Phusion Holding B.V.
+#
+#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+#  THE SOFTWARE.
+
+UnionStationHooks.require_lib 'request_reporter/basics'
+UnionStationHooks.require_lib 'request_reporter/controllers'
+UnionStationHooks.require_lib 'request_reporter/view_rendering'
+UnionStationHooks.require_lib 'request_reporter/misc'
+
+module UnionStationHooks
+  # A RequestReporter object is used for logging request-specific information
+  # to Union Station. "Information" may include (and are not limited to):
+  #
+  #  * Web framework controller and action name.
+  #  * Exceptions raised during the request.
+  #  * Cache hits and misses.
+  #  * Database actions.
+  #
+  # A unique RequestReporter is created by Passenger at the beginning of every
+  # request (by calling {UnionStationHooks.begin_rack_request}). This object is
+  # closed at the end of the same request (after the Rack body object is
+  # closed).
+  #
+  # As an application developer, the RequestReporter is the main class
+  # that you will be interfacing with. See the {UnionStationHooks} module
+  # description for an example of how you can use RequestReporter.
+  #
+  # ## Obtaining a RequestReporter
+  #
+  # You are not supposed to create a RequestReporter object directly.
+  # You are supposed to obtain the RequestReporter object that Passenger creates
+  # for you. This is done through the `union_station_hooks` key in the Rack
+  # environment hash, as well as through the `:union_station_hooks` key in
+  # the current thread's object:
+  #
+  #     env['union_station_hooks']
+  #     # => RequestReporter object or nil
+  #
+  #     Thread.current[:union_station_hooks]
+  #     # => RequestReporter object or nil
+  #
+  # Note that Passenger may not have created such an object because of an
+  # error. At present, there are two error conditions that would cause a
+  # RequestReporter object not to be created. However, your code should take
+  # into account that in the future more error conditions may trigger this.
+  #
+  #  1. There is no transaction ID associated with the current request.
+  #     When Union Station support is enabled in Passenger, Passenger always
+  #     assigns a transaction ID. However, administrators can also
+  #     {https://www.phusionpassenger.com/library/admin/nginx/request_individual_processes.html
+  #     access Ruby processes directly} through process-private HTTP sockets,
+  #     bypassing Passenger's load balancing mechanism. In that case, no
+  #     transaction ID will be assigned.
+  #  2. An error occurred recently while sending data to the UstRouter, either
+  #     because the UstRouter crashed or because of some other kind of
+  #     communication error occurred. This error condition isn't cleared until
+  #     certain a timeout has passed.
+  #
+  #     The UstRouter is a Passenger process which runs locally and is
+  #     responsible for aggregating Union Station log data from multiple
+  #     processes, with the goal of sending the aggregate data over the network
+  #     to the Union Station service.
+  #
+  #     This kind of error is automatically recovered from after a certain
+  #     period of time.
+  #
+  # ## Null mode
+  #
+  # The error condition 2 described above may also cause an existing
+  # RequestReporter object to enter the "null mode". When this mode is entered,
+  # any further actions on the RequestReporter object will become no-ops.
+  # You can check whether the null mode is active by calling {#null?}.
+  #
+  # Closing a RequestReporter also causes it to enter the null mode.
+  class RequestReporter
+    # Returns a new RequestReporter object. You should not call
+    # `RequestReporter.new` directly. See "Obtaining a RequestReporter"
+    # in the {RequestReporter class description}.
+    #
+    # @api private
+    def initialize(context, txn_id, app_group_name, key)
+      raise ArgumentError, 'Transaction ID must be given' if txn_id.nil?
+      raise ArgumentError, 'App group name must be given' if app_group_name.nil?
+      raise ArgumentError, 'Union Station key must be given' if key.nil?
+      @context = context
+      @txn_id = txn_id
+      @app_group_name = app_group_name
+      @key = key
+      @transaction = continue_transaction
+    end
+
+    # Indicates that no further information will be logged for this
+    # request.
+    #
+    # @api private
+    def close
+      @transaction.close
+    end
+
+    # Returns whether is this RequestReporter object is in null mode.
+    # See the {RequestReporter class description} for more information.
+    def null?
+      @transaction.null?
+    end
+
+    # Other methods are implemented in the files in the
+    # 'request_reporter/' subdirectory.
+
+  private
+
+    def continue_transaction
+      @context.continue_transaction(@txn_id, @app_group_name,
+        :requests, @key)
+    end
+
+    # Called when one of the methods return early upon detecting null
+    # mode. Used by tests to verify that methods return early.
+    def do_nothing_on_null(_source)
+      # Do nothing by default. Tests will stub this.
+    end
+  end
+end

data/lib/union_station_hooks_core/request_reporter/basics.rb

@@ -0,0 +1,132 @@
+#  Union Station - https://www.unionstationapp.com/
+#  Copyright (c) 2010-2015 Phusion Holding B.V.
+#
+#  "Union Station" and "Passenger" are trademarks of Phusion Holding B.V.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in
+#  all copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+#  THE SOFTWARE.
+
+require 'thread'
+
+module UnionStationHooks
+  class RequestReporter
+    ###### Logging basic request information ######
+
+    # A mutex for synchronizing GC stats reporting. We do this because in
+    # multithreaded situations we don't want to interleave GC stats access with
+    # calls to `GC.clear_stats`. Not that GC stats are very helpful in
+    # multithreaded situations, but this is better than nothing.
+    #
+    # @private
+    GC_MUTEX = Mutex.new
+
+    # @private
+    OBJECT_SPACE_SUPPORTS_LIVE_OBJECTS = ObjectSpace.respond_to?(:live_objects)
+
+    # @private
+    OBJECT_SPACE_SUPPORTS_ALLOCATED_OBJECTS =
+      ObjectSpace.respond_to?(:allocated_objects)
+
+    # @private
+    OBJECT_SPACE_SUPPORTS_COUNT_OBJECTS =
+      ObjectSpace.respond_to?(:count_objects)
+
+    # @private
+    GC_SUPPORTS_TIME = GC.respond_to?(:time)
+
+    # @private
+    GC_SUPPORTS_CLEAR_STATS = GC.respond_to?(:clear_stats)
+
+    # Log the beginning of a Rack request. This is automatically called
+    # from {UnionStationHooks.begin_rack_request} (and thus automatically
+    # from Passenger).
+    #
+    # @private
+    def log_request_begin
+      return do_nothing_on_null(:log_request_begin) if null?
+      @transaction.log_activity_begin('app request handler processing')
+    end
+
+    # Log the end of a Rack request. This is automatically called
+    # from {UnionStationHooks.begin_rack_request} (and thus automatically
+    # from Passenger).
+    #
+    # @private
+    def log_request_end(uncaught_exception_raised_during_request = false)
+      return do_nothing_on_null(:log_request_end) if null?
+      @transaction.log_activity_end('app request handler processing',
+        UnionStationHooks.now, uncaught_exception_raised_during_request)
+    end
+
+    # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+
+    # @private
+    def log_gc_stats_on_request_begin
+      return do_nothing_on_null(:log_gc_stats_on_request_begin) if null?
+
+      # See the docs for MUTEX on why we synchronize this.
+      GC_MUTEX.synchronize do
+        if OBJECT_SPACE_SUPPORTS_LIVE_OBJECTS
+          @transaction.message('Initial objects on heap: ' \
+            "#{ObjectSpace.live_objects}")
+        end
+        if OBJECT_SPACE_SUPPORTS_ALLOCATED_OBJECTS
+          @transaction.message('Initial objects allocated so far: ' \
+            "#{ObjectSpace.allocated_objects}")
+        elsif OBJECT_SPACE_SUPPORTS_COUNT_OBJECTS
+          count = ObjectSpace.count_objects
+          @transaction.message('Initial objects allocated so far: ' \
+            "#{count[:TOTAL] - count[:FREE]}")
+        end
+        if GC_SUPPORTS_TIME
+          @transaction.message("Initial GC time: #{GC.time}")
+        end
+      end
+    end
+
+    # @private
+    def log_gc_stats_on_request_end
+      return do_nothing_on_null(:log_gc_stats_on_request_end) if null?
+
+      # See the docs for MUTEX on why we synchronize this.
+      GC_MUTEX.synchronize do
+        if OBJECT_SPACE_SUPPORTS_LIVE_OBJECTS
+          @transaction.message('Final objects on heap: ' \
+            "#{ObjectSpace.live_objects}")
+        end
+        if OBJECT_SPACE_SUPPORTS_ALLOCATED_OBJECTS
+          @transaction.message('Final objects allocated so far: ' \
+            "#{ObjectSpace.allocated_objects}")
+        elsif OBJECT_SPACE_SUPPORTS_COUNT_OBJECTS
+          count = ObjectSpace.count_objects
+          @transaction.message('Final objects allocated so far: ' \
+            "#{count[:TOTAL] - count[:FREE]}")
+        end
+        if GC_SUPPORTS_TIME
+          @transaction.message("Final GC time: #{GC.time}")
+        end
+        if GC_SUPPORTS_CLEAR_STATS
+          # Clear statistics to void integer wraps.
+          GC.clear_stats
+        end
+      end
+    end
+
+    # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+  end
+end