SRE / Basic: promises and measurements / Lesson 2

SLIs and trustworthy event contracts

Define good and eligible events so a ratio describes user experience and remains interpretable when instrumentation or traffic changes.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Specify numerator and denominator.
Choose a meaningful observation point.
Handle missing and duplicate events explicitly.

Write the event definition first

A service level indicator, or SLI, is a quantitative measure of service behavior. For request-based availability, define the eligible event set before defining success. The Library API counts supported reservation attempts that reach its service boundary. Invalid authentication can be excluded according to an agreed policy, while a valid request rejected because the service is overloaded remains a bad event. Otherwise the service could appear more reliable by refusing work. Record method, route family, outcome policy, source, and units. The definition is a contract for interpretation, not merely a query someone happens to have written.

Choose a boundary that can see failure

A server-side counter cannot see a DNS failure that prevents requests from reaching the server. A client-side observation can cover more of the journey but may be incomplete, sampled, or delayed. Use synthetic checks to examine reachability, recognizing that they represent selected locations and request shapes rather than all users. Do not add counts from these different populations into a single denominator. The teaching record makes the measurement boundary visible beside its exclusions. A second diagnostic metric may describe database success, but that metric measures an internal dependency rather than the whole reservation experience.

yaml Illustrative SLI event contract

sli: reservation-availability
source: edge-completion-events
eligible: supported-valid-reservation-attempt
good: durable-confirmation-within-deadline
missing_completion: bad-after-deadline
excluded: malformed-client-input

The contract counts eligible work before applying the good-event rule. Missing completions need an explicit deadline and cannot disappear from the population.

Calculate a ratio without changing populations

Use good divided by eligible for an availability indicator, checking that good never exceeds eligible. The example filters one synthetic event list exactly once and then classifies the remaining events. It produces three eligible requests, two good outcomes, and a ratio of two thirds. A zero denominator is represented as unknown rather than perfect success. In a real measurement pipeline, late arrival and retry duplication require additional controls. Request attempts and user operations can be separate valid indicators, but naming them consistently matters: ten retries of one operation do not represent ten independent satisfied users.

python Offline event classification

events = [(True, True), (True, False), (False, False), (True, True)]
eligible = [good for include, good in events if include]
good = sum(eligible)
ratio = good / len(eligible) if eligible else None
print(len(eligible), good)
print(f"{ratio:.4f}" if ratio is not None else "unknown")

Expected output

3 2
0.6667

The excluded malformed request is removed from both counts. The failed eligible request stays in the denominator; no monitoring backend is accessed.

Inspect the measurement pipeline

An SLI is only as trustworthy as its collection path. Look for counter resets, clock disagreement, missing emitters, duplicated forwarding, delayed batches, and changes in route classification. Compare independent totals when possible, such as accepted edge attempts versus recorded completions, without assuming they should match instantly. Retain a bounded unknown category during diagnosis. If a deployment changes the meaning of success, version the definition and annotate the transition instead of silently comparing incompatible weeks. A stable-looking graph can hide a broken instrument, especially when absent telemetry is automatically converted to zero errors.

Test edge cases with a tiny fixture

Before relying on an SLI, review a small truth table with product and implementation owners. Include a successful response, a timeout, a dependency error, invalid input, an overloaded rejection, and an attempt with no completion. Ask whether the classification matches what the user experienced. Then test the query against that fixture and preserve it with the definition. This is a semantic check, not a performance benchmark. Repeat it after changes to instrumentation, request routing, or business behavior so that improvements in the reported ratio reflect better outcomes rather than convenient reclassification of failures.

Common errors and fixes

The success ratio exceeds one

Why it happens: Good and eligible counts came from different populations.
How to fix it: Rebuild both counts from the same eligibility contract.
Prevent it next time: Keep a fixture asserting good is at most eligible.

A telemetry outage looks like perfect availability

Why it happens: Missing observations were replaced with zero errors.
How to fix it: Represent unknown data explicitly and inspect collection health.
Prevent it next time: Alert on completeness separately from service failure.

Overload improves the reported SLI

Why it happens: Rejected valid work was excluded.
How to fix it: Count those attempts as bad eligible events.
Prevent it next time: Review exclusion changes with service owners.

Check your understanding

1. Classify an authenticated valid reservation that times out before confirmation.

Show worked solution

It is an eligible bad event under this contract, even if a dependency later completes. Investigate any late write separately because retrying may create a duplicate reservation. The availability classification describes the promised timely outcome; it does not settle the data-correctness question.

2. There are no eligible requests during a five-minute interval. What is the SLI?