Map the report’s journey beyond the quick API reply

Almost at once, Dispatch returns a job number. Minutes pass. The customer still has no report. The request is over, but the work they wanted is not, and a useful service map follows that work past the quick reply.

The map should help another person find the delayed handoff: what each component needs, who operates it and where to check whether the next step happened. A neat diagram matters less than a useful place to start looking.

This is the fictional Dispatch service from lesson 1. An eligible accepted export should produce the correct report and make it available to its intended user within five minutes. The architecture, ownership and failures below are illustrative. Something to draw on is all the equipment this exercise needs.

The job number is the start of another journey

Trace one export. The API records the job and sends it to a queue. A worker takes it, reads source records, builds the report and writes it to output storage. The customer later makes a separate request to download that file.

The API waits for the queue to accept the job, then returns its identifier. It does not hold the original connection open while the report is built. That identifier lets later requests ask what happened to the same job.

This handoff is convenient until work arrives faster than workers can finish it. The waiting line grows. New customers still get quick API replies while their reports take longer and longer. Neither observation contradicts the other.

The successful API reply covers only part of the promise. To measure the whole export, we need to see the places it could fail. A worker writing a file establishes something about processing, not necessarily about the customer’s ability to download it.

The service clock should not wait until someone chooses to click tomorrow, either. The question is whether the correct report was available to that person within five minutes. Actual download time includes their choice to wait. Mark which of those outcomes the measurement is meant to describe.

Label what crosses each arrow

Draw the API, queue, worker, source store and output store, with submission and download requests around them. Then label the arrows. A job message, a source-record read and report bytes are different things moving between different responsibilities.

Handing a message to a queue is not the same as asking a source store for data and waiting for its reply. Labels make that waiting visible. Without them, a tidy row of boxes can conceal the part of the journey we most need to understand.

At each handoff, ask what would let you say it worked:

Some of these records may not exist in a real service. Write that beside the handoff: “ready state visible; download access unverified,” for example. Adding an observation point to the drawing does not create the observation.

Put the right team beside the handoff

For this exercise, the application team operates the API, worker and download behavior. Messaging runs the queue, data runs the source store and the storage platform team runs output storage. Put each name where someone looking at the map will need it.

Now consider a failed write. Storage operators can repair their service, but the application team must explain what Dispatch does next. Does it retry? Could that create two outputs? What does the customer see while it happens? Those questions sit between the teams, not inside one box.

Leave an unknown as a question someone can answer. “Can a failed write be retried?” invites an investigation. “Retries handled” makes the same uncertainty harder to see.

Add a dependency when it can change the customer outcome or the recovery decision. Not every internal library belongs here, but a permission check that can deny the intended user’s download does. Google’s SLO guidance develops how to measure that user-facing result.

The same complaint can begin in different places

Imagine output writes becoming slow. Workers stay occupied longer and take fewer new jobs. The queue grows while the API keeps accepting requests. To the customer, the only visible fact may be a report that has not arrived.

Now imagine a broken download-permission check instead. Jobs start and finish promptly; files exist. Intended users still get an access error. It sounds like the same complaint, but adding workers would not repair that check.

The map helps separate the cases. Long queue waits and slow writes point toward processing and storage. Normal processing followed by failed authorized retrieval points toward the download path. These patterns suggest the next check; they do not prove the cause.

Even slow storage is not automatically a reason to add workers. If storage already limits throughput, more writers can increase competition without producing more exports. Locate the delayed handoff before choosing what to scale.

Let someone else follow the report

Draw the whole route, including the source read and download access check. Beside each handoff, note what moves, whether the caller waits, who can help and what records success. Mark when the five-minute goal starts and what would show timely availability of the correct report.

Give the map to someone who did not draw it. Can they explain why the fast reply has not settled the complaint and choose a useful next check: a wait, a read or write, or an authorized download? The next lesson turns that understanding into reliability measures. For now, the job number no longer looks like the end of the story.