Capacity planning: define a completed operation before setting throughput

Count the result the user requested

A team planning an export service needs a throughput target. The API accepts an export request, a worker builds the file, and the user retrieves it later. Counting every successful API response would measure a different boundary from the finished export. RFC 9110 makes that distinction explicit for HTTP 202: processing has been accepted and remains incomplete.

For this design exercise, define completion as one requested export producing a valid file that the requesting user can retrieve. The file must match the requested dataset and format. A queued job, a worker attempt, and a status poll each have separate counts. These are proposed measurement rules, with no claim about an implemented service.

Google's SRE guidance starts service objectives from what users need and asks teams to specify measurement conditions. Apply that discipline before choosing a number: decide which observable result earns one completed operation and where the evidence for that result will come from.

Give each operation one place in the accounting

In the proposed contract, an operation identity stays the same across submission retries and worker attempts. Count the first verified completion once for that identity. Keep attempts visible as work the system performed, and keep rejected submissions separate from accepted operations. The report must reveal whether its target applies to offered demand or admitted demand.

At an observation boundary, give every accepted identity exactly one recorded outcome: successfully completed, terminally failed, cancelled, unfinished with a known status, or unresolved. Reconcile these categories with the accepted total. Investigate missing evidence before the result supports a capacity decision.

PostgreSQL 18's pgbench provides a concrete reporting example at a narrower boundary: it reports completed transactions, failures, and transactions per second, with retry statistics when configured. Its transaction definition belongs to the selected script. A database result alone does not establish that an export became retrievable.

Work through a one-minute example

Suppose an illustrative 60-second interval starts with no unfinished work. There are 600 new export identities, all admitted, plus 300 submission retries referring to those same identities. During the interval, 480 exports reach verified completion and 12 reach terminal failure. The other 108 remain queued or executing. There are no cancellations or unknown outcomes in this example.

The rates are 15 submission attempts per second, 10 newly accepted operations per second, and 8 successful completions per second. The accounting closes: 480 completed plus 12 failed plus 108 unfinished equals 600 accepted. Retrying a submission has added activity without adding a new export to the denominator.

These invented counts demonstrate the calculation. They establish no system's sustained capacity. The interval ends with 108 outstanding obligations, and its 12 failed operations have also consumed work. A report containing only the 15-attempt rate would leave the buyer unable to evaluate the delivered output or remaining demand.

Keep the output window separate from the arrival cohort

Counting completions during a minute answers how much output appeared in that minute. To ask whether exports meet an illustrative 20-second deadline, follow the identities admitted during the minute and their individual admission-to-completion times. An export admitted at second 59 is not late at second 60. Observation must extend through its deadline.

For that deadline measure, use timely valid completions as the numerator and all accepted identities in the cohort as the denominator. Terminal failures and missed deadlines remain outside the numerator. Report cancellations separately under a rule agreed before the run. Google SRE's good-events-over-total-events method supports this construction; the export boundary and example deadline are choices for this exercise.

If observation ends early or evidence is missing, retain an unresolved category and report the incomplete observation. Completion latency measured only for successful exports cannot tell the reviewer how many operations failed or are still waiting.

Attach the workload to the throughput number

An export count also needs a workload definition. Record dataset sizes, output formats, and the mix of operations the capacity decision covers. Google's handling-overload guidance explains that request resource costs can differ substantially and change with the workload. A result for small exports needs additional evidence before it supports a target dominated by large ones.

Retain resource use and application latency beside completed output. State the observation interval, initial backlog, and whether the interval includes startup or recovery work. Google SRE documents how averages can hide bursts and latency tails. Inspect the distribution relevant to the user promise instead of relying on a single average.

Any later measurement should name its environment, software revision, workload, and method. PostgreSQL's pgbench guidance also calls for sufficiently long and repeatable runs because short results can mislead. Select duration and repetitions for the behavior being investigated; the one-minute arithmetic example supplies no such validation.

Write the contract before approving capacity

A reviewable target names a completed result, a required rate, a workload mix, and the conditions that make the result acceptable. For the export service, it must also state the deadline measure, permitted failures, and how unfinished work will be reported. The system owner supplies those product requirements; the measurement determines whether a particular configuration meets them.

Before funding more capacity, request one reconciled report connecting offered demand, admitted identities, attempts, and verified output. If those counts cannot be joined, scope the first investigation around the missing evidence. An assessment can deliver that measurement contract and a bounded validation plan before the team commits to a throughput claim.