union_station_hooks_core 1.0.2 → 2.0.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZGU3MGNhZGUwZjEzYzZkMzM1OTk1ZmExZTg0MjQ3MzlmZTNjZDdkZQ==
+    NGUzYzY0ODI2NjJhZTdjZDliOWJjOWQyZTFhZDM3MzVjODFhYWUzYw==
   data.tar.gz: !binary |-
-    ZjY4NzI5MTJjZDIxOWJhZTQ2OWZiNTk2ZWYzYWUyODEyYzlkYTNhZQ==
+    NjBjOGIzYjU3NmYwYjkzNzJhOTA4ZTU1MWJkNDQ2MmFhYzIyODZiMQ==
 SHA512:
   metadata.gz: !binary |-
-    ODk1YzBlZTM4ZmI4MjllMGZjODkxZTkzY2NkOTI2MTJhZjc5YjM4YjUxYjcy
-    MmVlZTI0MDBmZGZjOGFjNzgzN2NhMjRmNWZkMWI4NWNhZmY4YjhlNWRhZjcy
-    N2JlZDYzNGE2NGFhN2YwOTQ4NmJhZDc2ZWVlODcyODRlNWExMzI=
+    ODhmNDg4NTgwNDNjMjgwNjIyYjIwY2VjNzI1ZjZiZTI4MGUxOWE1NTZlODYy
+    NTI1N2U4MzJkYzk0NDdkZGJhN2U5MzNjOTg3NDY5YmI2MWQwNDFlMmRhMGJk
+    MTQyMzFiNmM0NmEyOTU1NTcyOGY4NjNhOGU3YWFjNzEzNWRlYmU=
   data.tar.gz: !binary |-
-    ODQ1MDQ4MGRjNjhjMjBjMWUxMzliMTA5ODZjNDM5ODIxMzA0N2JmYTcxOTc0
-    ZjFmODdjMjcyYjZjZjQ5NzNiYWQ5YjMyNTc2OTg4Y2UzOGZhOGQ1NjgyMjRh
-    YTNhMGI1OTFmOGM0NDFhNTQ5YTc1ZDM4NjE3ZTg4YjVmZGI0MmY=
+    OTJhNDI4YzJkNjhhYTkyODc2NjNmOTllMzM2NWUwNjlhY2IxNzhhMzlkNWVj
+    MzY0ZmJjZDlmYWVmYmRkMzNhMWRiMGFlNTAzMDRjMGI5ODJiMDk4NmFjYzAy
+    ZTk5MzE0ZjgwZTliOTQ1NTI5YjM2OTQ3NWRiNDQyODJkZTVjNTA=

data/lib/union_station_hooks_core/api.rb

@@ -123,9 +123,9 @@ module UnionStationHooks
     # etc. The exact information contained in the object is operating
     # system specific, hence why the object is meant to be opaque.
     #
-    # See {RequestReporter#log_controller_action_happened} for an example of
+    # See {RequestReporter#log_controller_action} for an example of
     # an API method which expects timing information.
-    # `RequestReporter#log_controller_action_happened` expects you to
+    # `RequestReporter#log_controller_action` expects you to
     # provide timing information about a controller action. That timing
     # information is supposed to be obtained by calling
     # `UnionStationHooks.now`.

data/lib/union_station_hooks_core/request_reporter/basics.rb

@@ -52,7 +52,7 @@ module UnionStationHooks
     # @private
     GC_SUPPORTS_CLEAR_STATS = GC.respond_to?(:clear_stats)
 
-    # Log the beginning of a Rack request. This is automatically called
+    # Logs the beginning of a Rack request. This is automatically called
     # from {UnionStationHooks.begin_rack_request} (and thus automatically
     # from Passenger).
     #
@@ -62,9 +62,16 @@ module UnionStationHooks
       @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).
+    # Logs the end of a Rack request. This means that the Rack response body
+    # has been written out, and that the `#close` has been called on the Rack
+    # response body.
+    #
+    # This does not necessarily indicate that any buffering mechanism in
+    # between the app and the client (e.g. Nginx, or the Passenger core) is
+    # done flushing the response to the client.
+    #
+    # 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)
@@ -128,5 +135,62 @@ module UnionStationHooks
     end
 
     # rubocop:enable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+
