brut 0.0.9 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b455ac9d87f61b5baa45cc6f4cc11c3b940b015aaf7792ba5ed8229dfd23d2fc
-  data.tar.gz: 5e6216b69db294da81ed31041a4b65a4a2b04de229e3d8695e5c9e1ad1625a84
+  metadata.gz: 75470f9c0becdf6066db6bf7d4a53f170e783e2e9a664cc5eef779d977427c3a
+  data.tar.gz: 70006b0aba279306c4f7f99bde119b2d348a55b383179b70955240e5bc39be01
 SHA512:
-  metadata.gz: 688aba783c6b979976ddf40417a6220a10295effef357aa9ebc0b1cd772fac759cae4ddaa2ce09c5bb4b1559d65ee04261d57a3c4253559b7f22a4c9dfffa42b
-  data.tar.gz: 67dbc5b31bf1c6e02f4f5b505d3f69e1eb084f862ccb78372377a3b49052e71711af4868eec6c5fd3bc68a4994bc10bbecb5ce42a260677c6a42c765f8a21e0a
+  metadata.gz: 6cfdd32b6fe7595d3a8215d5ed5a9bc8ec33f6093284fbf82be365c2bd7ca2a1e92695ab63a0cb629424ff0877f726647b1853433ab620f694a8de9b130fd852
+  data.tar.gz: 2487a01fa0138416af5821c4699c68febd1bffb16be906e53cc2b39c0315f6cf0fc26c87d20b23de975eaef52b683ae495a8ab09b21b944f074e78db7adeb5cb

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brut (0.0.9)
+    brut (0.0.11)
       concurrent-ruby
       i18n
       irb

data/lib/brut/cli/app.rb

@@ -211,7 +211,7 @@ class Brut::CLI::App
     if self.class.configure_only?
       as_execution_result(command.execute)
     else
-      result = Brut.container.instrumentation.span("CLI.#{$0}", class: self.class.name) do |span|
+      result = Brut.container.instrumentation.span("CLI #{$0}", prefix: "brut.cli", class: self.class.name) do |span|
         as_execution_result(command.execute)
       end
       result

data/lib/brut/cli/apps/db.rb

@@ -13,12 +13,10 @@ class Brut::CLI::Apps::DB < Brut::CLI::App
     def handle_bootstrap_exception(ex)
       case ex
       when Sequel::DatabaseConnectionError
-        err.puts "Database needs to be created"
-        stop_execution
+        abort_execution("Database needs to be created")
       when Sequel::DatabaseError
         if ex.cause.kind_of?(PG::UndefinedTable)
-          err.puts "Migrations need to be run"
-          stop_execution
+          abort_execution("Migrations need to be run")
         else
           super
         end
@@ -87,6 +85,7 @@ class Brut::CLI::Apps::DB < Brut::CLI::App
         stop_execution
       when Sequel::DatabaseError
         if ex.cause.kind_of?(PG::UndefinedTable)
+          out.puts ex.message
           out.puts "Migrations need to be run"
           continue_execution
         else
@@ -151,8 +150,7 @@ class Brut::CLI::Apps::DB < Brut::CLI::App
     def handle_bootstrap_exception(ex)
       case ex
       when Sequel::DatabaseConnectionError
-        err.puts "Database does not exist. Create it first"
-        stop_execution
+        abort_execution("Database does not exist. Create it first")
       when Sequel::DatabaseError
         if ex.cause.kind_of?(PG::UndefinedTable)
           # ignoring - we are running migrations which will address this

data/lib/brut/cli/apps/test.rb

@@ -47,11 +47,11 @@ class Brut::CLI::Apps::Test < Brut::CLI::App
       end
       Brut.container.instrumentation.span("tests.run") do |span|
         if args.empty?
-          span.add_attributes(tests: :all)
+          span.add_prefixed_attributes("brut.cli.test", tests: :all)
           out.puts "Running all tests"
           system! "#{rspec_command} #{Brut.container.app_specs_dir}/"
         else
