feat: queue time metric (#16030)

<!-- Use this checklist to make sure your PR is ready for merge. You may
delete any sections you don't need. -->

## DESCRIBE YOUR PR
docs for Ruby queue-time capture
getsentry/sentry-ruby#2838

## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [x] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

## LEGAL BOILERPLATE

<!-- Sentry employees and contractors can delete or ignore this section.
-->

Look, I get it. The entity doing business as "Sentry" was incorporated
in the State of Delaware in 2015 as Functional Software, Inc. and is
gonna need some rights from me in order to utilize my contributions in
this here PR. So here's the deal: I retain all rights, title and
interest in and to my contributions, and by keeping this boilerplate
intact I confirm that Sentry can use, modify, copy, and redistribute my
contributions, under Sentry's choice of terms.

## EXTRA RESOURCES

- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)

---------

Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 4 people

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

@@ -327,6 +327,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).
@@ -467,7 +481,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/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.
    */