+    # Logs that the application server is about to write out the Rack
+    # response body.
+    #
+    # This call *must* be followed by a call to {#log_writing_rack_body_end}
+    # some time later.
+    #
+    # This is automatically called by Passenger's Rack handler.
+    #
+    # @private
+    # @return An ID to be passed later to {#log_writing_rack_body_end}.
+    def log_writing_rack_body_begin
+      return do_nothing_on_null(:log_writing_rack_body_begin) if null?
+      @transaction.log_activity_begin('writing out response body')
+      nil
+    end
+
+    # Logs that the application server is done writing out the Rack
+    # response body. This does not necessarily indicate that any buffering
+    # mechanism in between the app and the client (e.g. Nginx, or the Passenger
+    # core) is done flushing the response to the client.
+    #
+    # This is automatically called by Passenger's Rack handler.
+    #
+    # @private
+    def log_writing_rack_body_end(id)
+      return do_nothing_on_null(:log_writing_rack_body_end) if null?
+      @transaction.log_activity_end('writing out response body')
+      nil
+    end
+
+    # Logs that the application server is about to call `#close` on the
+    # Rack body object.
+    #
+    # This call *must* be followed by a call to {#log_closing_rack_body_end}
+    # some time later.
+    #
+    # This is automatically called by Passenger's Rack handler.
+    #
+    # @private
+    # @return An ID to be passed later to {#log_closing_rack_body_end}.
+    def log_closing_rack_body_begin
+      return do_nothing_on_null(:log_closing_rack_body_begin) if null?
+      @transaction.log_activity_begin('closing rack body object')
+      nil
+    end
+
+    # Logs that the application server is done calling `#close` on the
+    # Rack body object.
+    #
+    # This is automatically called by Passenger's Rack handler.
+    #
+    # @private
+    def log_closing_rack_body_end(id)
+      return do_nothing_on_null(:log_closing_rack_body_end) if null?
+      @transaction.log_activity_end('closing rack body object')
+    end
   end
 end

data/lib/union_station_hooks_core/request_reporter/misc.rb

@@ -21,7 +21,6 @@
 #  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
@@ -41,20 +40,82 @@ module UnionStationHooks
     # @return The return value of the block.
     # @yield The block is expected to perform the activity.
     # @example
-    #   reporter.log_activity_block('Preheat cache') do
+    #   reporter.log_user_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)
+    def log_user_activity_block(name, &block)
       if null?
-        do_nothing_on_null(:log_activity_block)
+        do_nothing_on_null(:log_user_activity_block)
         yield
       else
-        @transaction.log_activity_block(name, &block)
+        @transaction.log_activity_block(next_user_activity_name,
+          name, &block)
       end
     end
 
+    # Logs the begin of 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 logs only the name and the begin time. You *must* also
+    # call {#log_user_activity_end} later with the same name to log the end
+    # time.
+    #
+    # @param name The name that should show up in the activity timeline.
+    #   It can be any arbitrary name but may not contain newlines.
+    # @return id An ID which you must pass to {#log_user_activity_end} later.
+    def log_user_activity_begin(name)
+      return do_nothing_on_null(:log_user_activity_begin) if null?
+      id = next_user_activity_name
+      @transaction.log_activity_begin(id, UnionStationHooks.now, name)
+      id
+    end
+
+    # Logs the end of 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 logs only the name and the end time. You *must* also
+    # have called {#log_user_activity_begin} earlier with the same name to log
+    # the begin time.
+    #
+    # @param id The ID which you obtained from {#log_user_activity_begin}
+    #   earlier.
+    # @param [Boolean] has_error Whether an uncaught
+    #   exception occurred during the activity.
+    def log_user_activity_end(id, has_error = false)
+      return do_nothing_on_null(:log_user_activity_end) if null?
+      @transaction.log_activity_end(id, UnionStationHooks.now, has_error)
+    end
+
+    # 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.
+    #
+    # Unlike {#log_user_activity_block}, this form does not expect a block.
+    # However, you are expected to pass timing information.
+    #
+    # @param name The name that should show up in the activity timeline.
+    #   It can be any arbitrary name but may not contain newlines.
+    # @param [TimePoint or Time] begin_time  The time at which this activity
+    #   begun. See {UnionStationHooks.now} to learn more.
+    # @param [TimePoint or Time] end_time The time at which this activity
+    #   ended. See {UnionStationHooks.now} to learn more.
+    # @param [Boolean] has_error Whether an uncaught
+    #   exception occurred during the activity.
+    def log_user_activity(name, begin_time, end_time, has_error = false)
+      return do_nothing_on_null(:log_user_activity) if null?
+      @transaction.log_activity(next_user_activity_name,
+        begin_time, end_time, name, has_error)
+    end
+
     # Logs a benchmarking activity, for display in the activity timeline.
     #
     # An activity is a block in the activity timeline in the Union Station
@@ -71,8 +132,8 @@ module UnionStationHooks
     # 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
+    # The difference between this method and {#log_user_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
@@ -98,13 +159,13 @@ module UnionStationHooks
         do_nothing_on_null(:log_benchmark_block)
         yield
       else
-        log_activity_block("BENCHMARK: #{title}", &block)
+        log_user_activity_block("Benchmark: #{title}", &block)
       end
     end
 
     # Logs an exception that occurred during a request.
     #