-          span.add_attributes(tests: args.length)
+          span.add_prefixed_attributes("brut.cli.test", tests: args.length)
           test_args = args.map { |_|
             '"' + Shellwords.escape(_) + '"'
           }.join(" ")

data/lib/brut/cli.rb

@@ -26,12 +26,7 @@ module Brut
     # @param project_root [Pathname] the path to the root of your project. This is needed before the Brut framework is initialized so
     # it must be specified explicitly.
     def self.app(app_klass, project_root:)
-      Brut::CLI::AppRunner.new(app_klass:,project_root:).run!.tap {
-        otel_configured = OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
-        if otel_configured
-          OpenTelemetry.tracer_provider.shutdown
-        end
-      }
+      Brut::CLI::AppRunner.new(app_klass:,project_root:).run!
     end
     autoload(:App, "brut/cli/app")
     autoload(:Command, "brut/cli/command")

data/lib/brut/framework/mcp.rb

@@ -17,6 +17,9 @@ require "opentelemetry/exporter/otlp"
 # intended to use or interact with this class at all. End of line.
 class Brut::Framework::MCP
 
+  @otel_shutdown = Concurrent::AtomicBoolean.new(false)
+  def self.otel_shutdown = @otel_shutdown
+
   # Create and configure the MCP.  The app will not work until {#boot!} has been called, however most of the core configuration
   # will be available via `Brut.container`.
   #
@@ -50,6 +53,17 @@ class Brut::Framework::MCP
     setup_zeitwerk
 
     @app = app_klass.new
+    otel_prefix = if @app.id == @app.organization
+                    @app.id
+                  else
+                    "#{@app.organization}.#{@app.id}"
+                  end
+    Brut.container.store(
+      "otel_attribute_prefix",
+      "String",
+      "Prefix for all OTel attributes set by the app",
+      otel_prefix
+    )
   end
 
   # Starts up the internals of Brut and that app so that it can receive requests from
@@ -66,58 +80,34 @@ class Brut::Framework::MCP
       begin
         Brut.container.sequel_db_handle.disconnect
       rescue Sequel::DatabaseConnectionError
-        SemanticLogger["Sequel::Database"].info "Not connected to database, so not disconnecting"
+        SemanticLogger[self.class].info "Not connected to database, so not disconnecting"
+      end
+      otel_configured = OpenTelemetry.tracer_provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+      if otel_configured
+        if $PROGRAM_NAME =~ /^sidekiq/
+          SemanticLogger[self.class].info "Assuming we are sidekiq, which will shutdown OpenTelemetry, so doing nothing", program: $PROGRAM_NAME
+        else
+          if self.class.otel_shutdown.make_true
+            SemanticLogger[self.class].info "Shutting down OpenTelemetry", program: $PROGRAM_NAME
+            OpenTelemetry.tracer_provider.shutdown
+          else
+            SemanticLogger[self.class].info "OpenTelemetry already shutdown", program: $PROGRAM_NAME
+          end
+        end
+      else
+        SemanticLogger[self.class].info "OpenTelemetry was not configured, so no shutdown needed", program: $PROGRAM_NAME
       end
     end
-    Sequel::Database.extension :pg_array
-    Sequel::Database.extension :pg_json
-
-    sequel_db = Brut.container.sequel_db_handle
-
-    Sequel::Model.db = sequel_db
 
-    Sequel::Model.plugin :find_bang
-    Sequel::Model.plugin :created_at
-    Sequel::Model.plugin :table_select
-    Sequel::Model.plugin :skip_saving_columns
+    boot_otel!
+    boot_postgres!
 
-    if !Brut.container.external_id_prefix.nil?
-      Sequel::Model.plugin :external_id, global_prefix: Brut.container.external_id_prefix
-    end
     if Brut.container.eager_load_classes?
       SemanticLogger["Brut"].info("Eagerly loading app's classes")
       @loader.eager_load
     else
       SemanticLogger["Brut"].info("Lazily loading app's classes")
     end
