rails-profiler 0.38.0 → 0.39.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b58bf97abcca532a115936ba089a63a668d8593dc7311b59d345ea3d5488a6e
-  data.tar.gz: 72144d7c3f5d434c9b61f3b700acd05a783b725fa21addd6c633174e334ce5cc
+  metadata.gz: 6bc10ed77cb2126254ad1b94fb697766bd7e8305fdeb957e7a5dd44909e622dd
+  data.tar.gz: d250a8a1b41ea1668b6835cbf07a0371422fa90b3c820be182da4c6734e82dd1
 SHA512:
-  metadata.gz: 901671364cc31c093aa9a9e5d083ab1fea68f9a1576df7b74239a3b9e6cf7003fe0e8ba4de5e6597b61f93acbc77ab85c976459793620652aab4c808ec5e5f05
-  data.tar.gz: e745e616088f23d67a9420ba5bf6ffc93eb2a0250280590417b6be451194a1d7bbc524641e206270f5d1240ffe3bb2f611d42ede6472309e3700251e8f7703b0
+  metadata.gz: 9c5c4774740ee3f12f3411cba23c3ff0c9c2f28db248d50a1d84f800a5a66d59bff11016f761d4fd1639105a854217c7190ebd5753febfaac08a3c80b1228eb2
+  data.tar.gz: 41d9f3e676848d74bd27c02062d0fe593f12c50aa2ef7de62f7bc1913e6a6ba8816858fade838969eaf1aacb1ca83a13a8f722215a0d4c72b2cdddeed76c6fa9

data/CHANGELOG.md

@@ -19,6 +19,16 @@ every commit of every tag interval is accounted for one way or the other.
 
 ## [Unreleased]
 
+## [0.39.0] - 2026-10-19
+
+<!-- stamped -->
+
+### Added
+
+- **OpenTelemetry:** with `config.otel_enabled = true`, each profiled request is exported as a trace: a root span carrying the profile's own `trace_id` and `span_id`, and a child span for each SQL query, view or partial render, cache operation and outbound `Net::HTTP` call. An application that already initialised OpenTelemetry keeps its own tracer provider; otherwise the gem sends the spans itself over OTLP `http/protobuf` to `config.otel_otlp_endpoint`, with `config.otel_service_name` (the application's name by default).
+- **OpenTelemetry:** the gem does not depend on OpenTelemetry. Add `opentelemetry-sdk` and `opentelemetry-exporter-otlp` to the application's `Gemfile` to use it; without them, `otel_enabled = true` writes one message to the log and exports nothing. With `otel_enabled` at `false` (the default) nothing of OpenTelemetry is loaded.
+- **Collectors:** the SQL, view and cache events now record their `started_at` (epoch seconds), which the trace export uses to place their spans.
+
 ## [0.38.0] - 2026-10-19
 
 <!-- stamped -->

data/lib/profiler/collectors/cache_collector.rb

@@ -40,6 +40,7 @@ module Profiler
           @cache_reads << {
             key: payload[:key],
             hit: payload[:hit],
+            started_at: started.to_f,
             duration: duration
           }
         end
@@ -48,6 +49,7 @@ module Profiler
           duration = ((finished - started) * 1000).round(2)
           @cache_writes << {
             key: payload[:key],
+            started_at: started.to_f,
             duration: duration
           }
         end
@@ -56,6 +58,7 @@ module Profiler
           duration = ((finished - started) * 1000).round(2)
           @cache_deletes << {
             key: payload[:key],
+            started_at: started.to_f,
             duration: duration
           }
         end

data/lib/profiler/collectors/database_collector.rb

