Resources > workshop

Debugging Next.js Best Practices: Logs and Tracing

Next.js gives you static pages, cached components, and dynamic renders — each shows up differently in your observability tooling. This session teaches you what to expect from each, how to query it, and when to alert on it.

Prerequisites

Modules

1 The App & Decision Framework

Tour the app and its four route types: static, cached, dynamic, and user-specific. Learn when to reach for a metric, a log, or a span.

  • Metric → counting and alerting (page.view by route type)
  • Log → investigating a specific event (auth.login with context)
  • Span → timing within a request (db.query, cache lookup)
  • What Sentry and Vercel already capture for you

2 Structured Logs

Query wide events in Sentry Logs. Each log packs one operation's full context — user, result, duration — so you can filter by any dimension and click through to its trace.

  • auth.login — filter by result, group by user
  • schedule.add — find the most popular talks
  • cache.miss — which cache key, which path
  • Log → trace: click any log to see the full request

3 Traces Across Route Types

Compare trace waterfalls across the four rendering strategies. See what server work each generates — from zero spans on a static page to full DB queries on a dynamic one.

  • Static (/workshop): render only, no DB, no cache
  • Cached hit (/): suspense-cache lookup, no DB
  • Cached miss (/): db.query spans + cache write-back
  • Dynamic (/my-schedule): auth + DB every request

4 Metrics & Dashboards

Build a dashboard from the command line with the Sentry CLI. Group page views by route type, track cache miss rates, and visualize auth patterns.

  • sentry dashboard create + widget add
  • page.view grouped by route_type and path
  • cache.miss rate vs total page views
  • Sentry MCP server for natural language queries

5 Alerts

Create a monitor on login failures from the Sentry UI. Review the framework: metrics for counting, logs for context, traces for timing.

  • Log-based monitor: auth failures > threshold
  • Metric-based monitor: cache miss rate spike
  • Each signal has one job — don't make one do another's

Tools

Sentry CLI

Create dashboards, query logs, and view traces from the terminal.

Sentry MCP Server

Query Sentry data with natural language through your AI editor.

Monitors & Alerts

Threshold-based monitors on logs and metrics with Slack/PagerDuty/email actions.

FAQs

The workshop targets Next.js 15 and 16. Older versions will work but some APIs (like proxy.ts) may differ.

In Next.js this is done automatically by the SDK, however if you're not seeing traces being connected between the frontend and the backend, add your backend API routes to tracePropagationTargets inside the Sentry.init inside instrumentation-client.ts

Logs are for investigations (high-cardinality, wide events with rich attributes). Metrics are for counting, with three APIs: count, gauge, and distribution. Both let you attach unlimited attributes at no extra cost.

A span is a unit of work (function call, DB query, resource load). A trace is a collection of related spans tied to the same interaction. Sentry auto-instruments most of these.

Yes. Text is masked by default. You can opt specific elements in or out via classes/attributes.

Filter in your Sentry init's beforeSend. Inspect the request's user-agent header (server side) and drop events from known crawlers (ClaudeBot, GoogleOther, etc.). A cookbook for this pattern is on the way.

More resources

Observing and Debugging Next.js apps with Sentry: A Hands-on Session

Observing and Debugging Next.js apps with Sentry: A Hands-on Session

Read More
[Workshop] Building and Monitoring AI Agents and MCP servers

[Workshop] Building and Monitoring AI Agents and MCP servers

Read More
Logging in Next.js is hard (But it doesn't have to be)

Logging in Next.js is hard (But it doesn't have to be)

Read More