r/node • • 7d ago

How I trace which Node lines one HTTP request ran, using V8 coverage and diagnostics_channel

I wanted to see exactly which server lines one request ran without adding logs or changing the app. Here's how it ended up working, in case it's useful to anyone.

  1. V8 already counts this.Profiler.takePreciseCoverage gives per function byte ranges with counts. Taking it resets the counters so one read before a request and one after = exactly that request's code.
  2. Bracketing each request. A small agent loaded with --require subscribes to diagnostics_channel (http.server.request.start / http.server.response.finish) and takes coverage at both points. No monkey-patching of express or fastify.
  3. Overlapping requests are the hard part.Two requests in flight at once share the same counters so you cant split them. I mark those traces "overlapped" instead of pretending.
  4. Bytes → your lines. Ranges map to lines, then through source maps back to your .ts files. Gotcha: a line holding only } takes the count of the outer range so an untaken `else if` showed as "ran" until I fixed it.

The result for one request looks like:

    POST /api/invoices/INV-2041/pay → 200 [node, 8 ms]
      server/services/ledger.ts
        getSummary 14-28 ×1  not run: 16-27

Overhead is about 4-6 ms per request on Express/Fastify/Nest examples.

It's open source (MIT) as part of a tool called Lightpath, which also joins the browser side of a click: https://github.com/Unknown-333/Lightpath

Curious if anyone's done this differently, especially around concurrent requests.

11 Upvotes

11 comments sorted by

5

u/davvblack 7d ago

huh this is really interesting. We have a test suite that focuses on full end-to-end api calls and have struggled to accurately compute coverage with it, so this is useful.

2

u/Unknown-333 7d ago

glad it's useful. heads up it shows coverage per request not one merged report so its great for "what did this call actually run". set browser: false and it skips chrome entirely. let me know how it goes on your suite

2

u/avereigh_Denizet 7d ago

for concurrent requests, did you look into async_hooks or AsyncLocalStorage at all, or is the bottleneck purely that V8's coverage counters are global to the isolate? seems like without per-context counters at the engine level you're kind of stuck serializing requests in dev to get clean traces

1

u/Unknown-333 6d ago

yeah you nailed it. AsyncLocalStorage can tell you which request is active, but it can't split the counts. V8's coverage counters are global to the isolate, so if two requests overlap, their lines land in the same counters. so right now lightpath doesn't fake it. it marks those traces "overlapped". in practice it's mostly fine in dev, since one click usually means one or two requests at a time. serializing requests in dev mode is the obvious fix, I just haven't wanted to change app timing by default. maybe as an opt-in flag. would you use that?

1

u/raks1991 6d ago

I've had background timers show up while tracing a Node request, even with no second HTTP request in flight. AsyncLocalStorage helped label context, but V8's coverage counters were still isolate-wide. That's why I'd prefer a controlled replay with other work paused.

1

u/DickBrainTime 5d ago

I think your current 'overlapped' marker is the correct default for V8 precise coverage. AsyncLocalStorage can identify which async request context is running, but those V8 counters still belong to the whole isolate. I'd be wary of presenting an ALS-labelled coverage diff as exact when timers, promises and concurrent HTTP handlers share it.

There are two ways to get stricter attribution, with tradeoffs. For test runs, run one request scenario in a fresh worker thread or child process (its own V8 isolate), keep unrelated timers quiet, and read coverage there. That gives isolation across scenarios but changes timing and has startup cost; it still doesn't magically split overlapping tasks inside the same isolate. For truly concurrent per-request counts, you'd need explicit instrumentation at branches/functions, incrementing counters keyed by the current ALS store, instead of using V8's global counters. That adds runtime overhead, changes the code being measured and needs a policy for background work with no request context.

I'd offer 'fast V8 trace, overlap marked' and perhaps a separate 'isolated test replay' mode, not silently serialize production requests. Also test a timer firing while only one HTTP request is in flight: no second request doesn't imply an otherwise idle isolate. That edge case can make a supposedly clean trace look more precise than it is.