UML Timing Diagrams

A timing diagram plots how the state of one or more participants changes along a horizontal time axis, with explicit durations and deadlines. It borrows the look of hardware logic-analyser traces. Engineers working on latency budgets, protocols, embedded systems and rate limits read it.

1. What a Timing Diagram Shows

Sequence diagrams show order, but time is only implied by vertical position. When how long matters as much as what happens, a timing diagram makes time the main axis. Each participant gets a horizontal lane; within the lane a line steps between named states as time passes. Messages between lanes can be drawn as arrows, and constraints such as {d < 200 ms} state deadlines.

It is the natural picture for SLAs and latency budgets, timeouts and retries, debouncing, watchdogs, and any protocol where a missed deadline is a bug.

2. Notation

Timing Diagram Notation Lifeline Busy Idle state change (vertical step) {d < 200 ms} duration constraint t = 0 time observation x-axis = time, left to right

Each lane is one lifeline. Its possible states are listed on the left; the thick line shows which state it is in at each moment. A vertical step is a state change. A two-headed arrow with a {...} label is a duration constraint; a tick labelled t = 0 is a time observation used in other constraints. UML also has a compact value lifeline form that writes states inside hexagon-shaped segments, handy when there are many states.

3. Example 1: Checkout Latency Budget

Online Shop: Checkout Timing Budget 0 ms 400 ms 800 ms 1200 ms 1600 ms 2000 ms Browser Waiting Idle Order API Working Idle PSP Authorizing Idle {end-to-end < 2 s}

Walkthrough: the browser starts waiting at 0 ms. The order API works briefly, then idles while the payment provider (PSP) authorizes, which takes the biggest slice. When authorization finishes, the API works again and responds; the browser returns to Idle at about 2.3 s on this scale. The yellow constraint {end-to-end < 2 s} is therefore violated, and the diagram shows exactly where the time went: the PSP lane. That is the conversation a timing diagram is for.

4. Example 2: A Token Bucket Rate Limiter

Token Bucket Rate Limiter Client Sending Quiet Bucket Full Partial Empty Response 429 200 While the bucket is Empty, requests get HTTP 429; refills move it back toward Full.

Walkthrough: a client sends a burst; the bucket drains from Full through Partial to Empty, and the response lane flips from 200 to 429. During the quiet period tokens refill and responses return to 200. The second burst drains it again. Seeing the three lanes aligned makes the cause-and-effect obvious in a way a sequence diagram with dozens of messages cannot.

5. Pros, Cons, and When to Use

Pros

Cons

When to use

When not to use

6. Reading Tips and Common Mistakes

Read vertically first: pick a moment and look straight down through every lane to see the whole system's state at that instant. Then read horizontally along the lane that matters most and measure where its time goes. Constraints tell you which of those measurements is a requirement.

Common mistakes: drawing to an inconsistent time scale, which makes durations misleading; adding too many states per lane; and inventing numbers. Base the timeline on real traces from OpenTelemetry, browser dev tools or load tests where you can, and say so on the diagram. A short legend noting the source and date of the measurements makes the diagram far more trustworthy.

7. As Diagrams-as-Code

PlantUML supports timing diagrams with robust and concise lanes:

@startuml
robust "Browser" as B
robust "Order API" as A
robust "PSP" as P
@0
B is Idle
A is Idle
P is Idle
@100
B is Waiting
A is Working
@400
A is Idle
P is Authorizing
@1700
P is Idle
A is Working
@2300
A is Idle
B is Idle
@100 <-> @2300 : end-to-end
@enduml

Mermaid has no timing diagram; its gantt chart is sometimes used as a rough substitute.