Traces

A trace is the anatomy of a single request: where the time actually went, span by span, from the FrankenPHP runtime through the object cache and into the database and back. When a page is slow, web vitals tell you that it’s slow; traces tell you why. Paired with the slowlog — the standing list of your slowest requests and queries — they take you from a vague “the site feels heavy” to a specific query you can fix.

What a trace captures

Each trace stitches together the spans of one request:

• Runtime — request handling in FrankenPHP, including PHP execution time.
• Cache — page-cache and persistent object-cache lookups, with hit/miss timing so you can see when a cache miss is the cost.
• Database — every query the request ran, with its duration. The slow query in a slow request is usually obvious here.
• Outbound — calls out to third-party services and APIs, which often dominate a slow request in ways the front end can’t reveal.

Reading a trace

Open an environment, go to Insights → Traces, and pick a request — or arrive here by drilling in from a slow page in Web Vitals & RUM or a failing path in Requests.

The Insights → Traces detail view for a single slow request, showing a waterfall of spans — FrankenPHP request handling at the top, a nested object-cache miss, and a 1.2 s database query span highlighted as the dominant contributor — with total duration and per-span timings down the right side.

The view is a waterfall, read top to bottom:

1. Find the widest span. The longest bar is where the time went — most often a single database query or an outbound call.
2. Check whether it’s a cache miss. A query that should have been served from the object cache but wasn’t points at a caching bug, not a slow database.
3. Look at how many queries ran. Fifty near-identical queries is the classic N+1 — a plugin querying inside a loop. The fix is in code, and now you know exactly where.
4. Cross-reference the logs for the same request if it errored as well as ran slow.

The slowlog

You don’t have to catch a slow request live. The slowlog keeps a running list of the slowest requests and queries an environment has served, ranked by duration, each linking straight to its full trace. It’s the fastest way to find the worst offenders without knowing in advance where to look — open it, sort by time, and start at the top.

Sampling: keeping it affordable at scale

Capturing a full trace for every request on a high-traffic site would cost more in storage than it’s worth — most requests are fast and identical, and you don’t need a trace for each one. So managed.dev samples traces, and the sampling rate is configured per-site and per-plan.

What sampling does and doesn't drop

Sampling thins out the routine, healthy requests. It is biased to keep the interesting ones — slow requests and errors are far more likely to be retained than a fast 200. So the slowlog stays representative even when the overall sample rate is low, and a busy site stays affordable without going blind to its problems.

A small, low-traffic site may trace at or near full rate, while a high-traffic site on a larger plan samples down to keep the volume sane. The exact sampling rates per plan are being finalized; the principle is fixed — your traffic level shouldn’t force you onto an enterprise tier just to keep tracing on.

Tip

If you’re debugging a specific intermittent issue and the sample is too thin to catch it, drive the path repeatedly (or reproduce it on a low-traffic preview environment, where sampling is effectively full) so a trace is captured.

Next steps

Web Vitals & RUMStart from a slow page, then drill into its trace.

LogsThe error messages that go with a slow or failing request.

RequestsStatus, latency, and path for every request the site serves.