# Build a dashboard and alert from Next.js custom metrics

> Emit a custom metric from your Next.js app, build a dashboard around it, and add a threshold or anomaly-detection alert that fires the moment it drifts.

**URL:** https://sentry.io/cookbook/custom-metrics-dashboard-alerts-nextjs/

---

Emit one custom metric from a Next.js Server Action, then turn it into a dashboard widget and a threshold or anomaly alert that fires the moment things drift — trace-connected, so a spike is one click from the request behind it.

**Time:** 20-25 minutes | **Difficulty:** Intermediate

## What You'll Learn

- Emitted a custom counter metric from a Next.js Server Action with business-context attributes

- Explored metric values, aggregations, and trace-connected samples in the Metrics explorer

- Built a dashboard widget from a saved metric query

- Created a static threshold alert routed to your team's channels

- Compared static thresholds with anomaly detection so you know which to reach for

**Topics:** Metrics, Dashboards, Alerts

**SDKs:** Next.js

## Steps

### 1. Install the Sentry Next.js SDK

Add the Sentry SDK to your project with the wizard, which wires up the instrumentation files automatically. Run this in your project root. Metrics are on by default in `@sentry/nextjs` `10.25.0` and later, so there's nothing extra to enable. If you ever need to turn them off, set `enableMetrics: false` in your `Sentry.init` config.

### 2. Emit a custom metric from your app

Pick a signal that maps to something your team cares about, then emit it from the exact code path where it happens. Use `Sentry.metrics.count()` for events you tally and `Sentry.metrics.distribution()` for values you'll want percentiles on later.

The example below is from a Next.js conference-scheduler app: every time a user adds or removes a talk, it counts a `schedule.event` and attaches `action` and `result` attributes so you can slice by outcome. Both logs and metrics are high-cardinality wide events, so adding more attributes costs nothing and gives you more ways to query, group, and alert later. For values where you want a p95, emit a distribution instead, for example `Sentry.metrics.distribution("ai.tokens.total", totalTokens)`.

### 3. Explore your metric in the Metrics explorer

Trigger the code path a few times, then open the [Metrics explorer](https://sentry.io/orgredirect/organizations/:orgslug/explore/metrics/). Select `schedule.event`, choose an aggregation like `sum` or `per_minute`, and group by the `result` attribute to see successes, duplicates, and failures split out.

Open the **Samples** tab to see individual metric events, each with a direct link to its trace, so a suspicious number is one click away from the request behind it.

### 4. Build a dashboard around your metric

Once the query in the explorer shows what you want, open the **Save As** menu and pin it as a dashboard widget. Head to [Dashboards](https://sentry.io/orgredirect/organizations/:orgslug/dashboards/) to add it to a new or existing dashboard, then drop in a second widget for another signal (like `ai.tokens.total` at p95, or `page.view` throughput) so related metrics sit side by side.

A good starter layout: schedule events over time grouped by result, plus a throughput or latency widget next to it.

### 5. Add a threshold alert

From the metric query, use the **Save As** menu to turn it into a Monitor (or head to [Alerts](https://sentry.io/orgredirect/organizations/:orgslug/monitors/alerts/) and create one). Pick **Threshold** as the detection method and set a number you understand: for a free AI assistant, that might be `ai.tokens.total` summed above a cost ceiling per hour; for the scheduler, `schedule.event` where `result` is not `success` above N per hour. Route the notification to Slack, PagerDuty, or email so the right people hear about it.

Static thresholds are the right call when you already know the number that means trouble, like a spend cap or an SLO you've committed to.

### 6. Switch to anomaly detection when you don't have a baseline

When you don't yet know what "normal" looks like, a static threshold either fires all night or sleeps through daytime spikes. Create a second alert and pick **Anomaly** as the detection method instead. Sentry learns your metric's seasonality and daily or weekly patterns, then flags deviations with no threshold to tune, just a sensitivity slider. Throughput metrics like `page.view` are a perfect fit, since traffic naturally rises and falls through the day.

Reach for anomaly detection on new metrics or anything with a strong daily rhythm, and keep static thresholds for hard limits you've explicitly agreed to.

## FAQ

**Do I need to configure anything to turn metrics on?**

No. Metrics are on by default in @sentry/nextjs version 10.25.0 and later. If you want to turn them off, set enableMetrics: false in your Sentry.init config.

**Counter, gauge, or distribution: which should I use?**

Use a counter for things you tally, like schedule events or requests. Use a gauge for a point-in-time value that goes up and down, like queue depth. Use a distribution for values you want percentiles on, like token usage or request latency.

**Should I use a static threshold or anomaly detection?**

Use a static threshold when you already know the number that means trouble, like a spend cap or an SLO. Use anomaly detection when you don't have a baseline yet or the metric has strong daily or weekly seasonality. Sentry learns the pattern and flags deviations without a fixed threshold.

**How much does this cost in Sentry?**

Metrics are billed by volume, and Sentry's free tier includes enough to get started. Anomaly-detection alerts are in open beta for Trial, Business, and Enterprise plans.

**Can alerts notify Slack or PagerDuty?**

Yes. Both threshold and anomaly alerts can route notifications to Slack, PagerDuty, or email, so they reach your team through the channels you already use.

---

*Source: [sentry.io/cookbook/custom-metrics-dashboard-alerts-nextjs/](https://sentry.io/cookbook/custom-metrics-dashboard-alerts-nextjs/)*