docs(nextjs): Add Next.js-specific metrics documentation #15997

sergical · 2026-01-13T16:08:15Z

Closes https://linear.app/getsentry/issue/DEVEX-227/metrics

Summary

Creates dedicated metrics guide for Next.js
Shows patterns for API routes, Server Actions, and middleware
Includes attribute best practices
Follows the logs/tracing doc pattern with SplitLayout

Why Override?

The common metrics doc shows generic JavaScript examples. This override adds:

Next.js-specific patterns (Server Actions, middleware)
Runtime context (works in client/server/edge)
Practical examples developers can copy

Test plan

Verify page renders at /platforms/javascript/guides/nextjs/metrics/
Check SplitLayout renders correctly
Verify beta badge appears

🤖 Generated with Claude Code

vercel · 2026-01-13T16:08:18Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
develop-docs	Ready	Preview, Comment	Jan 15, 2026 8:27pm
sentry-docs	Ready	Preview, Comment	Jan 15, 2026 8:27pm

docs/platforms/javascript/guides/nextjs/metrics/index.mdx

+export function middleware(request: NextRequest) {
+  Sentry.metrics.count("requests", 1, {
+    attributes: {
+      path: request.nextUrl.pathname,
+      method: request.method,
+    },
+  });


docs/platforms/javascript/guides/nextjs/metrics/index.mdx

+```typescript
+Sentry.metrics.count("api_calls", 1, {
+  attributes: {
+    endpoint: "/api/orders",
+    user_tier: "pro",
+    region: "us-west",
+    user_id: user.id,
+    order_id: order.id,
+  },
+});


linear · 2026-01-14T19:25:19Z

DEVEX-227 Metrics

chargome

I love the change! I would just rather not have different versions of the metrics documentation for js out there as we would have to maintain them all, wdyt of rolling this out for all js docs and just adding the "Nextjs Patterns" part specifically here?

chargome · 2026-01-15T09:03:36Z

docs/platforms/javascript/guides/nextjs/metrics/index.mdx

+|------|---------|
+| `count` | Events (orders, clicks, API calls) |
+| `gauge` | Current values (queue depth, connections) |
+| `distribution` | Value ranges (response times, payload sizes) |


The distribution part does not break well on smaller displays:

sfanahata · 2026-01-15T18:41:00Z

docs/platforms/javascript/guides/nextjs/metrics/index.mdx

+beta: true
+---
+
+Sentry Metrics let you track custom application data beyond errors and traces. Track business metrics like orders processed, API response times, or cache hit rates across all Next.js runtimes.


Suggested change

Sentry Metrics let you track custom application data beyond errors and traces. Track business metrics like orders processed, API response times, or cache hit rates across all Next.js runtimes.

[Sentry Metrics](/product/explore/metrics/) let you track custom application data beyond errors and traces. Track business metrics like orders processed, API response times, or cache hit rates across all Next.js runtimes.

We say almost nothing about the value prop of this feature here. We need to at least link out to the product docs.

sfanahata · 2026-01-15T18:43:04Z

docs/platforms/javascript/guides/nextjs/metrics/index.mdx

+
+## Options
+
+Configure these options in **all three runtime files** (`instrumentation-client.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`).


Are we assuming that of someone has gotten this far, they know about the config of these files already? Is there something we could link to that references the sentry-specific config files?

sfanahata · 2026-01-15T18:43:54Z

docs/platforms/javascript/guides/nextjs/metrics/index.mdx

+
+### Flush Metrics
+
+Metrics are buffered and sent periodically. To flush immediately:


Suggested change

Metrics are buffered and sent periodically. To flush immediately:

Metrics are buffered and sent periodically. Use this snippet ot flush immediately -

sfanahata · 2026-01-15T18:45:07Z

docs/platforms/javascript/guides/nextjs/metrics/index.mdx

+**If user is set:**
+- `user.id`, `user.name`, `user.email`
+
+**Client-side:**
+- `browser.name`, `browser.version`, `sentry.replay_id`
+
+**Server-side:**
+- `server.address`
+


I can't tell why these are formatted differently. I'd add them to the table above and just have a note for "if user is set", "client-side", "server-side".

sfanahata

@chargome has a good point. This shouldn't be a blocker, per say, but could this be the common file with nextjs-specific references inserted in through includes?

Creates a dedicated metrics guide showing: - Metric types (count, gauge, distribution) - Next.js patterns (API routes, Server Actions, middleware) - Attribute best practices (avoid high-cardinality) - Quick reference tables Follows technical-docs skill principles: concise, pattern-focused, no redundant API documentation. Co-Authored-By: Claude Opus 4.5 <[email protected]>

@chargome

- Move metrics content to common JS doc with SplitLayout format - Add Next.js-specific patterns as platform include - Delete dedicated Next.js metrics page (content now in common + includes) - Fix CSS width constraint to only apply on 1800px+ screens - Add link to product docs in intro - Consolidate Default Attributes into single table - Rename Requirements to Prerequisites with getting started link Addresses PR feedback from @chargome and @sfanahata Co-Authored-By: Claude Opus 4.5 <[email protected]>

Move inline SplitLayout content from common metrics doc to platform-include files where it belongs. This follows the docs architecture pattern and restores the original SEO description and alert text. Changes: - Restore common doc to use <PlatformContent> for usage/options/default-attributes - Move SplitLayout components to platform-includes/metrics/usage/javascript.mdx - Move options SplitLayout to platform-includes/metrics/options/javascript.mdx - Consolidate default-attributes into a cleaner table format Co-Authored-By: Claude <[email protected]>

Co-Authored-By: Claude <[email protected]>

- First/middle columns now use white-space: nowrap to keep config names, options, and short values compact - Only last column allows word-break for long descriptions - Revert SplitLayout styles to original 80% max-width with mobile override Co-Authored-By: Claude <[email protected]>

Restore documentation for using getGlobalScope() and withScope() to set attributes that apply to all metrics (10.33.0+). Co-Authored-By: Claude <[email protected]>

- Add display: block and overflow-x: auto for horizontal scroll - Add min-width: 200px to last column to prevent squishing Co-Authored-By: Claude <[email protected]>

sentry · 2026-01-15T20:20:06Z

src/components/docPage/type.scss

+    display: block;
+    overflow-x: auto;


Bug: Setting display: block on <table> elements makes the border-collapse: collapse rule ineffective, causing incorrect border rendering and accessibility issues.
_{Severity: HIGH}

Suggested Fix

To enable horizontal scrolling, wrap the <table> element in a container <div> and apply overflow-x: auto to the wrapper. Remove the display: block style from the table element itself to ensure border-collapse and other table-specific properties function correctly.

Prompt for AI Agent

Review the code at the location below. A potential bug has been identified by an AI agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not valid. Location: src/components/docPage/type.scss#L192-L193 Potential issue: In `src/components/docPage/type.scss`, setting `display: block` on `<table>` elements is incompatible with the `border-collapse: collapse` property that is also being applied. The `border-collapse` property only works on elements with `display: table` or `display: inline-table`. Consequently, browsers will ignore the `border-collapse` rule, causing table borders to render incorrectly (separated instead of merged). This change will also negatively impact accessibility by altering the semantic structure of tables for screen readers, and may lead to inconsistent column width rendering.

_{Did we get this right? 👍 / 👎 to inform future reviews.}

sentry bot reviewed Jan 13, 2026

View reviewed changes

vercel bot deployed to Preview – sentry-docs January 13, 2026 16:18 View deployment

sergical force-pushed the docs/nextjs-metrics-override branch from 5348649 to 8d64886 Compare January 13, 2026 16:33

vercel bot deployed to Preview – sentry-docs January 13, 2026 16:44 View deployment

sergical force-pushed the docs/nextjs-metrics-override branch from 8d64886 to c64b50e Compare January 13, 2026 17:55

sentry bot reviewed Jan 13, 2026

View reviewed changes

vercel bot deployed to Preview – sentry-docs January 13, 2026 18:05 View deployment

sergical force-pushed the docs/nextjs-metrics-override branch from c64b50e to deec4c2 Compare January 13, 2026 19:39

vercel bot deployed to Preview – sentry-docs January 13, 2026 19:49 View deployment

sergical force-pushed the docs/nextjs-metrics-override branch 2 times, most recently from 032051d to c17a4f9 Compare January 13, 2026 20:13

vercel bot deployed to Preview – sentry-docs January 13, 2026 20:23 View deployment

sergical requested a review from sfanahata January 13, 2026 20:57

chargome reviewed Jan 15, 2026

View reviewed changes

sfanahata reviewed Jan 15, 2026

View reviewed changes

vercel bot deployed to Preview – develop-docs January 15, 2026 19:29 View deployment

vercel bot deployed to Preview – sentry-docs January 15, 2026 19:34 View deployment

sergical and others added 5 commits January 15, 2026 14:47

docs(metrics): Add link to supported units documentation

98eb8be

Co-Authored-By: Claude <[email protected]>

sergical force-pushed the docs/nextjs-metrics-override branch from d9586fd to 4fd3901 Compare January 15, 2026 19:48

docs(metrics): Add scope attributes section back

62ccd3a

Restore documentation for using getGlobalScope() and withScope() to set attributes that apply to all metrics (10.33.0+). Co-Authored-By: Claude <[email protected]>

vercel bot deployed to Preview – sentry-docs January 15, 2026 20:02 View deployment

fix(styles): Add table horizontal scroll and last column min-width

05a4343

- Add display: block and overflow-x: auto for horizontal scroll - Add min-width: 200px to last column to prevent squishing Co-Authored-By: Claude <[email protected]>

sergical force-pushed the docs/nextjs-metrics-override branch from 8f48c0c to 05a4343 Compare January 15, 2026 20:17

sentry bot reviewed Jan 15, 2026

View reviewed changes

vercel bot deployed to Preview – develop-docs January 15, 2026 20:22 View deployment

vercel bot deployed to Preview – sentry-docs January 15, 2026 20:27 View deployment

sergical requested review from chargome and sfanahata January 15, 2026 21:06

	Sentry Metrics let you track custom application data beyond errors and traces. Track business metrics like orders processed, API response times, or cache hit rates across all Next.js runtimes.
	[Sentry Metrics](/product/explore/metrics/) let you track custom application data beyond errors and traces. Track business metrics like orders processed, API response times, or cache hit rates across all Next.js runtimes.


		## Options

		Configure these options in all three runtime files (`instrumentation-client.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`).


		### Flush Metrics

		Metrics are buffered and sent periodically. To flush immediately:

Uh oh!

docs(nextjs): Add Next.js-specific metrics documentation #15997

Are you sure you want to change the base?

docs(nextjs): Add Next.js-specific metrics documentation #15997

Uh oh!

Conversation

sergical commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why Override?

Test plan

Uh oh!

vercel bot commented Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

linear bot commented Jan 14, 2026

Uh oh!

chargome left a comment

Choose a reason for hiding this comment

Uh oh!

chargome Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

sfanahata Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

sfanahata Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

sfanahata Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

sfanahata Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

sfanahata left a comment

Choose a reason for hiding this comment

Uh oh!

sentry bot Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sergical commented Jan 13, 2026 •

edited

Loading

vercel bot commented Jan 13, 2026 •

edited

Loading