Allow Rails to provide timing data in browser dev-tools via Server-Timing header

docs/CHANGELOG.md

@@ -10,6 +10,10 @@ nav_order: 5
 
 ## main
 
+* Allow instrumentation to be automatically included in Server-Timing headers generated by Rails. To enable this set the config `config.use_deprecated_instrumentation_name = false`.  The old key `!render.view_component` is deprecated: update ActiveSupport::Notification subscriptions to `render.view_component`.
+
+    *Travis Gaff*
+
 ## 3.3.0
 
 * Include InlineTemplate by default in Base. **Note:** It's no longer necessary to include `ViewComponent::InlineTemplate` to use inline templates.

docs/api.md

@@ -244,6 +244,13 @@ The controller used for testing components.
 Can also be configured on a per-test basis using `#with_controller_class`.
 Defaults to `ApplicationController`.
 
+### `.use_deprecated_instrumentation_name`
+
+Whether ActiveSupport Notifications use the private name `"!render.view_component"`
+or are made more publicly available via `"render.view_component"`.
+Will default to `false` in next major version.
+Defaults to `true`.
+
 ### `.view_component_path`
 
 The path in which components, their templates, and their sidecars should
@@ -342,14 +349,6 @@ with_request_url("/users/42") do
 end
 ```
 
-To use a specific host, pass the host param:
-
-```ruby
-with_request_url("/users/42", host: "app.example.com") do
-  render_inline(MyComponent.new)
-end
-```
-
 ### `#with_variant(variant)`
 
 Set the Action Pack request variant for the given block:
@@ -362,6 +361,12 @@ end
 
 ## Errors
 
+### `AlreadyDefinedPolymorphicSlotSetterError`
+
+A method called 'SETTER_METHOD_NAME' already exists and would be overwritten by the 'SETTER_NAME' polymorphic slot setter.
+
+Please choose a different setter name.
+
 ### `ContentAlreadySetForPolymorphicSlotError`
 
 Content for slot SLOT_NAME has already been provided.

docs/guide/instrumentation.md

@@ -15,14 +15,23 @@ To enable ActiveSupport notifications, use the `instrumentation_enabled` option:
 # config/application.rb
 # Enable ActiveSupport notifications for all ViewComponents
 config.view_component.instrumentation_enabled = true
+config.view_component.use_deprecated_instrumentation_name = false
 ```
 
-Then subscribe to the `!render.view_component` event:
+Setting `use_deprecated_instrumentation_name` configures the event name. If `false` the name is `"render.view_component"`. If `true` (default) the deprecated `"!render.view_component"` will be used.
+
+Subscribe to the event:
 
 ```ruby
-ActiveSupport::Notifications.subscribe("!render.view_component") do |*args|
+ActiveSupport::Notifications.subscribe("render.view_component") do |*args| # or !render.view_component
   event = ActiveSupport::Notifications::Event.new(*args)
-  event.name    # => "!render.view_component"
+  event.name    # => "render.view_component"
   event.payload # => { name: "MyComponent", identifier: "/Users/mona/project/app/components/my_component.rb" }
 end
 ```
+
+## Viewing instrumentation sums in the browser developer tools
+
+When using `render.view_component` with `config.server_timing = true` (default in development) in Rails 7, the browser developer tools display the sum total timing information in Network > Timing under the key `render.view_component`.
+
+![Browser showing the Server Timing data in the browser dev tools](../images/viewing_instrumentation_sums_in_browser_dev_tools.png "Server Timing data in the browser dev tools")

docs/index.md

@@ -192,6 +192,7 @@ ViewComponent is built by over a hundred members of the community, including:
 <img src="https://avatars.githubusercontent.com/tbroad-ramsey?s=64" alt="tbroad-ramsey" width="32" />
 <img src="https://avatars.githubusercontent.com/tclem?s=64" alt="tclem" width="32" />
 <img src="https://avatars.githubusercontent.com/tenderlove?s=64" alt="tenderlove" width="32" />
+<img src="https://avatars.githubusercontent.com/tgaff?s=64" alt="tgaff" width="32" />
 <img src="https://avatars.githubusercontent.com/thutterer?s=64" alt="thutterer" width="32" />
 <img src="https://avatars.githubusercontent.com/tonkpils?s=64" alt="tonkpils" width="32" />
 <img src="https://avatars.githubusercontent.com/traels?s=64" alt="traels" width="32" />

lib/view_component/config.rb

@@ -17,6 +17,7 @@ def defaults
           preview_route: "/rails/view_components",
           show_previews_source: false,
           instrumentation_enabled: false,
+          use_deprecated_instrumentation_name: true,
           render_monkey_patch_enabled: true,
           view_component_path: "app/components",
           component_parent_class: nil,
@@ -99,6 +100,13 @@ def defaults
       # Whether ActiveSupport notifications are enabled.
       # Defaults to `false`.
 
+      # @!attribute use_deprecated_instrumentation_name
+      # @return [Boolean]
+      # Whether ActiveSupport Notifications use the private name `"!render.view_component"`
+      # or are made more publicly available via `"render.view_component"`.
+      # Will default to `false` in next major version.
+      # Defaults to `true`.
+
       # @!attribute render_monkey_patch_enabled
       # @return [Boolean] Whether the #render method should be monkey patched.
       # If this is disabled, use `#render_component` or

