devbench 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61008f8defbff11fd3e079f568739cc25114bc05fb0f8981c5084f83d4770de4
-  data.tar.gz: d0304643c20cdb7fc413771188d60ee1881ae9e760129c22fd32d63aebea0bd5
+  metadata.gz: 733817dd1561a76917c0426c041129aa4fefe9200c21ffb462bdaf60c6db801c
+  data.tar.gz: 9f17ddc4d783f8c666737406df6ddc5c79ff776b299af8b25f2e6d31b43baa9d
 SHA512:
-  metadata.gz: 8af3f77395bf0f10fddf36e0cdfcfdfd85aa2e1528d08c4abc170eeffd318021d657824d24b8f1dfb8fdba1da71b904760ffffdee84a4d50944ab63f41a3f5db
-  data.tar.gz: c59ffb19a9739467182f6e4bf15b4ad68ebeb18d2eaabb79a17b15a24de40bde6230247bc58d8085368ef7be2b562986360dd0d5e90a45334d63adf739976938
+  metadata.gz: 82993e99341857d99a11475d9805b1ba7d9dda794e5415a8b27ed121c8eb2f4c8a0ca63df58dcb89b1824a094a8d8f84cd43a1bae7e1d8aaa019e91a44827fda
+  data.tar.gz: 44038eba715ea44b2423beb8d0c763f7c20430daf272d5e82be7b5e6af1993fbc655160a4d854520d91a27c3e0da6d0185103a5b71fac2092b226cfd9886a839

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RedpointRack LLC
+
+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.

data/README.md

@@ -50,7 +50,7 @@ gem (upgrading the gem upgrades the sensor), with **only the public part**
 of `DEVBENCH_DSN`:
 
 ```html
-<script src="https://unpkg.com/devbench@0.6.0/dist/devbench.min.js"
+<script src="https://unpkg.com/devbench@0.8.0/dist/devbench.min.js"
         data-dsn="https://<public>@adt-ingest.onrender.com" data-release="<release>" defer></script>
 ```
 
@@ -76,8 +76,9 @@ All optional except the DSN.
 |---|---|---|
 | `DEVBENCH_DSN` | — (falls back to `ADT_DSN`) | `https://<public>:<secret>@<host>[:port]` from `adt dsn create`. The server authenticates with the secret; the page gets the public part. A 0.5 `https://<key>@<host>` still works (no browser tag, see below). Plain `http://` is accepted only for localhost. |
 | `DEVBENCH_SERVICE` | your app's module, underscored (`AcmeShop` → `acme_shop`); `app` outside Rails; **`<that>-sidekiq` in a Sidekiq process** | Groups this app's issues. Set it and it wins everywhere. |
-| `DEVBENCH_RELEASE` | `GIT_SHA`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`, else empty | Which deploy an occurrence came from. |
+| `DEVBENCH_RELEASE` | the first found of: a `REVISION` file in `Rails.root` (Capistrano writes one), `HEROKU_SLUG_COMMIT`, `KAMAL_VERSION`, `GITHUB_SHA`, `GIT_SHA`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`; else empty | Which deploy an occurrence came from. `c.release` in code wins over all of these. |
 | `DEVBENCH_ENABLED` | on | `false` turns everything off: no middleware, no hooks, no tag, nothing sent. |
+| `DEVBENCH_WIDGET_SECRET` | — | The chat widget's secret (`dbws_…`, from the account page). Set, signed-in pages carry the signed identity the widget needs (below). Never reaches the page. |
 
 Or from code, e.g. `config/initializers/devbench.rb`:
 
@@ -123,6 +124,39 @@ frames with paths relative to `Rails.root`, the trace, and the user.
   reporting is dropped, and the application's own exception always comes
   out unchanged.
 