-    OpenTelemetry::SDK.configure do |c|
-      c.service_name = @app.id
-      if ENV["OTEL_TRACES_EXPORTER"]
-        SemanticLogger[self.class].info "OTEL_TRACES_EXPORTER was set (to '#{ENV['OTEL_TRACES_EXPORTER']}'), so Brut's OTel logging is disabled"
-      else
-        c.add_span_processor(
-          OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
-            Brut::Instrumentation::LoggerSpanExporter.new
-          )
-        )
-      end
-
-      if defined?(OpenTelemetry::Instrumentation::Sidekiq)
-        c.use 'OpenTelemetry::Instrumentation::Sidekiq', {
-          span_naming: :job_class,
-        }
-      else
-        SemanticLogger[self.class].info "OpenTelemetry::Instrumentation::Sidekiq is not loaded, so Sidekiq traces will not be captured"
-      end
-    end
-
-    Brut.container.store(
-      "tracer",
-      OpenTelemetry::SDK::Trace::Tracer,
-      "Tracer for Open Telemetry",
-      OpenTelemetry.tracer_provider.tracer(@app.id)
-    )
-    Sequel::Database.extension :brut_instrumentation
 
     @app.boot!
 
@@ -215,7 +205,7 @@ class Brut::Framework::MCP
             hook = klass.new
             span.add_prefixed_attributes("#{method}.args",args.map { |k,v| [ k,v.class] }.to_h )
             result = hook.send(method,**args)
-            span.add_attributes(result:)
+            span.add_prefixed_attributes("brut", result_class: result.class)
             case result
             in URI => uri
               redirect to(uri.to_s)
@@ -304,4 +294,53 @@ private
 
     @loader.setup
   end
+
+  def boot_postgres!
+    Sequel::Database.extension :pg_array
+    Sequel::Database.extension :pg_json
+
+    sequel_db = Brut.container.sequel_db_handle
+    sequel_db.extension :brut_instrumentation
+
+    Sequel::Model.db = sequel_db
+
+    Sequel::Model.plugin :find_bang
+    Sequel::Model.plugin :created_at
+    Sequel::Model.plugin :table_select
+    Sequel::Model.plugin :skip_saving_columns
+
+    if !Brut.container.external_id_prefix.nil?
+      Sequel::Model.plugin :external_id, global_prefix: Brut.container.external_id_prefix
+    end
+  end
+
+  def boot_otel!
+    OpenTelemetry::SDK.configure do |c|
+      c.service_name = @app.id
+      if ENV["OTEL_TRACES_EXPORTER"]
+        SemanticLogger[self.class].info "OTEL_TRACES_EXPORTER was set (to '#{ENV['OTEL_TRACES_EXPORTER']}'), so Brut's OTel logging is disabled"
+      else
+        c.add_span_processor(
+          OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(
+            Brut::Instrumentation::LoggerSpanExporter.new
+          )
+        )
+      end
+
+      if defined?(OpenTelemetry::Instrumentation::Sidekiq)
+        c.use 'OpenTelemetry::Instrumentation::Sidekiq', {
+          span_naming: :job_class,
+        }
+      else
+        SemanticLogger[self.class].info "OpenTelemetry::Instrumentation::Sidekiq is not loaded, so Sidekiq traces will not be captured"
+      end
+    end
+
+    Brut.container.store(
+      "tracer",
+      OpenTelemetry::SDK::Trace::Tracer,
+      "Tracer for Open Telemetry",
+      OpenTelemetry.tracer_provider.tracer(@app.id)
+    )
+  end
 end

data/lib/brut/front_end/component.rb

@@ -79,7 +79,8 @@ class Brut::FrontEnd::Component
   #
   # @return [Brut::FrontEnd::Templates::HTMLSafeString] string containing the component's HTML.
   def render
-    Brut.container.instrumentation.span("#{self.class}.render") do |span|
+    Brut.container.instrumentation.span("#{self.class} render") do |span|
+      span.add_prefixed_attributes("brut", type: :component, class: self.class.name)
       Brut.container.component_locator.locate(self.template_name).
         then { Brut::FrontEnd::Template.new(it) }.
         then { it.render_template(self).html_safe! }
