Your API is down - now what? Capturing failure context in Node.js

Most monitoring tools tell you one thing

"Your API is down."

That's useful. But only partially.

I wanted to go beyond "it's down" and understand why — specifically, where in the request lifecycle things actually broke.

The frustrating part of debugging failures

The first time this really hit me, I spent almost an hour digging through logs after a 3am alert — only to realize the issue had already disappeared. No trace of what went wrong. Just a gap in the metrics and a resolved status.

The typical workflow looks like this:

• You get an alert
• You SSH into your server
• You check logs
• You try to reproduce the issue

And in many cases… the issue is already gone.

The failure might have lasted only a few seconds:

• A DNS resolution issue
• A TLS handshake problem
• A temporary upstream timeout

By the time you investigate, there's no trace left.

Logs don't always tell the full story

Logs are helpful, but they have real limitations:

• They only capture what your application explicitly logs
• They often miss network-level issues entirely
• They don't show how a request failed step by step

What I kept missing was the network-level picture — not what the app logged, but what actually happened between the client and the server at each phase of the request.

Breaking down an HTTP request

When you make a request to an API, a lot happens under the hood:

1. DNS lookup — translating the domain name into an IP address
2. TCP connection — establishing a connection to the server
3. TLS handshake — negotiating encryption (for HTTPS)
4. Server processing — the server does its work and prepares a response
5. First byte received — also called TTFB (Time To First Byte), this is the total time from sending the request to getting the first byte back. It's not a separate step — it's a cumulative measurement across all the steps above.

If any one of these steps fails or slows down, the entire request is affected.

But most monitoring tools treat the request as a black box. You get a status code. Sometimes a timeout. Rarely anything more.

The idea: capture the failure at the moment it happens

Instead of trying to debug after the failure has resolved itself...

What if we could capture useful diagnostic signals during the failure?

So I started experimenting with capturing:

• DNS lookup timing
• TLS handshake duration
• Time to first byte
• The first part of the response body

At the exact moment a request fails.

I ended up building a small tool around this idea — I call it Pinghawk.

What this actually changes

To see why this matters, here's what a typical monitoring alert looks like:

ALERT: API DOWN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
endpoint:  api.myapp.io/payments
status:    DOWN
started:   2026-03-26 09:05:25
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

That's everything you get. Now you start the investigation — SSH, logs, curl, check DNS, check TLS. By the time you look, the evidence is usually gone.

Now here's what it looks like when you capture diagnostic data at each failure. The tool waits for three consecutive failures before alerting (more on why below), and captures a snapshot at each one silently:

Example A — Server degradation into timeout

--- SNAPSHOT #1 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  dns_lookup       1ms                       (~estimated)
  tls_handshake    5ms                   (SSL negotiation)
  ttfb             4,007ms                     ↑ critical
                   server is very slow or overloaded
  total_time       4,312ms
───────────────────────────────────────────────────────────

--- SNAPSHOT #2 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  dns_lookup       2ms                       (~estimated)
  tls_handshake    4ms                   (SSL negotiation)
  ttfb             10,002ms                    ↑ critical
                   server is very slow or overloaded
  total_time       10,374ms                      ↑ worse
───────────────────────────────────────────────────────────

--- SNAPSHOT #3 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  error            TIMEOUT
                   Your server did not respond within
                   the allowed time. May be overloaded,
                   crashed, or unreachable.
  total_time       10,000ms
───────────────────────────────────────────────────────────

TTFB went from 4,007ms to 10,002ms to a full timeout. The server was degrading under load until it stopped responding entirely. You can see the failure developing across three snapshots.

Example B — Upstream dependency failure

--- SNAPSHOT #1 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  dns_lookup       3ms                       (~estimated)
  tls_handshake    12ms                  (SSL negotiation)
  ttfb             1,847ms                        ↑ high
  status_code      502
                   Bad Gateway — upstream service
                   returned an invalid response
  response_body    {"error":"upstream_timeout",
                    "service":"payment-gateway"}
───────────────────────────────────────────────────────────

--- SNAPSHOT #2 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  ttfb             1,923ms                        ↑ high
  status_code      502
  response_body    {"error":"upstream_timeout",
                    "service":"payment-gateway"}
───────────────────────────────────────────────────────────

