feat: queue time metric

docs/platforms/ruby/common/configuration/options.mdx

@@ -326,6 +326,20 @@ config.trace_ignore_status_codes = [404, (502..511)]
 
 </SdkOption>
 
+<SdkOption name="capture_queue_time" type="Boolean" defaultValue="true">
+
+Automatically capture how long requests wait in the web server queue before processing begins. The SDK reads the `X-Request-Start` header set by reverse proxies (Nginx, HAProxy, Heroku) and attaches queue time to transactions as `http.server.request.time_in_queue`.
+
+This helps identify when requests are delayed due to insufficient worker threads or server capacity, which is especially useful under load. Learn more about <PlatformLink to="/tracing/instrumentation/performance-metrics/#automatic-queue-time-capture">automatic queue time capture</PlatformLink>.
+
+To disable queue time capture:
+
+```ruby
+config.capture_queue_time = false
+```
+
+</SdkOption>
+
 <SdkOption name="instrumenter" type="Symbol" defaultValue=":sentry">
 
 The instrumenter to use, `:sentry` or `:otel` for [use with OpenTelemetry](../../tracing/instrumentation/opentelemetry).
@@ -466,7 +480,7 @@ end
 
 <SdkOption name="spotlight" type="Boolean | String" defaultValue="false">
 
-Whether to also capture events and traces into [Spotlight](https://spotlightjs.com/setup/other/).
+Whether to also capture events and traces into [Spotlight](https://spotlightjs.com/).
 
 If you set this to true, Sentry will send events and traces to the local Sidecar proxy at `http://localhost:8969/stream`.
 

docs/platforms/ruby/common/tracing/instrumentation/automatic-instrumentation.mdx

@@ -21,4 +21,6 @@ Spans are instrumented for the following operations within a transaction:
 - Outgoing HTTP requests made with `Net::HTTP`
 - Redis operations
 
+The SDK also captures **queue time** as transaction data (not a child span) when a `X-Request-Start` header is present from your reverse proxy (Nginx, HAProxy, or Heroku). See <PlatformLink to="/tracing/instrumentation/performance-metrics/#automatic-queue-time-capture">Automatic Queue Time Capture</PlatformLink> for setup instructions.
+
 Spans are only created within an existing transaction. If you're not using any of the supported frameworks, you'll need to <PlatformLink to="/tracing/instrumentation/custom-instrumentation/">create transactions manually</PlatformLink>.

docs/platforms/ruby/common/tracing/instrumentation/performance-metrics.mdx

@@ -22,6 +22,8 @@ Sentry supports adding arbitrary custom units, but we recommend using one of the
 
 <Include name="custom-measurements-units-disclaimer.mdx" />
 
+<PlatformContent includePath="performance/queue-time-capture" />
+
 ## Supported Measurement Units
 
 Units augment measurement values by giving meaning to what otherwise might be abstract numbers. Adding units also allows Sentry to offer controls - unit conversions, filters, and so on - based on those units. For values that are unitless, you can supply an empty string or `none`.

platform-includes/performance/queue-time-capture/ruby.mdx

@@ -0,0 +1,46 @@
+## Automatic Queue Time Capture
+
+The Ruby SDK automatically captures queue time for Rack-based applications when the `X-Request-Start` header is present. This measures how long requests wait in the web server queue (e.g., waiting for a Puma thread) before your application begins processing them.
+
+Queue time is attached to transactions as the `http.server.request.time_in_queue` attribute and helps identify server capacity issues. Tracing must be enabled for queue time to be captured.
+
+### Setup
+
+Configure your reverse proxy to add the `X-Request-Start` header:
+
+**Nginx:**
+
+```nginx
+location / {
+  proxy_pass http://your-app;
+  proxy_set_header X-Request-Start "t=${msec}";
+}
+```
+
+**HAProxy:**
+
+```haproxy
+frontend http-in
+  http-request set-header X-Request-Start t=%Ts%ms
+```
+
+**Heroku:** The header is automatically set by Heroku's router.
+
+### How It Works
+
+The SDK:
+
+1. Reads the `X-Request-Start` header timestamp from your reverse proxy
+2. Calculates the time difference between the header timestamp and when the request reaches your application
+3. Subtracts `puma.request_body_wait` (if present) to exclude time spent waiting for slow client uploads
+4. Attaches the result as `http.server.request.time_in_queue` to the transaction
+
+### Disable Queue Time Capture
+
+If you don't want queue time captured, disable it in your configuration:
+
+```ruby
+Sentry.init do |config|
+  config.capture_queue_time = false
+end
+```

src/mdx.ts

@@ -268,6 +268,7 @@ export async function getDevDocsFrontMatterUncached(): Promise<FrontMatter[]> {
 
             const source = await readFile(file, 'utf8');
             const {data: frontmatter} = matter(source);
+
             return {
               ...(frontmatter as FrontMatter),
               slug: fileName.replace(/\/index.mdx?$/, '').replace(/\.mdx?$/, ''),

src/types/frontmatter.ts

@@ -39,11 +39,11 @@ export interface FrontMatter {
    * A list of keywords for indexing with search.
    */
   keywords?: string[];
+
   /**
    * Set this to true to show a "new" badge next to the title in the sidebar
    */
   new?: boolean;
-
   /**
    * The next page in the bottom pagination navigation.
    */
@@ -53,6 +53,7 @@ export interface FrontMatter {
    * takes precedence over children when present
    */
   next_steps?: string[];
+
   /**
    * Set this to true to disable indexing (robots, algolia) of this content.
    */