@@ -63,6 +63,7 @@ module Profiler
           query = Models::SqlQuery.new(
             sql: payload[:sql],
             duration: duration,
+            started_at: started.to_f,
             binds: extract_binds(payload[:binds]),
             name: payload[:name],
             connection: payload[:connection],

data/lib/profiler/collectors/view_collector.rb

@@ -41,6 +41,7 @@ module Profiler
           @views << {
             identifier: payload[:identifier],
             layout: payload[:layout],
+            started_at: started.to_f,
             duration: duration
           }
         end
@@ -50,6 +51,7 @@ module Profiler
           @intervals << [started, finished]
           @partials << {
             identifier: payload[:identifier],
+            started_at: started.to_f,
             duration: duration
           }
         end

data/lib/profiler/configuration.rb

@@ -45,6 +45,7 @@ module Profiler
                   :cors_allowed_origins, :api_forgery_protection, :frame_ancestors,
                   :track_ajax, :ajax_skip_paths,
                   :track_http, :slow_http_threshold, :http_backtrace_depth,
+                  :otel_enabled, :otel_service_name, :otel_otlp_endpoint,
                   :track_jobs,
                   :track_console,
                   :apply_env_overrides_when_disabled, :restrict_storage_permissions,
@@ -105,6 +106,11 @@ module Profiler
       # The profiler's own calls (cluster, slave proxy) are never recorded, whatever this says.
       @http_skip_hosts = []
       @http_backtrace_depth = 40
+      # OpenTelemetry export of each profiled request as a trace. Off: nothing of OpenTelemetry is
+      # loaded or touched. The opentelemetry-* gems are the application's to add to its Gemfile.
+      @otel_enabled = false
+      @otel_service_name = nil
+      @otel_otlp_endpoint = nil
       @track_jobs = true
       @track_console = true
       @apply_env_overrides_when_disabled = false
@@ -294,6 +300,11 @@ module Profiler
       mcp_enabled && mcp_transport.to_s == "http" ? true : false
     end
 
+    # The service.name of the exported spans: otel_service_name, else the application's name.
+    def resolved_otel_service_name
+      otel_service_name.to_s.strip.empty? ? resolved_name : otel_service_name.to_s
+    end
+
     def resolved_name
       @name || (defined?(Rails) ? Rails.application.class.module_parent_name.underscore : "profiler")
     end

data/lib/profiler/middleware/profiler_middleware.rb

@@ -4,6 +4,7 @@ require "rack"
 require_relative "../models/profile"
 require_relative "../current_context"
 require_relative "../trace_context"
+require_relative "../otel/trace_exporter"
 require_relative "../collectors/lifecycle"
 require_relative "toolbar_injector"
 require_relative "capturing_body"
@@ -128,7 +129,7 @@ module Profiler
 
         # A profile that was not saved (a store unavailable, a save that failed) gets no token and
         # no toolbar: both would point to a profile that is not there.
-        return [status, headers, body] unless Profiler.save_profile(profile, from: "ProfilerMiddleware")
+        return [status, headers, body] unless save_and_export(profile)
 
         set_header(headers, TOKEN_HEADER, profile.token)
 
@@ -172,7 +173,7 @@ module Profiler
           end
           record_response(env, profile, request_body, status, profiled_headers, "", nil, false)
           # Saved before the headers leave: a profile that is not there gets no token.
-          set_header(headers, TOKEN_HEADER, profile.token) if Profiler.save_profile(profile, from: "ProfilerMiddleware")
+          set_header(headers, TOKEN_HEADER, profile.token) if save_and_export(profile)
           return [[status, headers, body], nil]
         end
 
@@ -217,11 +218,20 @@ module Profiler
           end
         end
 
-        Profiler.save_profile(profile, from: "ProfilerMiddleware")
+        save_and_export(profile)
       rescue => e
         Profiler.log_error("ProfilerMiddleware: could not finish the profile of a streamed response", e)
       end
 
+      # The profile is saved, then sent to OpenTelemetry when config.otel_enabled asks for it:
+      # once per profile, here, and not from Profiler.save_profile, which a profile reaches again
+      # whenever a late outbound call completes. The export never raises.
+      def save_and_export(profile)
+        saved = Profiler.save_profile(profile, from: "ProfilerMiddleware")
+        Otel::TraceExporter.export(profile)
+        saved
+      end
+
       def collect_from_any_thread?(collector)
         collector.respond_to?(:collect_from_any_thread?) && collector.collect_from_any_thread?
       end
@@ -266,7 +276,7 @@ module Profiler
           resp_content_type: ""
         )
         collect_all(profile, collectors)
