union_station_hooks_core 1.0.0

data/lib/union_station_hooks_core/request_reporter/controllers.rb

@@ -0,0 +1,187 @@
+#  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 'utils'
+
+module UnionStationHooks
+  class RequestReporter
+    ###### Logging controller-related information ######
+
+    # Logs that you are calling a web framework controller action. Of course,
+    # you should only call this if your web framework has the concept of
+    # controller actions. For example Rails does, but Sinatra and Grape
+    # don't.
+    #
+    # This form takes an options hash as well as a block. You can pass
+    # additional information about the web framework controller action, which
+    # will be logged. The block is expected to perform the actual request
+    # handling. When the block returns, timing information about the block is
+    # automatically logged.
+    #
+    # See also {#log_controller_action} for a form that doesn't
+    # expect a block.
+    #
+    # The `union_station_hooks_rails` gem automatically calls this for you
+    # if your application is a Rails app.
+    #
+    # @yield The given block is expected to perform request handling.
+    # @param [Hash] options Information about the controller action.
+    #   All options are optional.
+    # @option options [String] :controller_name
+    #   The controller's name, e.g. `PostsController`.
+    # @option options [String] :action_name
+    #   The controller action's name, e.g. `create`.
+    # @option options [String] :method
+    #   The HTTP method that the web framework thinks this request should have,
+    #   e.g. `GET` and `PUT`. The main use case for this option is to support
+    #   Rails's HTTP verb emulation. Rails uses a parameter named
+    #   [`_method`](http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-patch-put-or-delete-methods-work-questionmark)
+    #   to emulate HTTP verbs besides GET and POST. Other web frameworks may
+    #   have a similar mechanism.
+    # @return The return value of the block.
+    #
+    # @example Rails example
+    #   # This example shows what to put inside a Rails controller action
+    #   # method. Note that all of this is automatically done for you if you
+    #   # use the union_station_hooks_rails gem.
+    #   options = {
+    #     :controller_name => self.class.name,
+    #     :action_name => action_name,
+    #     :method => request.request_method
+    #   }
+    #   reporter.log_controller_action_block(options) do
+    #     do_some_request_processing_here
+    #   end
+    def log_controller_action_block(options = {})
+      if null?
+        do_nothing_on_null(:log_controller_action_block)
+        yield
+      else
+        build_full_controller_action_string(options)
+        has_error = true
+        begin_time = UnionStationHooks.now
+        begin
+          result = yield
+          has_error = false
+          result
+        ensure
+          log_controller_action(
+            options.merge(
+              :begin_time => begin_time,
+              :end_time => UnionStationHooks.now,
+              :has_error => has_error
+            )
+          )
+        end
+      end
+    end
+
+    # Logs that you are calling a web framework controller action. Of course,
+    # you should only call this if your web framework has the concept of
+    # controller actions. For example Rails does, but Sinatra and Grape
+    # don't.
+    #
+    # You can pass additional information about the web framework controller
+    # action, which will be logged.
+    #
+    # Unlike {#log_controller_action_block}, this form does not expect a block.
+    # However, you are expected to pass timing information to the options
+    # hash.
+    #
+    # The `union_station_hooks_rails` gem automatically calls
+    # {#log_controller_action_block} for you if your application is a Rails
+    # app.
+    #
+    # @param [Hash] options Information about the controller action.
+    # @option options [String] :controller_name (optional)
+    #   The controller's name, e.g. `PostsController`.
+    # @option options [String] :action_name (optional if :controller_name
+    #   isn't set) The controller action's name, e.g. `create`.
+    # @option options [String] :method (optional)
+    #   The HTTP method that the web framework thinks this request should have,
+    #   e.g. `GET` and `PUT`. The main use case for this option is to support
+    #   Rails's HTTP verb emulation. Rails uses a parameter named
+    #   [`_method`](http://guides.rubyonrails.org/form_helpers.html#how-do-forms-with-patch-put-or-delete-methods-work-questionmark)
+    #   to emulate HTTP verbs besides GET and POST. Other web frameworks may
+    #   have a similar mechanism.
+    # @option options [TimePoint or Time] :begin_time The time at which the
+    #   controller action begun. See {UnionStationHooks.now} to learn more.
+    # @option options [TimePoint or Time] :end_time The time at which the
+    #   controller action ended. See {UnionStationHooks.now} to learn more.
+    # @option options [Boolean] :has_error (optional) Whether an uncaught
+    #   exception occurred during the request. Default: false.
+    #
+    # @example
+    #   # This example shows what to put inside a Rails controller action
+    #   # method. Note that all of this is automatically done for you if you
+    #   # use the union_station_hooks_rails gem.
+    #   options = {
+    #     :controller_name => self.class.name,
+    #     :action_name => action_name,
+    #     :method => request.request_method,
+    #     :begin_time => UnionStationHooks.now
+    #   }
+    #   begin
+    #     do_some_request_processing_here
+    #   rescue Exception
+    #     options[:has_error] = true
+    #     raise
+    #   ensure
+    #     options[:end_time] = UnionStationHooks.now
+    #     reporter.log_controller_action(options)
+    #   end
+    def log_controller_action(options)
+      return do_nothing_on_null(:log_controller_action) if null?
+      Utils.require_key(options, :begin_time)
+      Utils.require_key(options, :end_time)
+
+      if options[:controller_name]
+        build_full_controller_action_string(options)
+        @transaction.message("Controller action: #{@controller_action}")
+      end
+      if options[:method]
+        @transaction.message("Application request method: #{options[:method]}")
+      end
+      @transaction.log_activity('framework request processing',
+        options[:begin_time], options[:end_time], nil, options[:has_error])
+    end
+
+    # Returns whether {#log_controller_action_block} or
+    # {#log_controller_action} has been called during this request.
+    #
+    # @return [Boolean]
+    def controller_action_logged?
+      !!@controller_action
+    end
+
+  private
+
+    def build_full_controller_action_string(options)
+      if options[:controller_name]
+        Utils.require_key(options, :action_name)
+        @controller_action = "#{options[:controller_name]}#" \
+          "#{options[:action_name]}"
+      end
+    end
+  end
+end

