Why is one GraphQL endpoint's overall request latency metric not actionable?

## The dimension a single route takes away Every useful latency metric is really a latency metric *per something*. In a path-per-resource HTTP API, that something arrives free of charge: the request line already names the resource, so a proxy, a framework filter or a server-side timer can partition durations by path with no application knowledge at all. Two routes that do different amounts of work produce two series, and each series describes one workload. A GraphQL API deliberately throws that away. The whole design is that a caller composes what it wants and posts it to a single endpoint. The consequence for observability is immediate and often unremarked: the route dimension still exists, but it now has exactly one value, so partitioning by it partitions nothing. Whatever your timer wraps, it wraps *every* operation the schema permits. ## What that mixture actually looks like Take a payroll and benefits graph. Two of its operations sit at opposite ends of the cost range: * `EmployeeBadge` reads a display name and a photo reference off one row. Call it 6 ms at p50, and roughly 91% of the traffic, because it renders in a header on every screen. * `PayRunReconciliation` pages 8,400 payslips and, for each, expands the deduction lines and the benefit plan behind them. Call it 3.2 seconds at p50, and 0.3% of the traffic, because a payroll administrator runs it a few times per cycle. Now read the blended p99 of that endpoint. With the heavy operation at 0.3% of traffic, it sits below the 99th percentile entirely, so p99 is somewhere in the tens of milliseconds and describes the badge lookup's tail. The report is invisible. Two things follow, and both are the reason interviewers ask this question. **The number moves for reasons that are not regressions.** Move the reconciliation operation from 0.3% to 1.4% of requests — a business-calendar effect, month-end, nothing shipped — and it crosses into the top percentile. The endpoint p99 jumps from 40-odd milliseconds to seconds. The dashboard looks like an outage. No operation got slower; the mixture changed. This is the single most common false page on a GraphQL service. **The number stays still for reasons that are regressions.** Let the reconciliation operation degrade from 3.2 seconds to 9 seconds because a deduction-line lookup lost an index. At 0.3% of traffic it never reaches p99, so the endpoint metric does not twitch, while the administrators who depend on it are timing out. A rare, expensive, business-critical operation is exactly the kind the aggregate hides. ## What to measure instead Measure the **operation**, not the route. The minimum useful dimension set for a request-duration metric on a GraphQL endpoint is: * **operation type** — `query`, `mutation` or `subscription`. The server parses this out of the document itself, so it is authoritative and bounded to three values. It matters because subscriptions are long-lived and do not belong in the same duration series as request/response operations at all. * **operation identity** — which document ran. The client-declared operation name is the obvious candidate and the treacherous one; a server-computed hash of the document is the trustworthy one. That trade-off is a question of its own. With those, `EmployeeBadge` and `PayRunReconciliation` become separate series with separate baselines, and both failure modes above disappear: a mix shift changes the request *rate* of each series without touching either one's latency, and a regression in the rare operation shows up in that operation's own line. ## Two things not to do Do not reach for a metric per resolved field. One reconciliation document resolves tens of thousands of field positions; a counter or timer per field position is a cardinality problem and a cost problem, and the question it answers — where inside one execution the time went — is what per-resolver tracing exists for. Metrics answer "which operations, how often, how fast, how often failing"; that is a much smaller question and should stay small. Do not report a mean. The distribution of durations on a GraphQL endpoint is not merely skewed, it is a mixture of distributions that have nothing to do with each other, and a mean over a mixture is a number with no referent. Even after you split by operation, prefer a distribution over a mean — but the split matters far more than the statistic. ## Where the timer starts and stops One detail worth having an answer for: a GraphQL request is parsed, validated and then executed, and a failure at the first two stages costs almost nothing. If your timer covers all three, a flood of invalid documents will *lower* your latency while raising your error rate. Recording parse-plus-validate separately from execution keeps that honest. And when a response is delivered incrementally, "the request finished" has two candidate meanings — the initial payload and the final one — so pick one, name it in the metric, and be consistent.