-        Profiler.save_profile(profile, from: "ProfilerMiddleware")
+        save_and_export(profile)
       rescue => e
         Profiler.log_error("ProfilerMiddleware: could not record a failed request", e)
       end

data/lib/profiler/models/sql_query.rb

@@ -3,15 +3,16 @@
 module Profiler
   module Models
     class SqlQuery
-      attr_reader :sql, :duration, :binds, :name, :connection, :backtrace
+      attr_reader :sql, :duration, :binds, :name, :connection, :backtrace, :started_at
 
-      def initialize(sql:, duration:, binds: [], name: nil, connection: nil, backtrace: [])
+      def initialize(sql:, duration:, binds: [], name: nil, connection: nil, backtrace: [], started_at: nil)
         @sql = sql
         @duration = duration
         @binds = binds
         @name = name
         @connection = connection
         @backtrace = backtrace
+        @started_at = started_at
       end
 
       def slow?(threshold = 100)
@@ -29,6 +30,7 @@ module Profiler
       def to_h
         {
           sql: @sql,
+          started_at: @started_at,
           duration: @duration,
           binds: @binds,
           name: @name,

data/lib/profiler/otel/scoped_id_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Profiler
+  module Otel
+    # An id generator for an OpenTelemetry SDK tracer provider that hands out the trace-id and
+    # span-id the current thread asked for once (+with+), and otherwise defers to the generator
+    # the provider had. This is how a span gets the ids the profile already carries, through the
+    # SDK's public API only. Wraps nothing from OpenTelemetry at load time.
+    class ScopedIdGenerator
+      TRACE_KEY = :profiler_otel_trace_id
+      SPAN_KEY = :profiler_otel_span_id
+
+      def initialize(inner)
+        @inner = inner
+      end
+
+      attr_reader :inner
+
+      # Hex ids (32 and 16 characters) in, the byte strings the SDK uses out.
+      def self.with(trace_id:, span_id:)
+        Thread.current[TRACE_KEY] = [trace_id].pack("H*") if trace_id
+        Thread.current[SPAN_KEY] = [span_id].pack("H*") if span_id
+        yield
+      ensure
+        Thread.current[TRACE_KEY] = nil
+        Thread.current[SPAN_KEY] = nil
+      end
+
+      def generate_trace_id
+        take(TRACE_KEY) || @inner.generate_trace_id
+      end
+
+      def generate_span_id
+        take(SPAN_KEY) || @inner.generate_span_id
+      end
+
+      private
+
+      def take(key)
+        value = Thread.current[key]
+        Thread.current[key] = nil
+        value
+      end
+    end
+  end
+end

data/lib/profiler/otel/sdk.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "scoped_id_generator"
+
+module Profiler
+  module Otel
+    # Finds or builds the OpenTelemetry SDK the profiler exports through. The only place that
+    # requires "opentelemetry/..." and the only one that reaches the OpenTelemetry constants, and
+    # it does so only once config.otel_enabled is true: the gem declares no dependency on
+    # OpenTelemetry (like stackprof, it is optional), so an application that never heard of it
+    # loads and profiles exactly as before. Written so that metrics can share it: +available?+,
+    # +resource+ and the OTLP settings are not specific to traces.
+    module Sdk
+      LOCK = Monitor.new
+      REQUIRES = ["opentelemetry/sdk", "opentelemetry/exporter/otlp"].freeze
+      ENDPOINT_ENV = %w[OTEL_EXPORTER_OTLP_TRACES_ENDPOINT OTEL_EXPORTER_OTLP_ENDPOINT].freeze
+
+      @state = nil
+
+      class << self
+        # The tracer provider spans are started from, nil when export is off or cannot work. Warns
+        # once (Profiler.log_error) when it cannot; never raises.
+        def tracer_provider
+          return nil unless Profiler.configuration.otel_enabled
+
+          state = @state || LOCK.synchronize { @state ||= setup_tracer_provider }
+          state[:provider]
+        rescue StandardError, LoadError => e
+          LOCK.synchronize { @state = { provider: nil } }
+          Profiler.log_error("OpenTelemetry export disabled: setup failed", e)
+          nil
+        end
+
+        # Whether the SDK and the OTLP exporter can be loaded. Loads them (the sole place that
+        # does), and says so in the log once if they cannot.
+        def available?
+          return @available unless @available.nil?
+
+          LOCK.synchronize do
+            return @available unless @available.nil?
+
+            @available = load_gems
+          end
+        end
+
+        # The attributes every signal of this process carries.
+        def resource_attributes
+          { "service.name" => Profiler.configuration.resolved_otel_service_name }
+        end
+
+        # The endpoint the profiler's own exporter posts to: otel_otlp_endpoint, else the standard
+        # OTEL_EXPORTER_OTLP_* variables the exporter itself reads. nil when neither is set.
+        def otlp_endpoint
+          configured = Profiler.configuration.otel_otlp_endpoint.to_s.strip
+          return configured unless configured.empty?
+
+          ENDPOINT_ENV.each do |name|
+            value = ENV[name].to_s.strip
+            return value unless value.empty?
+          end
+          nil
+        end
+
+        # Forgets everything decided so far (the specs, and a configuration change).
+        def reset!
+          LOCK.synchronize do
+            @state = nil
+            @available = nil
+          end
+        end
+
+        private
+
+        def load_gems
+          REQUIRES.each { |name| require name }
+          true
+        rescue LoadError => e
+          Profiler.log_error(
+            "config.otel_enabled is true but the OpenTelemetry gems are not available (#{e.message}); " \
+            "add opentelemetry-sdk and opentelemetry-exporter-otlp to the application's Gemfile. " \
+            "OpenTelemetry export is off."
+          )
+          false
+        end
+
+        def setup_tracer_provider
+          return { provider: nil } unless available?
+
+          existing = host_tracer_provider
+          return { provider: scoped(existing) } if existing
+
+          own = build_own_tracer_provider
+          { provider: own && scoped(own) }
+        end
+
+        # The SDK provider the application initialised for itself, if any. The API's global
+        # provider is a proxy until one is installed; its delegate is the SDK's.
+        def host_tracer_provider
+          provider = OpenTelemetry.tracer_provider
+          provider = provider.delegate if provider.respond_to?(:delegate)
+          sdk_provider?(provider) ? provider : nil
+        end
+
+        def sdk_provider?(provider)
+          defined?(OpenTelemetry::SDK::Trace::TracerProvider) &&
+            provider.is_a?(OpenTelemetry::SDK::Trace::TracerProvider)
+        end
+
+        # Our own provider, never installed as the global one: the application's OpenTelemetry
+        # stays as it is. OTLP over http/protobuf, the protocol of opentelemetry-exporter-otlp.
+        def build_own_tracer_provider
+          endpoint = otlp_endpoint
+          unless endpoint
+            Profiler.log_error(
+              "config.otel_enabled is true but there is no OpenTelemetry SDK in the application and " \
+              "config.otel_otlp_endpoint is not set: OpenTelemetry export is off."
+            )
+            return nil
+          end
+
+          exporter = OpenTelemetry::Exporter::OTLP::Exporter.new(endpoint: endpoint)
+          provider = OpenTelemetry::SDK::Trace::TracerProvider.new(
+            resource: OpenTelemetry::SDK::Resources::Resource.create(resource_attributes)
+          )
+          provider.add_span_processor(OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter))
+          at_exit { provider.shutdown }
+          provider
+        end
+
+        # The provider with its id generator wrapped, once.
+        def scoped(provider)
+          unless provider.respond_to?(:id_generator=)
+            Profiler.log_error("OpenTelemetry export disabled: the tracer provider cannot take an id generator")
+            return nil
+          end
+
+          unless provider.id_generator.is_a?(ScopedIdGenerator)
+            provider.id_generator = ScopedIdGenerator.new(provider.id_generator)
+          end
+          provider
+        end
+      end
+    end
+  end
+end