data/lib/union_station_hooks_core/request_reporter/misc.rb

@@ -0,0 +1,218 @@
+#  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 'digest/md5'
+UnionStationHooks.require_lib 'utils'
+
+module UnionStationHooks
+  class RequestReporter
+    ###### Logging miscellaneous other information ######
+
+    # Logs a user-defined activity, for display in the activity timeline.
+    #
+    # An activity is a block in the activity timeline in the Union Station
+    # user interace. It has a name, a begin time and an end time.
+    #
+    # This form takes a block. Before and after the block runs, the time
+    # is measured.
+    #
+    # @param name The name that should show up in the activity timeline.
+    #   It can be any arbitrary name but may not contain newlines.
+    # @return The return value of the block.
+    # @yield The block is expected to perform the activity.
+    # @example
+    #   reporter.log_activity_block('Preheat cache') do
+    #     calculate_preheat_values.each_pair do |key, value|
+    #       Rails.cache.write(key, value)
+    #     end
+    #   end
+    def log_activity_block(name, &block)
+      if null?
+        do_nothing_on_null(:log_activity_block)
+        yield
+      else
+        @transaction.log_activity_block(name, &block)
+      end
+    end
+
+    # Logs a benchmarking activity, for display in the activity timeline.
+    #
+    # An activity is a block in the activity timeline in the Union Station
+    # user interace. It has a name, a begin time and an end time.
+    #
+    # The primary use case of this method is to integrate with Rails's
+    # benchmarking API (`ActiveSupport::Benchmarkable`). The Rails benchmarking
+    # API allows you to run a block and to log how long that block has taken.
+    # But you can also use it to integrate with the Ruby standard library's
+    # `Benchmark` class.
+    #
+    # You can wrap a benchmark call in a
+    # `UnionStationHooks.log_benchmark_block` call, so that an entry for it is
+    # displayed in the acitivity timeline. This method measures the time before
+    # and after the block runs.
+    #
+    # The difference between this method and {#log_activity_block} is that this
+    # method generates timeline blocks of a different color, as to
+    # differentiate user-defined activities from benchmark activities.
+    #
+    # If your app is a Rails app, then the `union_station_hooks_rails` gem
+    # automatically calls this for you every time
+    # `ActiveSupport::Benchmarkable#benchmark` is called. This includes
+    # `benchmark` calls from controllers and from views.
+    #
+    # @param title A title for this benchmark. It can be any arbitrary name but
+    #   may not contain newlines.
+    # @return The return value of the block.
+    # @yield The block is expected to perform the benchmarking activity.
+    # @example Rails example
+    #   # This example shows what to put inside a Rails controller action
+    #   # method. Note that the `log_benchmark_block` call is automatically done
+    #   # for you if you use the union_station_hooks_rails gem.
+    #   UnionStationHooks.log_benchmark_block('Process data files') do
+    #     benchmark('Process data files') do
+    #       expensive_files_operation
+    #     end
+    #   end
+    def log_benchmark_block(title = 'Benchmarking', &block)
+      if null?
+        do_nothing_on_null(:log_benchmark_block)
+        yield
+      else
+        log_activity_block("BENCHMARK: #{title}", &block)
+      end
+    end
+
+    # Logs an exception that occurred during a request.
+    #
+    # If {#log_controller_action} or {#log_controller_action_happened}
+    # was called during the same request, then the information passed to
+    # those methods will be included in the exception report.
+    #
+    # @param [Exception] exception
+    def log_exception(exception)
+      transaction = @context.new_transaction(
+        @app_group_name,
+        :exceptions,
+        @key)
+      begin
+        return do_nothing_on_null(:log_exception) if transaction.null?
+
+        base64_message = exception.message
+        base64_message = exception.to_s if base64_message.empty?
+        base64_message = Utils.base64(base64_message)
+        base64_backtrace = Utils.base64(exception.backtrace.join("\n"))
+
+        if controller_action_logged?
+          transaction.message("Controller action: #{@controller_action}")
+        end
+        transaction.message("Request transaction ID: #{@txn_id}")
+        transaction.message("Message: #{base64_message}")
+        transaction.message("Class: #{exception.class.name}")
+        transaction.message("Backtrace: #{base64_backtrace}")
+      ensure
+        transaction.close
+      end
+    end
+
+    # Logs a database query that was performed during the request.
+    #
+    # @option options [String] :name (optional) A name for this database
+    #   query activity. Default: "SQL"
+    # @option options [TimePoint or Time] :begin_time The time at which this
+    #   database query begun. See {UnionStationHooks.now} to learn more.
+    # @option options [TimePoint or Time] :end_time The time at which this
+    #   database query ended. See {UnionStationHooks.now} to learn more.
+    # @option options [String] :query The database query string.
+    def log_database_query(options)
+      return do_nothing_on_null(:log_database_query) if null?
+      Utils.require_key(options, :begin_time)
+      Utils.require_key(options, :end_time)
+      Utils.require_non_empty_key(options, :query)
+
+      name = options[:name] || 'SQL'
+      begin_time = options[:begin_time]
+      end_time = options[:end_time]
+      query = options[:query]
+
+      digest = Digest::MD5.hexdigest("#{name}\0#{query}\0#{rand}")
+      @transaction.log_activity("DB BENCHMARK: #{digest}",
+        begin_time, end_time, "#{name}\n#{query}")
+    end
+
+    # Logs that something was successfully retrieved from a cache.
+    # This can be any cache, be it an in-memory Hash, Redis, Memcached, a
+    # flat file or whatever.
+    #
+    # There is just one exception. You should not use this method to log cache
+    # hits in the ActiveRecord SQL cache or similar mechanisms.
+    # Database-related timing should be logged with {#log_database_query}.
+    #
+    # If your app is a Rails app, then the `union_station_hooks_rails` gem
+    # automatically calls this for you every time an `ActiveSupport::Cache`
+    # `#fetch` or `#read` call success. This includes calls to
+    # `Rails.cache.fetch` or `Rails.cache.read`, because `Rails.cache` is
+    # an instance of `ActiveSupport::Cache`.
+    #
+    # @param [String] name A unique name for this cache hit event. The cache
+    #   key is a good value to use.
+    # @note At present (30 September 2015), logged cache hit/miss information
+    #   isn't shown in the Union Station interface. We may implement this
+    #   feature in the near future.
+    def log_cache_hit(name)
+      return do_nothing_on_null(:log_cache_hit) if null?
+      @transaction.message("Cache hit: #{name}")
+    end
+
+    # Logs the failure to retrieve something from a cache.
+    # This can be any cache, be it an in-memory Hash, Redis, Memcached, a
+    # flat file or whatever.
+    #
+    # There is just one exception. You should not use this method to log cache
+    # misses in the ActiveRecord SQL cache or similar mechanisms.
+    # Database-related timing should be logged with {#log_database_query}.
+    #
+    # If your app is a Rails app, then the `union_station_hooks_rails` gem
+    # automatically calls this for you every time an `ActiveSupport::Cache`
+    # `#fetch` or `#read` call success. This includes calls to
+    # `Rails.cache.fetch` or `Rails.cache.read`, because `Rails.cache` is
+    # an instance of `ActiveSupport::Cache`.
+    #
+    # @param [String] name A unique name for this cache miss event. The cache
+    #   key is a good value to use.
+    # @param [Numeric] miss_cost_duration The amount of time that was spent in
+    #   calculating or processing something, as a result of this cache miss.
+    #   This time is in **microseconds**.
+    # @note At present (30 September 2015), logged cache hit/miss information
+    #   isn't shown in the Union Station interface. We may implement this
+    #   feature in the near future.
+    def log_cache_miss(name, miss_cost_duration = nil)
+      return do_nothing_on_null(:log_cache_miss) if null?
+      if miss_cost_duration
+        @transaction.message("Cache miss (#{miss_cost_duration.to_i} usec): " \
+          "#{name}")
+      else
+        @transaction.message("Cache miss: #{name}")
+      end
+    end
+  end
+end