--- SNAPSHOT #3 ---                         ap-southeast-1
───────────────────────────────────────────────────────────
  ttfb             2,104ms                        ↑ high
  status_code      502
  response_body    {"error":"upstream_timeout",
                    "service":"payment-gateway"}

  ┌─────────────────────────────────────────────────────┐
  │  DNS ✓  TLS ✓  Server responded — upstream failed.  │
  │  Payment gateway timed out. Your server is fine.     │
  └─────────────────────────────────────────────────────┘
───────────────────────────────────────────────────────────

DNS fine. TLS fine. Your server responded — but the payment gateway behind it timed out. No SSH session required.

The difference: instead of starting an investigation after the alert, the evidence is already there when the alert arrives.

The tricky part: getting this data in Node.js

This turned out to be harder than expected.

Most high-level APIs like fetch don't expose DNS timing or TLS handshake duration at all. They give you a response, but no visibility into the individual phases of how that response was obtained.

To get this data, I ended up using undici (the HTTP client that powers Node.js fetch under the hood) combined with Node.js diagnostics_channel. This lets you subscribe to events that fire at specific moments during a request:

import diagnostics_channel from 'node:diagnostics_channel'

const requestStartMs = Date.now()
let connectStartMs = null
let connectEndMs = null
let headersMs = null

diagnostics_channel.subscribe('undici:client:beforeConnect', () => {
  connectStartMs = Date.now()
})

diagnostics_channel.subscribe('undici:client:connected', () => {
  connectEndMs = Date.now()  // TCP + TLS handshake complete
})

diagnostics_channel.subscribe('undici:request:headers', () => {
  headersMs = Date.now()  // First byte received
})

// After the request completes:
// connectEndMs - connectStartMs = real TCP + TLS handshake time
// headersMs - requestStartMs     = real TTFB (total time to first byte)
// Remember to unsubscribe after the request completes

Here's what each metric actually gives you — and whether it's a real measurement or an estimate:

A few things worth noting honestly:

• DNS timing is estimated, not exact. Node.js doesn't expose real DNS resolution timing through diagnostics_channel. DNS resolution happens before the beforeConnect event fires, so there's no direct event to hook into. The values I capture are heuristic-based — useful for spotting anomalies, but not precise measurements. That's why the examples above show (~estimated) next to DNS values.

• The diagnostics_channel events are semi-internal. They work well today, but undici doesn't guarantee these channel names will stay stable across Node.js versions. It's a tradeoff — you get real timing data, but you're relying on an API that could change.

• The capture is a separate request. When a check fails, the tool makes a second HTTP request using undici to capture the timing breakdown. This means the snapshot might not match the original failure exactly — the server could have recovered, or the error could be different. It's a real tradeoff I'm still thinking about. The alternative would be to instrument the original request, but that adds complexity to the main check path.

I wanted real timing data, even if it meant accepting these tradeoffs.

One more design decision: don't alert on the first failure

As you saw in the examples above, the tool waits for three consecutive failures before sending an alert — and captures a snapshot at each one silently:

Check 1 fails → snapshot #1 captured silently
Check 2 fails → snapshot #2 captured silently
Check 3 fails → snapshot #3 captured + alert sent with all three

Why three? It's enough to filter out transient blips (a single DNS hiccup, a momentary network glitch), but short enough to catch real outages within minutes at typical check intervals.

The result:

• Fewer false alarms — transient issues don't wake you up at 3am
• A progression timeline — you can see the failure developing across three snapshots (like the degradation in Example A above)
• Evidence arrives with the alert — all three snapshots are attached before you even open it
• Recovery is handled too — two consecutive successes resolve the incident and send a recovery notification with the total downtime duration

A small shift in thinking

What changed for me was this:

Don't just detect failures — capture context when they happen.

That one shift made debugging much faster and less frustrating. By the time the alert arrives, the evidence is already there.

Still exploring

There are still open questions here — especially around DNS timing accuracy and how closely the snapshot matches the original failure when it's captured as a separate request.

I'm curious how others handle this:

How do you usually debug short-lived or transient API failures?

Do you rely on logs, APM tools, distributed tracing, or something else entirely? Have you found a good way to capture context at the moment of failure rather than investigating after the fact?

Would love to hear what works for you.

The tool I mentioned is called Pinghawk (https://pinghawk.io) — it's in free beta if you want to try it.