diff --git a/docs/platforms/ruby/common/configuration/options.mdx b/docs/platforms/ruby/common/configuration/options.mdx
index 9dc805338fe14..a53d63cd9f20c 100644
--- a/docs/platforms/ruby/common/configuration/options.mdx
+++ b/docs/platforms/ruby/common/configuration/options.mdx
@@ -326,6 +326,20 @@ config.trace_ignore_status_codes = [404, (502..511)]
+
+
+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 automatic queue time capture.
+
+To disable queue time capture:
+
+```ruby
+config.capture_queue_time = false
+```
+
+
+
The instrumenter to use, `:sentry` or `:otel` for [use with OpenTelemetry](../../tracing/instrumentation/opentelemetry).
@@ -466,7 +480,7 @@ end
-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`.
diff --git a/docs/platforms/ruby/common/tracing/instrumentation/automatic-instrumentation.mdx b/docs/platforms/ruby/common/tracing/instrumentation/automatic-instrumentation.mdx
index 06e5c62996a28..4b510f2712a4a 100644
--- a/docs/platforms/ruby/common/tracing/instrumentation/automatic-instrumentation.mdx
+++ b/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 Automatic Queue Time Capture 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 create transactions manually.
diff --git a/docs/platforms/ruby/common/tracing/instrumentation/performance-metrics.mdx b/docs/platforms/ruby/common/tracing/instrumentation/performance-metrics.mdx
index 8955adc964609..ab8c95a9b51ee 100644
--- a/docs/platforms/ruby/common/tracing/instrumentation/performance-metrics.mdx
+++ b/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
+
+
## 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`.
diff --git a/platform-includes/performance/queue-time-capture/ruby.mdx b/platform-includes/performance/queue-time-capture/ruby.mdx
new file mode 100644
index 0000000000000..799e33464d2df
--- /dev/null
+++ b/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
+```
diff --git a/src/mdx.ts b/src/mdx.ts
index 5a3087cfbe91f..fd0842147040c 100644
--- a/src/mdx.ts
+++ b/src/mdx.ts
@@ -268,6 +268,7 @@ export async function getDevDocsFrontMatterUncached(): Promise {
const source = await readFile(file, 'utf8');
const {data: frontmatter} = matter(source);
+
return {
...(frontmatter as FrontMatter),
slug: fileName.replace(/\/index.mdx?$/, '').replace(/\.mdx?$/, ''),
diff --git a/src/types/frontmatter.ts b/src/types/frontmatter.ts
index a336bcefefe48..aed7608e1ec61 100644
--- a/src/types/frontmatter.ts
+++ b/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.
*/