data/lib/union_station_hooks_core/request_reporter/view_rendering.rb

@@ -0,0 +1,76 @@
+#  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 'utils'
+
+module UnionStationHooks
+  class RequestReporter
+    ###### Logging view rendering-related information ######
+
+    # Logs timing information about the rendering of a single view, template or
+    # partial. This form expects a block, which is to perform the
+    # view/template/partial rendering. Timing information is collected before
+    # and after the block returns.
+    #
+    # The `union_station_hooks_rails` gem automatically calls this for you
+    # if your application is a Rails app. It will call this on every view
+    # or partial rendering.
+    #
+    # @yield The given block is expected to perform the actual view rendering.
+    # @return The return value of the block.
+    def log_view_rendering_block(&block)
+      if null?
+        do_nothing_on_null(:log_view_rendering_block)
+        yield
+      else
+        log_activity_block('view rendering', &block)
+      end
+    end
+
+    # Logs timing information about the rendering of a single view, template or
+    # partial.
+    #
+    # Unlike {#log_view_rendering_block}, this form does not expect a block.
+    # However, you are expected to pass timing information to the options
+    # hash.
+    #
+    # The `union_station_hooks_rails` gem automatically calls
+    # {#log_view_rendering_block} for you if your application is a Rails app.
+    # It will call this on every view or partial rendering.
+    #
+    # @option options [TimePoint or Time] :begin_time The time at which this
+    #   view rendering begun. See {UnionStationHooks.now} to learn more.
+    # @option options [TimePoint or Time] :end_time The time at which this view
+    #   rendering ended. See {UnionStationHooks.now} to learn more.
+    # @option options [Boolean] :has_error (optional) Whether an uncaught
+    #   exception occurred during the view rendering. Default: false.
+    def log_view_rendering(options)
+      return do_nothing_on_null(:log_view_rendering) if null?
+      Utils.require_key(options, :begin_time)
+      Utils.require_key(options, :end_time)
+
+      @transaction.log_activity('view rendering', options[:begin_time],
+        options[:end_time], nil, options[:has_error])
+    end
+  end
+end