@@ -133,7 +134,7 @@ class Brut::FrontEnd::Component
     # @return [Brut::FrontEnd::Templates::HTMLSafeString] of the rendered component.
     def component(component_instance,&block)
       component_name = component_instance.kind_of?(Class) ? component_instance.name : component_instance.class.name
-      Brut.container.instrumentation.span(component_name) do |span|
+      Brut.container.instrumentation.span("component #{component_name}") do |span|
         if component_instance.kind_of?(Class)
           if !component_instance.ancestors.include?(Brut::FrontEnd::Component)
             raise ArgumentError,"#{component_instance} is not a component and cannot be created"
@@ -141,9 +142,9 @@ class Brut::FrontEnd::Component
           component_instance = Thread.current.thread_variable_get(:request_context).
             then { |request_context| request_context.as_constructor_args(component_instance,request_params: nil)
             }.then { |constructor_args| component_instance.new(**constructor_args) }
-          span.add_attributes("global_component" => true, "class" => component_instance.class.name)
+          span.add_prefixed_attributes("brut", "global_component" => true)
         else
-          span.add_attributes("global_component" => false, "class" => component_instance.class.name)
+          span.add_prefixed_attributes("brut", "global_component" => false)
         end
         if !block.nil?
           component_instance.yielded_block = block

data/lib/brut/front_end/form.rb

@@ -35,7 +35,7 @@ class Brut::FrontEnd::Form
       self.class.input_definitions.key?(key)
     }
     if unknown_params.any?