-    # If {#log_controller_action} or {#log_controller_action_happened}
+    # If {#log_controller_action_block} or {#log_controller_action}
     # was called during the same request, then the information passed to
     # those methods will be included in the exception report.
     #
@@ -154,8 +215,7 @@ module UnionStationHooks
       end_time = options[:end_time]
       query = options[:query]
 
-      digest = Digest::MD5.hexdigest("#{name}\0#{query}\0#{rand}")
-      @transaction.log_activity("DB BENCHMARK: #{digest}",
+      @transaction.log_activity(next_database_query_name,
         begin_time, end_time, "#{name}\n#{query}")
     end
 
@@ -214,5 +274,19 @@ module UnionStationHooks
         @transaction.message("Cache miss: #{name}")
       end
     end
+
+  private
+
+    def next_user_activity_name
+      result = @next_user_activity_number
+      @next_user_activity_number += 1
+      "user activity #{result}"
+    end
+
+    def next_database_query_name
+      result = @next_database_query_number
+      @next_database_query_number += 1
+      "database query #{result}"
+    end
   end
 end

data/lib/union_station_hooks_core/request_reporter/view_rendering.rb

@@ -36,14 +36,17 @@ module UnionStationHooks
     # if your application is a Rails app. It will call this on every view
     # or partial rendering.
     #
+    # @param [String] name Name of the view, template or partial that is being
+    #   rendered.
     # @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)
+    def log_view_rendering_block(name, &block)
       if null?
         do_nothing_on_null(:log_view_rendering_block)
         yield
       else
-        log_activity_block('view rendering', &block)
+        @transaction.log_activity_block(next_view_rendering_name,
+          name, &block)
       end
     end
 
@@ -58,6 +61,8 @@ module UnionStationHooks
     # {#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 [String] :name Name of the view, template or partial
+    #   that is being rendered.
     # @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
@@ -66,11 +71,21 @@ module UnionStationHooks
     #   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, :name)
       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])
+      @transaction.log_activity(next_view_rendering_name,
+        options[:begin_time], options[:end_time],
+        options[:name], options[:has_error])
+    end
+
+  private
+
+    def next_view_rendering_name
+      result = @next_view_rendering_number
+      @next_view_rendering_number += 1
+      "view rendering #{result}"
     end
   end
 end

data/lib/union_station_hooks_core/request_reporter.rb

@@ -91,6 +91,11 @@ module UnionStationHooks
   # You can check whether the null mode is active by calling {#null?}.
   #
   # Closing a RequestReporter also causes it to enter the null mode.
+  #
+  # ## Thread-safety
+  #
+  # RequestReporter is *not* thread-safe. If you access it concurrently, be sure
+  # to wrap its operations in a mutex.
   class RequestReporter
     # Returns a new RequestReporter object. You should not call
     # `RequestReporter.new` directly. See "Obtaining a RequestReporter"
@@ -106,6 +111,9 @@ module UnionStationHooks
       @app_group_name = app_group_name
       @key = key
       @transaction = continue_transaction
+      @next_view_rendering_number = 1
+      @next_user_activity_number = 1
+      @next_database_query_number = 1
     end
 
     # Indicates that no further information will be logged for this

data/lib/union_station_hooks_core/version_data.rb

@@ -37,8 +37,8 @@
 # here.
 
 {
-  :major  => 1,
+  :major  => 2,
   :minor  => 0,
-  :tiny   => 2,
-  :string => '1.0.2'
+  :tiny   => 0,
+  :string => '2.0.0'
 }

data/lib/union_station_hooks_core.rb

@@ -277,6 +277,11 @@ module UnionStationHooks
     # @raise RuntimeError
     def check_initialized
       if should_initialize? && !initialized?
+        return if !config.fetch(:check_initialized, true)
+
+        # We end each error message with two newlines so that in Passenger
+        # error reports in the exception class is shown on a new line, after
+        # the message.
         if defined?(::Rails)
           raise 'The Union Station hooks are not initialized. Please ensure ' \
             'that you have an initializer file ' \
@@ -284,14 +289,14 @@ module UnionStationHooks
             "this:\n\n" \
             "  if defined?(UnionStationHooks)\n" \
             "    UnionStationHooks.initialize!\n" \
-            '  end'
+            "  end\n\n"
         else
           raise 'The Union Station hooks are not initialized. Please ensure ' \
             'that the following code is called during application ' \
             "startup:\n\n" \
             "  if defined?(UnionStationHooks)\n" \
             "    UnionStationHooks.initialize!\n" \
-            '  end'
+            "  end\n\n"
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: union_station_hooks_core
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Hongli Lai
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-10 00:00:00.000000000 Z
+date: 2015-09-15 00:00:00.000000000 Z
 dependencies: []
 description: Union Station Ruby hooks core code.
 email: info@phusion.nl