Distributed Tracing

Distributed tracing lets you see exactly how a request moves through your app — from the initial HTTP call, through your API logic, database queries, and external service calls. If something is slow, you'll see exactly where the time is spent.

What is a trace?

A trace represents a single request or operation in your app. It's made up of spans — each span is one step in the process.

For example, a single API request might produce a trace like this:

[200ms] POST /api/checkout
  [5ms]   validate-input
  [120ms]  charge-stripe
  [50ms]   update-database
  [10ms]   send-confirmation-email

The dashboard shows this as a waterfall chart, so you can visually spot which step took the longest.

Auto-tracing in Next.js

If you're using @deeptracer/nextjs, tracing is enabled by default. No extra configuration needed.

DeepTracer automatically traces:

• Every incoming HTTP request (API routes, server components, server actions)
• fetch() calls made from the server
• Error boundaries and error pages

import { init } from "@deeptracer/nextjs"

export const { register, onRequestError, logger } = init()
// Tracing is already enabled. That's it.

Adding custom spans

For operations DeepTracer can't auto-trace (like database queries or business logic), add manual spans:

const user = await logger.startSpan("db-query", async (span) => {
  span.setAttribute("query", "SELECT * FROM users WHERE id = ?")
  const result = await db.query("SELECT * FROM users WHERE id = ?", [userId])
  return result
})

Custom spans show up inside the parent trace, so you get a complete picture of what happened.

Cross-service tracing

If your app has multiple services (e.g., a Next.js frontend and a separate API server), DeepTracer propagates trace IDs across HTTP requests via headers. This means a single user request that hits multiple services shows up as one connected trace.

Linked logs

Every trace shows the logs that were emitted during that request. Click on any trace in the dashboard and you'll see:

• The waterfall visualization of all spans
• Every log message that happened during the trace
• Any errors that occurred, with full stack traces

This makes debugging straightforward — you don't need to search for related logs manually.

Dashboard features

• Trace list — All recent traces, filterable by service, endpoint, status code, and duration
• Waterfall view — Visual breakdown of every span in a trace
• Linked logs — All logs emitted during the trace, shown inline
• Slow trace detection — Traces that exceed a duration threshold are highlighted

What's next?