DEV Community

Shubham
Shubham

Posted on

I built Tracepath to debug Node.js requests from the terminal

#showdev #node #javascript #webdev

A slow API response doesn’t tell you where the time went. Was it application logic, a database query, or a downstream HTTP call?
I built Tracepath to help investigate these questions during local development, with request traces displayed directly in the terminal.
What it does
Tracepath currently supports:

  • Express request tracing.
  • Automatic instrumentation of Node’s HTTP/HTTPS request and get calls.
  • Custom spans around operations you want to measure.
  • Browser fetch tracing, with additional setup for backend correlation.
  • A local terminal dashboard showing timings and errors. The local dashboard requires no hosted account or Docker. Your application does need instrumentation. Try it with Express You’ll need Node.js 22.13 or later. Install the SDK and Express: 
npm install @tracepath/node express
Enter fullscreen mode Exit fullscreen mode

Start the dashboard in a separate terminal:

npx @tracepath/cli dashboard
Enter fullscreen mode Exit fullscreen mode

Create a bootstrap file so instrumentation initializes before your application loads:
// bootstrap.mjs

import { init } from '@tracepath/node'

init({
  service: 'demo-api',
  dashboard: true,
})

await import('./server.mjs')
Enter fullscreen mode Exit fullscreen mode

Then create the server:
// server.mjs

import express from 'express'
import {
  getTracer,
  tracepathMiddleware,
} from '@tracepath/node'

const app = express()
const tracer = getTracer()

app.use(tracepathMiddleware(tracer))

app.get('/demo', async (_req, res) => {
  await tracer.startActiveSpan('simulate-slow-operation', async () => {
    await new Promise(resolve => setTimeout(resolve, 300))
  })

  res.json({ message: 'Check your terminal dashboard' })
})

app.listen(3000, '127.0.0.1')
Enter fullscreen mode Exit fullscreen mode

Run it:

node bootstrap.mjs
Enter fullscreen mode Exit fullscreen mode

Visit http://127.0.0.1:3000/demo.
The dashboard should show the request and the custom operation taking roughly 300 ms.
This is a minimal development example; see the package documentation for application shutdown and flushing.

What’s still missing?
This is an early release, and there are limits:

  • Database queries need manual spans; Postgres/MySQL auto-instrumentation isn’t implemented.
  • Native Node fetch/Undici and HTTP/2 aren’t automatically instrumented.
  • The local dashboard doesn’t provide persistent trace storage or alerting. One useful piece of feedback I’ve already received is that database spans—with query timing and row counts—would make this much more valuable. I’d like to hear which integrations matter most to other developers. Looking for hands-on feedback If you work with Node.js/Express, try tracing one endpoint and let me know:
  • Was setup straightforward?
  • Did the trace help explain where time was spent?
  • Which missing integration would stop you from using it? Please avoid putting secrets or personal data in custom span names and attributes. Keep the dashboard local.

📦 Node SDK and documentation
🖥️ Terminal dashboard
🌐 Browser SDK

Top comments (0)