data/lib/profiler/otel/trace_exporter.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "time"
+require "uri"
+require_relative "sdk"
+
+module Profiler
+  module Otel
+    # Sends a finished request profile to OpenTelemetry as one trace: a root span for the request,
+    # a child span for each SQL query, view or partial rendering, cache operation and outbound
+    # HTTP call the collectors already recorded (nothing is instrumented twice). The root span
+    # carries the profile's own trace_id and span_id, so that the trace in the collector and the
+    # profile in the dashboard are the same thing; a traceparent received with the request makes
+    # the root a child of the caller's span, as the profile already says.
+    #
+    # Does nothing, and touches nothing of OpenTelemetry, unless config.otel_enabled is true.
+    # Never raises: an export that fails is logged and the request goes on.
+    module TraceExporter
+      SCOPE_NAME = "profiler"
+      SAMPLED_FLAG = 1
+
+      module_function
+
+      def export(profile)
+        return false unless Profiler.configuration.otel_enabled
+        return false unless profile.trace_id && profile.span_id
+
+        provider = Sdk.tracer_provider
+        return false unless provider
+
+        emit(provider.tracer(SCOPE_NAME, Profiler.version), profile)
+        true
+      rescue StandardError => e
+        Profiler.log_error_once(:otel_export, "OpenTelemetry export of a profile failed", e)
+        false
+      end
+
+      def emit(tracer, profile)
+        started = profile.started_at || Time.now
+        finished = profile.finished_at || started
+        root = start_root(tracer, profile, started)
+        parent = OpenTelemetry::Trace.context_with_span(root)
+
+        children(profile).each do |child|
+          start = child[:started_at] || started
+          span = tracer.start_span(child[:name], with_parent: parent, kind: child[:kind],
+                                                 attributes: child[:attributes], start_timestamp: start)
+          mark_error(span, child[:error])
+          span.finish(end_timestamp: start + child[:duration].to_f / 1000.0)
+        end
+
+        root_status(root, profile)
+        root.finish(end_timestamp: finished)
+      end
+
+      def start_root(tracer, profile, started)
+        attributes = {
+          "http.request.method" => profile.method.to_s,
+          "url.path" => profile.path.to_s,
+          "profiler.token" => profile.token.to_s
+        }
+        attributes["http.response.status_code"] = profile.status if profile.status
+        name = "#{profile.method} #{profile.path}".strip
+
+        ScopedIdGenerator.with(trace_id: profile.trace_id, span_id: profile.span_id) do
+          tracer.start_span(name, with_parent: parent_context(profile), kind: :server,
+                                  attributes: attributes, start_timestamp: started)
+        end
+      end
+
+      # A caller's span (traceparent) when the request had one, otherwise an empty context, which
+      # makes the root span a true root. In both cases the trace_id comes from the generator.
+      def parent_context(profile)
+        return OpenTelemetry::Context.empty unless profile.parent_span_id
+
+        remote = OpenTelemetry::Trace::SpanContext.new(
+          trace_id: [profile.trace_id].pack("H*"), span_id: [profile.parent_span_id].pack("H*"),
+          trace_flags: OpenTelemetry::Trace::TraceFlags.from_byte(SAMPLED_FLAG), remote: true
+        )
+        OpenTelemetry::Trace.context_with_span(OpenTelemetry::Trace.non_recording_span(remote))
+      end
+
+      def root_status(root, profile)
+        return unless profile.status.to_i >= 500
+
+        root.status = OpenTelemetry::Trace::Status.error("HTTP #{profile.status}")
+      end
+
+      def mark_error(span, error)
+        span.status = OpenTelemetry::Trace::Status.error(error.to_s) if error
+      end
+
+      # Every collected event worth a span, as {name:, kind:, attributes:, started_at:, duration:}
+      # (duration in ms). An event without a start time (a profile saved before the collectors
+      # recorded it) starts with the request.
+      def children(profile)
+        data = profile.collectors_data || {}
+        sql_spans(fetch(data, "database")) + view_spans(fetch(data, "view")) +
+          cache_spans(fetch(data, "cache")) + http_spans(fetch(data, "http"))
+      end
+
+      def sql_spans(data)
+        list(data, :queries).filter_map do |query|
+          next if query[:transaction]
+
+          statement = query[:sql].to_s
+          { name: sql_name(statement), kind: :client, started_at: time(query[:started_at]),
+            duration: query[:duration],
+            attributes: { "db.query.text" => statement, "db.operation.name" => statement[/\A\s*(\w+)/, 1].to_s.upcase } }
+        end
+      end
+
+      def view_spans(data)
+        views = list(data, :views).map { |v| ["render_template", v] } +
+                list(data, :partials).map { |v| ["render_partial", v] }
+        views.map do |kind, view|
+          { name: "#{kind} #{view[:identifier]}", kind: :internal, started_at: time(view[:started_at]),
+            duration: view[:duration], attributes: { "code.filepath" => view[:identifier].to_s } }
+        end
+      end
+
+      # The key is left out: cache keys carry user data, and the dashboard is the place for them.
+      def cache_spans(data)
+        reads = list(data, :reads).map { |e| ["read", e, { "cache.hit" => e[:hit] ? true : false }] }
+        writes = list(data, :writes).map { |e| ["write", e, {}] }
+        deletes = list(data, :deletes).map { |e| ["delete", e, {}] }
+        (reads + writes + deletes).map do |operation, event, attributes|
+          { name: "cache #{operation}", kind: :internal, started_at: time(event[:started_at]),
+            duration: event[:duration], attributes: attributes.merge("cache.operation" => operation) }
+        end
+      end
+
+      # Scheme, host and path only: the query string of an outbound call may hold a token.
+      def http_spans(data)
+        list(data, :requests).filter_map do |request|
+          next if request[:in_flight]
+
+          url = safe_url(request[:url])
+          attributes = { "http.request.method" => request[:method].to_s, "url.full" => url }
+          attributes["http.response.status_code"] = request[:status] if request[:status].to_i.positive?
+          { name: "HTTP #{request[:method]}", kind: :client, started_at: time(request[:started_at]),
+            duration: request[:duration], attributes: attributes, error: request[:error] }
+        end
+      end
+
+      def sql_name(statement)
+        operation = statement[/\A\s*(\w+)/, 1].to_s.upcase
+        operation.empty? ? "sql" : operation
+      end
+
+      def safe_url(url)
+        uri = URI.parse(url.to_s)
+        uri.query = nil
+        uri.fragment = nil
+        uri.userinfo = nil
+        uri.to_s
+      rescue URI::InvalidURIError
+        ""
+      end
+
+      def fetch(data, key)
+        data[key] || data[key.to_sym] || {}
+      end
+
+      # A collector's list, whatever the keys' type (symbols as collected, strings once stored).
+      def list(data, key)
+        Array(data[key] || data[key.to_s]).map { |entry| entry.transform_keys(&:to_sym) }
+      end
+
+      def time(value)
+        case value
+        when Numeric then Time.at(value)
+        when String then Time.iso8601(value)
+        end
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/profiler/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Profiler
-  VERSION = "0.38.0"
+  VERSION = "0.39.0"
 
   GEM_ROOT = File.expand_path("../..", __dir__)
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-profiler
 version: !ruby/object:Gem::Version
-  version: 0.38.0
+  version: 0.39.0
 platform: ruby
 authors:
 - Sébastien Duplessy
@@ -235,6 +235,9 @@ files:
 - lib/profiler/models/profile.rb
 - lib/profiler/models/sql_query.rb
 - lib/profiler/models/timeline_event.rb
+- lib/profiler/otel/scoped_id_generator.rb
+- lib/profiler/otel/sdk.rb
+- lib/profiler/otel/trace_exporter.rb
 - lib/profiler/process_snapshot.rb
 - lib/profiler/railtie.rb
 - lib/profiler/redaction.rb