+## Failed and slow requests
+
+`Devbench::Middleware` also reports what a request does *without*
+raising. Nothing to set up, and no new API:
+
+| Signal | When | Reported as |
+|---|---|---|
+| **Failed** | the app answered 500–599 and no exception was reported during the request | `http_503 at PUT DealsController#update` |
+| **Slow** | the app answered 100–499 after **more than 3 seconds** (3,000 ms exactly is not slow) | `slow_request at GET DealsController#index` |
+| **429 spike** | one action answered at least ten 429s in one minute, and at least 10% of its requests | `http_429_spike at GET DealsController#index` |
+
+- **The exception wins.** A 500 page Rails rendered for an exception, or a
+  5xx after `Rails.error.report` / `Devbench.capture_exception`, is
+  reported once, as the exception. An exception you ignore
+  (`Devbench.ignore_exceptions`) does not come back as an `http_500`. A
+  slow request is slow whatever else happened in it.
+- **`report_handled` changes nothing here:** a 5xx after it is still
+  failed, and the `x-adt-handled` header is unchanged.
+- **Other 4xx are not reported.** A 404 or 422 is a status code, not a
+  problem; only a burst of 429s is.
+- The route is Rails' `Controller#action`, never the path (paths carry
+  ids). A request no route matched, and every request in a plain Rack
+  app, is `*`. The duration runs until the app hands back its response;
+  streaming the body after that does not count, and streaming responses
+  (`text/event-stream`, a websocket upgrade, a hijacked connection) are
+  never slow.
+- Failed and slow requests carry the trace and the user; a spike, which
+  is many requests, carries neither. Spikes are counted per process
+  (each Puma worker on its own) and reported when the minute is over, at
+  the next flush, or when the process exits.
+- The 3-second threshold is the same in every Dev Bench SDK and is not a
+  setting yet.
+
 ## What is sent, and when
 
 Like the browser sensor, the gem does not send one request per error:
@@ -153,7 +187,8 @@ Triage reads the server's log lines for the user action that failed. With
 
 - **What:** every line written to `Rails.logger` and `Sidekiq.logger`
   while a request or job carries a trace (`x-adt-trace` from the browser
-  sensor; a job inherits the trace of the request that enqueued it).
+  sensor; a job inherits the trace of the request that enqueued it — see
+  [Background jobs](#background-jobs)).
   Untraced lines are not kept. Rails 7.1+: a capturing logger joins
   `Rails.logger`'s broadcast (it follows the app's level and `silence`,
   and writes nothing); older Rails and `Sidekiq.logger`: a tee after the
@@ -190,6 +225,30 @@ end
 - The middleware clears it when the request ends (Sidekiq: when the job
   ends), so the next request on the same thread never inherits it.
 
+### Chat widget identity
+
+The chat widget (off by default) is shown only to signed-in users your
+server vouches for. With `DEVBENCH_WIDGET_SECRET` set, `devbench_script_tag`
+signs the user `set_user` recorded for the request into
+`data-widget-identity`, at render time. Nothing else to write. A signed-out
+page (no `set_user`) gets no attribute and no widget.
+
+Optionally, say what this user may do in the chat:
+
+```ruby
+Devbench.set_user(email: current_user.email, account: current_dealer.id,
+                  role: current_user.role,          # your role name; mapped in the widget settings
+                  chat: [:report, :howto, :handoff]) # overrides the mapping; [] = may not chat
+```
+
+Capabilities: `:report`, `:status`, `:howto`, `:feature_requests`,
+`:handoff`. `role` and `chat` go only into the signed token, never with
+sensor data. An identity that can't be signed exactly (a field over 255
+characters, a control character such as a line break, an unknown
+capability) gets no token rather than a truncated one, and one
+`[devbench]` warning. Pages carrying a token are
+per-user: don't serve them from a shared cache.
+
 ## Reporting what you caught
 
 An exception you rescued but want seen, like Sentry's `capture_exception`:
@@ -216,6 +275,25 @@ browser already knows whether the user was shown an error; this is the one
 fact it cannot know on its own. The header carries a count and nothing else,
 and it is added even when reporting is down.
 