lib/view_component/engine.rb

@@ -2,6 +2,7 @@
 
 require "rails"
 require "view_component/config"
+require "view_component/deprecation"
 
 module ViewComponent
   class Engine < Rails::Engine # :nodoc:
@@ -39,8 +40,14 @@ class Engine < Rails::Engine # :nodoc:
         Base.config = app.config.view_component
 
         if app.config.view_component.instrumentation_enabled.present?
-          # :nocov:
+          # :nocov: Re-executing the below in tests duplicates initializers and causes order-dependent failures.
           ViewComponent::Base.prepend(ViewComponent::Instrumentation)
+          if app.config.view_component.use_deprecated_instrumentation_name
+            ViewComponent::Deprecation.deprecation_warning(
+              "!render.view_component",
+              "Use the new instrumentation key `render.view_component` instead. See https://viewcomponent.org/guide/instrumentation.html"
+            )
+          end
           # :nocov:
         end
       end

lib/view_component/instrumentation.rb

@@ -10,7 +10,7 @@ def self.included(mod)
 
     def render_in(view_context, &block)
       ActiveSupport::Notifications.instrument(
-        "!render.view_component",
+        notification_name,
         {
           name: self.class.name,
           identifier: self.class.identifier
@@ -19,5 +19,13 @@ def render_in(view_context, &block)
         super(view_context, &block)
       end
     end
+
+    private
+
+    def notification_name
+      return "!render.view_component" if ViewComponent::Base.config.use_deprecated_instrumentation_name
+
+      "render.view_component"
+    end
   end
 end

test/sandbox/test/config_test.rb

@@ -14,6 +14,7 @@ def test_defaults_are_correct
       assert_equal @config.preview_route, "/rails/view_components"
       assert_equal @config.show_previews_source, false
       assert_equal @config.instrumentation_enabled, false
+      assert_equal @config.use_deprecated_instrumentation_name, true
       assert_equal @config.render_monkey_patch_enabled, true
       assert_equal @config.show_previews, true
       assert_equal @config.preview_paths, ["#{Rails.root}/test/components/previews"]

test/sandbox/test/instrumentation_test.rb

@@ -4,16 +4,29 @@
 
 class InstrumentationTest < ViewComponent::TestCase
   def test_instrumentation
+    with_config_option(:use_deprecated_instrumentation_name, false) do
+      events = []
+      ActiveSupport::Notifications.subscribe("render.view_component") do |*args|
+        events << ActiveSupport::Notifications::Event.new(*args)
+      end
+      render_inline(InstrumentationComponent.new)
+
+      assert_selector("div", text: "hello,world!")
+      assert_equal(events.size, 1)
+      assert_equal("render.view_component", events[0].name)
+      assert_equal(events[0].payload[:name], "InstrumentationComponent")
+      assert_match("app/components/instrumentation_component.rb", events[0].payload[:identifier])
+    end
+  end
+
+  def test_instrumentation_with_deprecated_name
     events = []
     ActiveSupport::Notifications.subscribe("!render.view_component") do |*args|
       events << ActiveSupport::Notifications::Event.new(*args)
     end
     render_inline(InstrumentationComponent.new)
 
-    assert_selector("div", text: "hello,world!")
     assert_equal(events.size, 1)
-    assert_equal(events[0].name, "!render.view_component")
-    assert_equal(events[0].payload[:name], "InstrumentationComponent")
-    assert_match("app/components/instrumentation_component.rb", events[0].payload[:identifier])
+    assert_equal("!render.view_component", events[0].name)
   end
 end