-      Brut.container.instrumentation.add_attributes(ignored_unknown_params: unknown_params)
+      Brut.container.instrumentation.add_attributes(prefix: :brut, ignored_unknown_params: unknown_params.join(","))
     end
     @params = params.except(*unknown_params).map { |name,value|
         input_definition = begin
@@ -132,7 +132,18 @@ class Brut::FrontEnd::Form
   # values are arrays of {Brut::FrontEnd::Forms::ValidityState} instances.
   #
   # @param [true|false] server_side_only if true, only server side constraints are returned.
-  # @return [Hash] map of input names to arrays of validity states
+  # @return [Hash<String|Array[2]>] a map of input names to arrays of constraint violations.  The first element in the
+  # array is the validity state for the input, which is a {Brut::FrontEnd::Forms::ValidityState} instance.  The second
+  # element is the index of the input in the array.  This index is used when you have more than one field with the same
+  # name.
+  #
+  # @example iterationg
+  # form.constraint_violations.each do |input_name, (constraint_violations,index)|
+  #   # input_name is the input's name, e.g. "email"
+  #   # constraint_violations is an array of {Brut::FrontEnd::Forms::ValidityState} instances, one for each
+  #   #                       problem with the field's value
+  #   # index is the index of the input in the array, e.g. 0  for the first email field, 1 for the second, etc.
+  # end
   #
   def constraint_violations(server_side_only: false)
     @inputs.map { |input_name, inputs|
@@ -179,15 +190,17 @@ class Brut::FrontEnd::Form
 private
 
   def convert_to_string_or_nil(hash)
+    converted_hash = {}
     hash.each do |key,value|
+      key = key.to_s
       case value
-      in Hash       then convert_to_string_or_nil(value)
-      in String     then hash[key] = RichString.new(value).to_s_or_nil
-      in Numeric    then hash[key] = value.to_s
-      in TrueClass  then hash[key] = "true"
-      in FalseClass then hash[key] = "false"
-      in NilClass   then # it's fine
-      in Array      then hash[key] = value
+      in Hash       then converted_hash[key] = convert_to_string_or_nil(value)
+      in String     then converted_hash[key] = RichString.new(value).to_s_or_nil
+      in Numeric    then converted_hash[key] = value.to_s
+      in TrueClass  then converted_hash[key] = "true"
+      in FalseClass then converted_hash[key] = "false"
+      in NilClass   then converted_hash[key] = nil
+      in Array      then converted_hash[key] = value
       else
         if Brut.container.project_env.test?
           raise ArgumentError, "Got #{value.class} for #{key} in params hash, which is not expected"
@@ -196,5 +209,6 @@ private
         end
       end
     end
+    converted_hash
   end
 end

data/lib/brut/front_end/handlers/csp_reporting_handler.rb

@@ -4,7 +4,7 @@ class Brut::FrontEnd::Handlers::CspReportingHandler < Brut::FrontEnd::Handler
   def handle(body:)
     begin
       parsed = JSON.parse(body.read)
-      Brut.container.instrumentation.add_attributes(parsed)
+      Brut.container.instrumentation.add_attributes(parsed.merge(prefix: "brut.csp-reporting"))
     rescue => ex
       Brut.container.instrumentation.record_exception(ex)
     end

data/lib/brut/front_end/handlers/locale_detection_handler.rb

@@ -8,8 +8,13 @@ class Brut::FrontEnd::Handlers::LocaleDetectionHandler < Brut::FrontEnd::Handler
   def handle(body:,session:)
     begin
       parsed = JSON.parse(body.read)
-      Brut.container.instrumentation.add_attributes(parsed_body: parsed)
-      Brut.container.instrumentation.add_attributes(parsed_class: parsed.class)
+
+      Brut.container.instrumentation.add_attributes(
+        prefix: "brut.locale-detection",
+        parsed_body: parsed,
+        parsed_class: parsed.class
+      )
+
       if parsed.kind_of?(Hash)
         locale   = parsed["locale"]
         timezone = parsed["timeZone"]

data/lib/brut/front_end/middlewares/annotate_brut_owned_paths.rb

@@ -7,7 +7,7 @@ class Brut::FrontEnd::Middlewares::AnnotateBrutOwnedPaths < Brut::FrontEnd::Midd
   end
   def call(env)
     if env["PATH_INFO"] =~ /^\/__brut\//
-      Brut.container.instrumentation.add_attributes("brut.owned_path" => true)
+      Brut.container.instrumentation.add_attributes(prefix: "brut", owned_path: true)
       env["brut.owned_path"] = true
     end
     @app.call(env)

data/lib/brut/front_end/middlewares/open_telemetry_span.rb

@@ -3,9 +3,33 @@ class Brut::FrontEnd::Middlewares::OpenTelemetrySpan < Brut::FrontEnd::Middlewar
     @app = app
   end
   def call(env)
-    path = env["REQUEST_PATH"]
-    method = env["REQUEST_METHOD"]
-    Brut.container.instrumentation.span("HTTP.#{method}.#{path}") do |span|
+    otel_standard_attributes = {
+      "http.request.method"      => env["REQUEST_METHOD"],
+      "url.path"                 => env["PATH_INFO"],
+      "url.query"                => env["QUERY_STRING"],
+      "url.scheme"               => env["rack.url_scheme"],
+      "url.full"                 => "#{env["rack.url_scheme"]}://#{env["HTTP_HOST"]}#{env["REQUEST_URI"]}",
+      "server.address"           => env["HTTP_HOST"],
+      "user_agent.original"      => env["HTTP_USER_AGENT"],
+      "network.peer.ip"          => env["REMOTE_ADDR"],
+      "network.peer.port"        => env["REMOTE_PORT"],
+      "network.protocol.version" => env["HTTP_VERSION"],
+    }.merge(
+      "http.request.header.accept-language" => env["HTTP_ACCEPT_LANGUAGE"],
+      "http.request.header.referer"         => env["HTTP_REFERER"],
+      "http.request.header.user-agent"      => env["HTTP_USER_AGENT"],
+      "http.request.header.accept"          => env["HTTP_ACCEPT"],
+    ).delete_if { |_,v| v.nil? || v.empty? }
+
+    span_name = if env["PATH_INFO"] =~ /^\/js\//
+                  "HTTP #{env['REQUEST_METHOD']} JS"
+                elsif env["PATH_INFO"] =~ /^\/css\//
+                  "HTTP #{env['REQUEST_METHOD']} CSS"
+                else
+                  "HTTP #{env['REQUEST_METHOD']}"
+                end
+    Brut.container.tracer.in_span(span_name,kind: :server, attributes: otel_standard_attributes) do |span|
+      env["brut.otel.root_span"] = span
       @app.call(env)
     end
   end

data/lib/brut/front_end/route_hooks/locale_detection.rb

@@ -5,7 +5,6 @@
 class Brut::FrontEnd::RouteHooks::LocaleDetection < Brut::FrontEnd::RouteHook
   def before(session:,env:)
     http_accept_language = Brut::I18n::HTTPAcceptLanguage.from_header(env["HTTP_ACCEPT_LANGUAGE"])
-    Brut.container.instrumentation.add_attributes(http_accept_language:)
     if !session.http_accept_language.known?
       session.http_accept_language = http_accept_language
     end
@@ -20,10 +19,10 @@ class Brut::FrontEnd::RouteHooks::LocaleDetection < Brut::FrontEnd::RouteHook
       end
     end
     if best_locale
-      Brut.container.instrumentation.add_attributes(best_locale:)
+      Brut.container.instrumentation.add_attributes(prefix: "brut.locale-detection", best_locale:)
       ::I18n.locale = best_locale
     else
-      Brut.container.instrumentation.add_attributes(best_locale: false)
+      Brut.container.instrumentation.add_attributes(prefix: "brut.locale-detection", best_locale: false)
     end
     continue
   end

data/lib/brut/instrumentation/open_telemetry.rb

@@ -3,9 +3,7 @@ class Brut::Instrumentation::OpenTelemetry
   #
   # @param [String] name the name of the span. Should be specific to the code being wrapped, but not contain dynamic information. For
   # example, you could call this the method name, but should not include parameters in the name.
-  # @param [Hash<String|Symbol,Object>] attributes Hash of attributes to include in this span. This is as if you called
-  # {Brut::Instrumentation::OpenTelemetry::Span#add_attributes} as the first line of the block.  See that method for more details on
-  # the contents of this hash.
+  # @param [Hash<String|Symbol,Object>] attributes Hash of attributes to include in this span. This is as if you called {Brut::Instrumentation::OpenTelemetry::Span#add_attributes} as the first line of the block.  There is a special attribute named `prefix:` that will control how attributes are prefixed.  If it is missing, the app's configured OTel prefix is used. If it is sent to `false`, no prefixing is done. Otherwise, the provided value is used as the prefix.  Generally, you don't want to set this so your app's prefix is used. Also note that the keys and values are automatically converted to primitive types, so you can use whatever makes sense. Just know that for rich objects `to_s` will be called.
   #
   # @yield [Brut::Instrumentation::OpenTelemetry::Span] executes this block in the context of a new OpenTelemetry span. yields
   #                                                     the span so you can call further methods on it.
@@ -16,9 +14,9 @@ class Brut::Instrumentation::OpenTelemetry
   #
   def span(name,**attributes,&block)
     result = nil
-    Brut.container.tracer.in_span(name) do |span|
+    normalized_attributes = NormalizedAttributes.new(:detect,attributes).to_h
+    Brut.container.tracer.in_span(name, attributes: normalized_attributes) do |span|
       wrapped_span = Span.new(span)
-      wrapped_span.add_attributes(attributes)
       begin
         result = block.(wrapped_span)
       rescue => ex
@@ -46,22 +44,32 @@ class Brut::Instrumentation::OpenTelemetry
     current_span.record_exception(ex,attributes: NormalizedAttributes.new(nil,attributes).to_h)
   end
 
-  # Adds attributes to the current span
+  # Adds attributes to the span, converting the hash or keyword arguments to strings. This will use
+  # the app's Otel prefix for all attributes, so you do not have to prefix them.
+  # If you need to set standard attributes, you should use {Brut::Instrumentation::OpenTelemetry::Span#add_prefixed_attributes} instead.
   # @param [Hash] attributes any attributes to attach to the event.
   def add_attributes(attributes)
     current_span = OpenTelemetry::Trace.current_span
-    current_span.add_attributes(NormalizedAttributes.new(nil,attributes).to_h)
+    current_span.add_attributes(NormalizedAttributes.new(:detect,attributes).to_h)
   end
 
+private
+
   class NormalizedAttributes
     def initialize(prefix,attributes)
-      prefix = if prefix
-                 "#{prefix}."
-               else
-                 ""
-               end
+      if prefix == :detect
+        prefix = attributes.delete(:prefix)
+        if prefix.nil?
+          prefix = Brut.container.otel_attribute_prefix
+        end
+      end
+      prefix_string = if prefix
+                        "#{prefix}."
+                      else
+                        ""
+                      end
       @attributes = (attributes || {}).map { |key,value|
-        [ "#{prefix}#{key}", normalize_value(value) ]
+        [ "#{prefix_string}#{key}", normalize_value(value) ]
       }.to_h
     end
 
@@ -82,20 +90,23 @@ class Brut::Instrumentation::OpenTelemetry
         value.to_s
       end
     end
+
   end
 
   class Span < SimpleDelegator
 
-    # Adds attributes to the span, converting the hash or keyword arguments to strings.
+    # Adds attributes to the span, converting the hash or keyword arguments to strings. This will use
+    # the app's Otel prefix for all attributes, so you do not have to prefix them.
+    # If you need to set standard attributes, you should use {#add_prefixed_attributes} instead.
     #
     # @param [Hash] attributes a hash of the attributes to add. Keys will be converted to strings via `to_s`.
     # Values will be converted via {Brut::Instrumentation::OpenTelemetry::NormalizedAttributes}, which preserves strings, numbers, and
     # booleans, and converts the rest to strings via `to_s`.
     def add_attributes(attributes)
-      add_prefixed_attributes(nil,attributes)
+      add_prefixed_attributes(:detect,attributes)
     end
 
-    # Adds attributes to the span, prefixing each key with the given prefix, then converting the hash or keyword arguments to strings.
+    # Adds attributes to the span, prefixing each key with the given prefix, then converting the hash or keyword arguments to strings.  For example, if the prefix is 'my_app' and you add the attributes 'type' and 'reason', the actual attribute names will be 'my_app.type' and 'my_app.reason'.
     #
     # @see #add_attributes
     def add_prefixed_attributes(prefix,attributes)

data/lib/brut/instrumentation.rb

@@ -2,6 +2,7 @@ module Brut::Instrumentation
   autoload(:OpenTelemetry,"brut/instrumentation/open_telemetry")
   autoload(:LoggerSpanExporter,"brut/instrumentation/logger_span_exporter")
 
+  # Convenience method to add attributes to create a span without accessing the instrumentation instance directly.
   def span(name,**attributes,&block)
     Brut.container.instrumentation.span(name,**attributes,&block)
   end

data/lib/brut/sinatra_helpers.rb

@@ -65,19 +65,28 @@ module Brut::SinatraHelpers
       Brut.container.routing.register_page(path)
 
       get path do
-        route = Brut.container.routing.for(path: path,method: :get)
-        page_class = route.handler_class
-        Brut.container.instrumentation.span(page_class.name, path: path) do |span|
+        brut_route = Brut.container.routing.for(path: path,method: :get)
+        page_class = brut_route.handler_class
+        path_template = brut_route.path_template
+
+        root_span = env["brut.otel.root_span"]
+        if root_span
+          root_span.name = "GET #{path_template}"
+          root_span.add_attributes("http.route" => path_template)
+        end
+
+        Brut.container.instrumentation.span(page_class.name) do |span|
+          span.add_prefixed_attributes("brut", type: :page, class: page_class)
           request_context = Thread.current.thread_variable_get(:request_context)
           constructor_args = request_context.as_constructor_args(
             page_class,
             request_params: params,
-            route: route,
+            route: brut_route,
           )
-          span.add_prefixed_attributes("initializer.args", constructor_args.map { |k,v| [k.to_s,v.class.name] }.to_h)
+          span.add_prefixed_attributes("brut.initializer.args", constructor_args.map { |k,v| [k.to_s,v.class.name] }.to_h)
           page_instance = page_class.new(**constructor_args)
           result = page_instance.handle!
-          span.add_attributes(result_class: result.class)
+          span.add_prefixed_attributes("brut", result_class: result.class)
           case result
           in URI => uri
             redirect to(uri.to_s)
@@ -148,37 +157,55 @@ module Brut::SinatraHelpers
         # This must be re-looked up per-request do allow reloading to work
         brut_route = Brut.container.routing.for(path:,method:)
 
+        path_template = brut_route.path_template
+
+        root_span = env["brut.otel.root_span"]
+        if root_span
+          root_span.name = "#{method} #{path_template}"
+          root_span.add_attributes("http.route" => path_template)
+        end
+
         handler_class = brut_route.handler_class
-        form_class    = brut_route.respond_to?(:form_class) ? brut_route.form_class : nil
-
-        request_context = Thread.current.thread_variable_get(:request_context)
-        handler = handler_class.new
-        form = if form_class.nil?
-                 nil
-               else
-                 form_class.new(params: params)
-               end
-
-        process_args = request_context.as_method_args(handler,:handle,request_params: params,form: form,route:brut_route)
-
-        result = handler.handle!(**process_args)
-
-        case result
-        in URI => uri
-          redirect to(uri.to_s)
-        in Brut::FrontEnd::Component => component_instance
-          render_html(component_instance).to_s
-        in [ Brut::FrontEnd::Component => component_instance, Brut::FrontEnd::HttpStatus => http_status ]
-          [
-            http_status.to_i,
-            render_html(component_instance).to_s,
-          ]
-        in Brut::FrontEnd::HttpStatus => http_status
-          http_status.to_i
-        in Brut::FrontEnd::Download => download
-          [ 200, download.headers, download.data ]
-        else
-          raise NoMatchingPatternError, "Result from #{handler.class}'s handle! method was a #{result.class}, which cannot be used to understand the response to generate"
+
+        Brut.container.instrumentation.span(handler_class.name) do |span|
+
+          form_class = brut_route.respond_to?(:form_class) ? brut_route.form_class : nil
+
+          span.add_prefixed_attributes("brut",
+            type: form_class ? :form : :action,
+            class: handler_class,
+            form_class: form_class,
+          )
+
+          request_context = Thread.current.thread_variable_get(:request_context)
+          handler = handler_class.new
+          form = if form_class.nil?
+                   nil
+                 else
+                   form_class.new(params: params)
+                 end
+
+          process_args = request_context.as_method_args(handler,:handle,request_params: params,form: form,route:brut_route)
+
+          result = handler.handle!(**process_args)
+
+          case result
+          in URI => uri
+            redirect to(uri.to_s)
+          in Brut::FrontEnd::Component => component_instance
+            render_html(component_instance).to_s
+          in [ Brut::FrontEnd::Component => component_instance, Brut::FrontEnd::HttpStatus => http_status ]
+            [
+              http_status.to_i,
+              render_html(component_instance).to_s,
+            ]
+          in Brut::FrontEnd::HttpStatus => http_status
+            http_status.to_i
+          in Brut::FrontEnd::Download => download
+            [ 200, download.headers, download.data ]
+          else
+            raise NoMatchingPatternError, "Result from #{handler.class}'s handle! method was a #{result.class}, which cannot be used to understand the response to generate"
+          end
         end
       end
     end

data/lib/brut/version.rb

@@ -1,4 +1,4 @@
 module Brut
   # @!visibility private
-  VERSION = "0.0.9"
+  VERSION = "0.0.11"
 end

data/lib/sequel/extensions/brut_instrumentation.rb

@@ -4,7 +4,13 @@ module Sequel
     module BrutInstrumentation
       # @!visibility private
       def log_connection_yield(sql,conn,args=nil)
-        Brut.container.instrumentation.span("SQL", sql: sql) do |span|
+        otel_attributes = {
+          "db.system" => "sql",
+          "db.system.name" => "postgresql",
+          "db.query.text" => sql,
+          "prefix" => false,
+        }
+        Brut.container.instrumentation.span("SQL", **otel_attributes) do |span|
           super
         end
       end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: brut
 version: !ruby/object:Gem::Version
-  version: 0.0.9
+  version: 0.0.11
 platform: ruby
 authors:
 - David Bryant Copeland
 bindir: exe
 cert_chain: []
-date: 2025-04-02 00:00:00.000000000 Z
+date: 2025-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: irb