+## Background jobs
+
+A job inherits the trace of the request that enqueued it, so its failure
+and its log lines join the user action that caused them:
+
+- **ActiveJob, on any adapter** — Solid Queue (Rails 8's default), GoodJob,
+  Sidekiq, Resque, Delayed Job, `:async`, `:inline` and the rest. The trace
+  rides in the job's own payload (`"adt_trace"`), so it survives the queue,
+  a process restart and `retry_on`. Nothing to add: the Railtie installs it.
+  ActiveJob without Rails: `Devbench::ActiveJobHooks.install(ActiveJob::Base)`.
+- **Native Sidekiq jobs** (`Sidekiq::Job`), below.
+
+The trace is the request's, unchanged; the job's identity is its own
+(`set_user` inside the job; it ends with the job, and a worker thread's
+previous job never lends it one). A job enqueued outside a request runs
+untraced, as does one enqueued by an earlier version of this gem. On Sidekiq, an
+ActiveJob job runs inside the Sidekiq middleware's scope — traced once, not
+twice — and `:inline` runs inside the request's.
+
 ## Sidekiq
 
 Under Rails there is nothing to add: the Railtie installs the hooks at boot
@@ -244,7 +322,8 @@ use Devbench::Middleware   # Rack
 ```
 
 Everything else (`set_user`, `capture_exception`, `report_handled`, the
-DSN) works the same.
+DSN, failed and slow requests) works the same. Plain Rack has no route
+pattern, so failed and slow requests are reported under the route `*`.
 
 ## Trace propagation
 

data/lib/devbench/active_job_hooks.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'trace'
+require_relative 'current'
+
+module Devbench
+  # Carries the request's trace into ActiveJob jobs on every adapter (Solid
+  # Queue, GoodJob, async, inline, Sidekiq, ...), so a job's failure and its
+  # log lines join the user action that enqueued it (docs/server-sdk/trace-propagation.md,
+  # Capability 1; README "Server log lines").
+  #
+  # The trace travels inside the job's own serialized payload, which every
+  # adapter stores and hands back verbatim to ActiveJob::Base.execute:
+  #
+  #   * serialize   — adds "adt_trace": the trace the job already carries (a
+  #                   job re-enqueued by retry_on keeps the request it came
+  #                   from), else the active one. Unchanged, as the Sidekiq
+  #                   client middleware carries it: a job is the same
+  #                   service, not a downstream hop.
+  #   * deserialize — reads it back. A payload from an older gem has no key:
+  #                   the job runs untraced.
+  #   * perform_now — a job that came through deserialize runs inside
+  #                   Current.with(its trace), outermost (before ActiveJob's
+  #                   logging and instrumentation), so the perform.active_job
+  #                   report and every line the job logs carry it; the
+  #                   thread's previous trace and identity come back after.
+  #                   Identity is scoped to the job, never inherited from the
+  #                   thread (a pool thread's last job is not this job's user).
+  #
+  # Not twice: a job that runs inside a scope already open on its thread —
+  # Sidekiq's server middleware (which scoped the trace from the outer job
+  # hash), or the request whose inline adapter runs it — belongs to that
+  # scope and opens no second one, unless it carries a different trace. A
+  # job built and run with perform_now (never serialized) is left alone: it
+  # runs in its caller's context.
+  #
+  # Plain Ruby: no ActiveJob constant is named at load time. The Railtie
+  # installs it with ActiveSupport.on_load(:active_job); ActiveJob without
+  # Rails calls Devbench::ActiveJobHooks.install(ActiveJob::Base). Every
+  # override is guarded: the job's own behaviour and its own exception are
+  # what come out, whatever happens in here.
+  module ActiveJobHooks
+    # The payload key, the same one Sidekiq jobs carry. ActiveJob ignores
+    # keys it does not know, so payloads stay readable by apps without the gem.
+    TRACE_KEY = 'adt_trace'
+
+    # Prepended to ActiveJob::Base.
+    module Job
+      def serialize
+        payload = super
+        ActiveJobHooks.tag(self, payload)
+        payload
+      end
+
+      def deserialize(job_data)
+        super
+        ActiveJobHooks.read(self, job_data)
+      end
+
+      def perform_now
+        trace = ActiveJobHooks.scope_for(self)
+        return super if trace == :none
+
+        Current.with(trace) { super }
+      end
+    end
+
+    class << self
+      # Prepends the hooks to ActiveJob::Base (or any class with its
+      # serialize/deserialize/perform_now). Safe to call more than once.
+      # Returns true when installed.
+      def install(base)
+        return false unless base.is_a?(Class) && base.method_defined?(:serialize)
+
+        base.prepend(Job) unless base <= Job
+        true
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      # Adds the trace to a payload being built by serialize, and remembers
+      # it on the job so a later serialize (a retry) carries the same one.
+      def tag(job, payload)
+        return nil unless payload.is_a?(Hash)
+
+        trace = job.instance_variable_get(:@devbench_trace)
+        trace ||= Current.trace&.to_s
+        return nil if trace.nil?
+
+        job.instance_variable_set(:@devbench_trace, trace)
+        payload[TRACE_KEY] = trace
+        nil
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      def read(job, job_data)
+        trace = job_data.is_a?(Hash) ? Trace.parse(job_data[TRACE_KEY]) : nil
+        job.instance_variable_set(:@devbench_trace, trace&.to_s)
+        job.instance_variable_set(:@devbench_deserialized, true)
+        nil
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # The trace perform_now runs the job under, or :none to leave the
+      # thread's context as it is.
+      def scope_for(job)
+        return :none unless job.instance_variable_get(:@devbench_deserialized)
+
+        trace = Trace.parse(job.instance_variable_get(:@devbench_trace))
+        return trace unless Current.scoped?
+        return :none if trace.nil? || Current.trace&.to_s == trace.to_s
+
+        trace
+      rescue StandardError, SystemStackError
+        :none
+      end
+    end
+  end
+end

data/lib/devbench/config.rb

@@ -3,7 +3,7 @@
 require 'uri'
 
 module Devbench
-  # Where reports go, parsed from DEVBENCH_DSN (docs/SERVER_SDK_SPEC.md, "Dev
+  # Where reports go, parsed from DEVBENCH_DSN (docs/server-sdk/configuration.md, "Dev
   # Bench naming and configuration"; DECISIONS #161):
   #
   #   https://<public>:<secret>@<host>[:port]    from `adt dsn create`
@@ -109,11 +109,20 @@ module Devbench
   #                      module, underscored (AcmeShop -> acme_shop);
   #                      else "app"; with "-sidekiq" appended in a
   #                      Sidekiq process.
-  #   DEVBENCH_RELEASE   the deployed version. Default: GIT_SHA,
-  #                      SOURCE_VERSION, RENDER_GIT_COMMIT, else "".
+  #   DEVBENCH_RELEASE   the deployed version. Default, first found: the
+  #                      REVISION file in the app root (Capistrano),
+  #                      HEROKU_SLUG_COMMIT, KAMAL_VERSION, GITHUB_SHA,
+  #                      GIT_SHA, SOURCE_VERSION, RENDER_GIT_COMMIT,
+  #                      else "".
   #   DEVBENCH_ENABLED   "false" turns everything off.
   class Configuration
-    RELEASE_FALLBACKS = %w[GIT_SHA SOURCE_VERSION RENDER_GIT_COMMIT].freeze
+    # Tried in order after the REVISION file when no release is configured.
+    # Common deploy tools and platforms only; never an app's own variable.
+    RELEASE_FALLBACKS = %w[HEROKU_SLUG_COMMIT KAMAL_VERSION GITHUB_SHA GIT_SHA SOURCE_VERSION RENDER_GIT_COMMIT].freeze
+    # Capistrano writes the deployed commit here, in the release's root.
+    REVISION_FILE = 'REVISION'
+    # A commit or tag, not a document: read no more than this.
+    REVISION_MAX_BYTES = 255
     OFF = %w[false 0 no off].freeze
 
     # Strings, or nil for "not set".
@@ -121,12 +130,17 @@ module Devbench
     # Seconds between background flushes in direct mode (spec: 60).
     attr_accessor :flush_interval
     attr_writer :enabled
+    # The tenant's chat widget secret (dbws_…, DEVBENCH_WIDGET_SECRET), or
+    # nil. Signs the widget identity on the browser tag; never leaves the
+    # server.
+    attr_accessor :widget_secret
 
     def initialize(env = ENV)
       @dsn = presence(env['DEVBENCH_DSN']) || presence(env['ADT_DSN'])
       @service = presence(env['DEVBENCH_SERVICE'])
-      @release = presence(env['DEVBENCH_RELEASE']) ||
-                 RELEASE_FALLBACKS.lazy.map { |name| presence(env[name]) }.find(&:itself)
+      @release = presence(env['DEVBENCH_RELEASE'])
+      @widget_secret = presence(env['DEVBENCH_WIDGET_SECRET'])
+      @release_env = RELEASE_FALLBACKS.lazy.map { |name| presence(env[name]) }.find(&:itself)
       @enabled = !OFF.include?(env['DEVBENCH_ENABLED'].to_s.strip.downcase)
       @flush_interval = 60
     end
@@ -149,12 +163,40 @@ module Devbench
       sidekiq_server? ? "#{base}-sidekiq" : base
     end
 
+    # The release sent with every flush and on the browser tag. Explicit
+    # (configure or DEVBENCH_RELEASE) wins; else the REVISION file, read
+    # once reporting starts (after Rails has booted, so Rails.root is
+    # known); else the deploy variables in RELEASE_FALLBACKS order; else "".
     def resolved_release
-      @release.to_s
+      explicit = presence(@release)
+      return explicit if explicit
+
+      @detected_release ||= (revision_file_release || @release_env).to_s
     end
 
     private
 
+    # The first line of <app root>/REVISION, or nil when there is none or it
+    # cannot be read. The app root is Rails.root, else the working directory.
+    def revision_file_release
+      path = File.join(app_root, REVISION_FILE)
+      return nil unless File.file?(path)
+
+      presence(File.open(path, 'rb') { |f| f.read(REVISION_MAX_BYTES) }.to_s.lines.first)
+    rescue StandardError
+      nil
+    end
+
+    def app_root
+      if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+        ::Rails.root.to_s
+      else
+        Dir.pwd
+      end
+    rescue StandardError
+      Dir.pwd
+    end
+
     def sidekiq_server?
       defined?(::Sidekiq) && ::Sidekiq.respond_to?(:server?) && ::Sidekiq.server? ? true : false
     rescue StandardError, SystemStackError

data/lib/devbench/current.rb

@@ -10,6 +10,9 @@ module Devbench
     KEY = :__adt_trace
     HANDLED_KEY = :__adt_handled
     USER_KEY = :__adt_user
+    WIDGET_USER_KEY = :__adt_widget_user
+    SCOPE_KEY = :__adt_scope
+    EXCEPTION_KEY = :__adt_exception_reported
 
     # Counts failures handled during this request.
     #
@@ -24,6 +27,18 @@ module Devbench
       Thread.current[HANDLED_KEY] = handled_count + 1
     end
 
+    # Whether an `exception` was reported during this scope (any context:
+    # request, rails_error, job, explicit). A 5xx after one is not also a
+    # `failed` request: the exception is the report (Capability 2b). A
+    # handled failure (report_handled) does not set it.
+    def self.exception_reported?
+      Thread.current[EXCEPTION_KEY] == true
+    end
+
+    def self.record_exception
+      Thread.current[EXCEPTION_KEY] = true
+    end
+
     # Who this request is for, as set by Devbench.set_user: a frozen hash with
     # :email and/or :account, or nil. Normalised before it gets here.
     def self.user
@@ -34,6 +49,17 @@ module Devbench
       Thread.current[USER_KEY] = value
     end
 
+    # The raw identity, role and chat permission Devbench.set_user was given,
+    # for the chat widget's signed token (Devbench::WidgetIdentity); nil when
+    # no user is set. Never sent with sensor data.
+    def self.widget_user
+      Thread.current[WIDGET_USER_KEY]
+    end
+
+    def self.widget_user=(value)
+      Thread.current[WIDGET_USER_KEY] = value
+    end
+
     def self.trace
       Thread.current[KEY]
     end
@@ -42,6 +68,14 @@ module Devbench
       Thread.current[KEY] = value
     end
 
+    # True while a scope (Current.with: a request in the middleware, a
+    # Sidekiq job, an ActiveJob job) is open on this thread, traced or not.
+    # An ActiveJob job run inside one (the inline adapter in a request,
+    # ActiveJob on Sidekiq) belongs to it and opens no second scope.
+    def self.scoped?
+      Thread.current[SCOPE_KEY] == true
+    end
+
     # Runs the block with trace active, restoring whatever was there before.
     #
     # Restores rather than clearing, because servers reuse threads: clearing
@@ -50,7 +84,11 @@ module Devbench
       previous = Thread.current[KEY]
       previous_handled = Thread.current[HANDLED_KEY]
       previous_user = Thread.current[USER_KEY]
+      previous_widget_user = Thread.current[WIDGET_USER_KEY]
+      previous_scope = Thread.current[SCOPE_KEY]
+      previous_exception = Thread.current[EXCEPTION_KEY]
       Thread.current[KEY] = trace
+      Thread.current[SCOPE_KEY] = true
       # Reset rather than inherit: servers reuse threads, and carrying a count
       # across requests would mark an innocent response as having swallowed
       # the previous request's failure.
@@ -58,17 +96,28 @@ module Devbench
       # Same for identity, and more so: inheriting it would attribute one
       # user's failure to whoever this thread served before.
       Thread.current[USER_KEY] = nil
+      Thread.current[WIDGET_USER_KEY] = nil
+      Thread.current[EXCEPTION_KEY] = nil
       yield
     ensure
+      # An exception reported in a nested scope (a second middleware, a job
+      # run inside the request) was reported during the enclosing one too.
+      nested_exception = previous_scope == true && Thread.current[EXCEPTION_KEY] == true
+      Thread.current[EXCEPTION_KEY] = nested_exception ? true : previous_exception
       Thread.current[KEY] = previous
       Thread.current[HANDLED_KEY] = previous_handled
       Thread.current[USER_KEY] = previous_user
+      Thread.current[WIDGET_USER_KEY] = previous_widget_user
+      Thread.current[SCOPE_KEY] = previous_scope
     end
 
     def self.clear
       Thread.current[KEY] = nil
       Thread.current[HANDLED_KEY] = nil
       Thread.current[USER_KEY] = nil
+      Thread.current[WIDGET_USER_KEY] = nil
+      Thread.current[SCOPE_KEY] = nil
+      Thread.current[EXCEPTION_KEY] = nil
     end
   end
 end

data/lib/devbench/direct.rb

@@ -8,9 +8,10 @@ require_relative 'fingerprint'
 require_relative 'scrub'
 require_relative 'egress_policy'
 require_relative 'logs'
+require_relative 'request_signals'
 
 module Devbench
-  # Direct mode (docs/SERVER_SDK_SPEC.md, "Direct mode"): fingerprint and
+  # Direct mode (docs/server-sdk/transports.md, "Direct mode"): fingerprint and
   # count in-process, flush counts to ingest once a minute, upload one
   # redacted evidence bundle per fingerprint only when ingest asks, and
   # answer ingest's requests for the log lines of a trace (need_logs) from
@@ -176,9 +177,26 @@ module Devbench
       case payload[:kind]
       when 'exception' then exception_signal(payload)
       when 'handled_failure' then handled_signal(payload)
+      when 'request' then request_signal(payload)
       end
     end
 
+    # recordRequest (internal/reqsignal): {error|degradation, server,
+    # service, http_<status>|slow_request|http_429_spike, "<METHOD> <route>"},
+    # no frames. A signal/status pair the sidecar would drop is dropped.
+    def request_signal(payload)
+      built = RequestSignals.build(signal: payload[:signal], method: payload[:method], route: payload[:route],
+                                   status: payload[:status], duration_ms: payload[:duration_ms],
+                                   count: payload[:count], total: payload[:total])
+      return nil if built.nil?
+
+      fp = Fingerprint.compute(kind: built.kind, source: 'server', service: @service,
+                               type: built.type, message: built.message)
+      return nil if fp.nil?
+
+      Signal.new(fp, built.kind, built.text, user(payload[:user]), [], built.exemplar)
+    end
+
     # recordException: {error, server, service, type, message[0,2000], frames}.
     def exception_signal(payload)
       type = payload[:error].to_s
@@ -338,6 +356,9 @@ module Devbench
     # (a rule arriving with a request for the shape it governs applies to
     # that request), then log slices, then evidence.
     def flush_cycle(deadline)
+      # A 429 spike window the clock has left closes at a flush: counted
+      # here, so it goes out with this one.
+      RequestSignals.tick!(self)
       counts, overflowed = @lock.synchronize do
         taken = [@window, @overflowed]
         @window = {}
@@ -406,9 +427,14 @@ module Devbench
       out
     end
 
+    # Which SDK sent a flush, on every request of it (#308): counts, each
+    # request of a split window and the empty poll are all built here.
+    SDK_FIELD = { name: SDK_NAME, version: VERSION }.freeze
+    private_constant :SDK_FIELD
+
     def envelope(counts, overflowed)
-      body = { v: 1, tenant: '', source: 'server', service: @service, release: @release,
-               sensor_id: @sensor_id, counts: counts }
+      body = { v: PROTOCOL_VERSION, tenant: '', source: 'server', service: @service, release: @release,
+               sensor_id: @sensor_id, sdk: SDK_FIELD, counts: counts }
       body[:overflowed] = overflowed if overflowed.positive?
       JSON.generate(body)
     end
@@ -543,7 +569,7 @@ module Devbench
       return nil if detail.nil?
 
       bundle = {
-        v: 1, fp: fp, kind: detail.kind,
+        v: PROTOCOL_VERSION, fp: fp, kind: detail.kind,
         template: Scrub.template_text(detail.text, @policy, fp), service: @service,
         exemplars: detail.exemplar.empty? ? [] : [Scrub.egress(detail.exemplar, @policy, @service)]
       }

data/lib/devbench/identity.rb

@@ -3,7 +3,7 @@
 require_relative 'current'
 
 module Devbench
-  # Who was affected (docs/SERVER_SDK_SPEC.md, Capability 5).
+  # Who was affected (docs/server-sdk/identity.md, Capability 5).
   #
   # Identity travels in its own field of every control message and nowhere
   # else: never in a message, a symbol or a log line, so it can never move a
@@ -44,8 +44,22 @@ module Devbench
   #
   # Each field is optional. Calling again replaces the whole identity, and
   # calling with neither clears it. Never raises.
-  def self.set_user(email: nil, account: nil)
-    Current.user = Identity.normalize(email, account)
+  #
+  # role: and chat: are for the chat widget only (docs/server-sdk/chat-widget.md,
+  # Capability 6): devbench_script_tag signs them, with the email and
+  # account, into the widget's identity token when DEVBENCH_WIDGET_SECRET is
+  # set. They are never sent with sensor data. role is the app's own role
+  # name for the user (mapped to chat capabilities in the tenant's settings);
+  # chat, when given, overrides that mapping: a list of capabilities
+  # (:report, :status, :howto, :feature_requests, :handoff), [] for "may not
+  # chat", nil (the default) for "not stated".
+  def self.set_user(email: nil, account: nil, role: nil, chat: nil)
+    user = Identity.normalize(email, account)
+    Current.user = user
+    # The raw values, not the sensor identity's truncated ones: the widget
+    # signer refuses what it cannot sign exactly instead of signing a
+    # different person.
+    Current.widget_user = user && { email: email, account: account, role: role, chat: chat.is_a?(Array) ? chat.dup.freeze : chat }.freeze
     nil
   rescue StandardError, SystemStackError
     nil