Give individual requests an identifier, connect distributed work through trace context, and preserve a separate job or operation identity for work that outlives one request. These identifiers solve different lookup problems. Keeping their meanings explicit makes a failure easier to follow without dumping credentials or entire payloads into logs.

This walkthrough uses an illustrative report-export service. It explains the design rather than prescribing one tracing vendor or claiming a benchmark of observability tools.

Decide what each identifier names

Teams use “correlation ID” to mean several things. Before choosing a header, define its scope:

A request-ID convention belongs to your system or infrastructure; its exact header and lifecycle are not automatically standardised by calling it X-Request-ID. Document which layer creates it, whether downstream services retain it, and how retries are identified.

For tracing, prefer the established W3C Trace Context format through a compatible library. It provides a portable way to propagate trace relationships across services. A random UUID in a custom header can be useful for lookup, but it does not by itself establish parent-child spans, timing or error relationships.

Follow one export through the boundaries

Suppose a browser submits an export. The gateway assigns request R1. The API creates job J1, commits it and returns a status URL. A worker later claims J1, writes a file, then records completion.

Useful structured events might be represented as:

{"event":"export.accepted","request_id":"R1","job_id":"J1","status":202}
{"event":"export.started","job_id":"J1","attempt":1}
{"event":"export.failed","job_id":"J1","attempt":1,"error_code":"storage_timeout"}

These are illustrative labels, not valid W3C trace IDs or real production records. Actual trace IDs and span IDs should come from the tracing implementation and can be attached as additional structured fields.

The job ID bridges time and execution ownership. Even if a trace is sampled out, expires from the backend or deliberately ends at the queue boundary, the product still needs to know which job failed. Store the durable state in the job system; logs help investigate it, rather than becoming the only record that work exists.

On a retry, retain J1 and increment or otherwise identify the attempt. A new worker attempt is different work on the same durable job. Recording only a new random identifier would make the relationship needlessly difficult to recover.

Propagation carries relationships, not permission

OpenTelemetry's context propagation documentation explains how context is injected into and extracted from carriers such as HTTP headers. Instrumentation normally creates child operations while preserving the trace relationship. Let a compatible SDK handle that work instead of hand-building trace headers around every call.

Decide what happens at an external trust boundary. An incoming trace ID or request ID is caller-controlled until your gateway or instrumentation validates and applies its policy. It must never select an account, approve a tenant, bypass rate limiting or grant access to logs.

Also avoid unlimited, unchecked request-ID strings. A system that reflects arbitrary values into headers or concatenates them into text logs has introduced an input-handling problem into its diagnostic path. If a trusted proxy supplies the identifier, establish that trust through the actual deployment configuration, not the header's name.

For asynchronous work, use the queue integration's supported propagation or linking behaviour. A long-lived job can have a different tracing lifecycle from the HTTP request that created it. Preserve the job identity regardless, and document whether worker attempts continue a trace, start a new trace or link to earlier work.

Correlate logs with spans without copying the request

OpenTelemetry's log data model includes trace and span fields so logs emitted during a span can be connected to it. Add them through supported logging integration where available. Include the service name, operation, outcome and stable error classification as well: an ID with no meaningful event tells you little.

For an export failure, job_id, attempt, error_code, duration and the affected subsystem can be enough to locate the next step. The access token, full SQL query, customer document and raw request body usually add exposure without helping that first diagnosis.

OWASP's logging guidance identifies credentials, session values and other sensitive fields that should not be recorded directly. Prefer an explicit event schema to a generic “log every header” middleware. Redaction after collection is a weaker boundary because the original has already entered the pipeline.

Use structured serialisation rather than concatenating untrusted text into a line format. Test how your logging stack handles control characters and oversized fields. Then protect the log store with appropriate access and retention: a random correlation ID does not make the associated records public.

Baggage travels further than it looks

Trace context is not an invitation to attach customer details. OpenTelemetry baggage can propagate key-value data downstream, including through automatically instrumented network calls. A field added for convenience in one service can reach a third-party API later.

Keep personally identifying data, credentials and sensitive business content out of propagation headers. Use non-sensitive routing or diagnostic metadata only where its distribution is understood and permitted. Trace IDs themselves can correlate activity, so apply a deliberate boundary policy when communicating outside your system.

Sampling also affects what investigators can retrieve. Seeing a trace ID in a log does not prove that the backend retained a complete trace for it. Document sampling and retention so “trace not found” is interpreted as a coverage question rather than proof that the request never happened.

Make support lookup work on a deliberately failed request

Before an incident, create a controlled failure in a test environment. Capture the support-facing reference, locate the gateway and API events, follow the durable job, then identify the worker attempt and downstream failure. Repeat after a retry.

Check that the same operation can be followed without access to raw credentials or payloads. Verify that caller-supplied request or trace IDs cannot select privileges or bypass the gateway's propagation policy. An identifier does not authenticate its source; that trust comes from the authenticated connection and deployment boundary. Bound or replace oversized and malformed values according to the documented policy.

Finally, distinguish correlation from deduplication. An idempotency key can intentionally survive several HTTP attempts, while each attempt deserves its own request record. Jitsumi's API idempotency guide explains why those attempts should not create repeated effects.

A useful incident record lets you answer four questions: which request, which job, which attempt, and which dependency failed? Design those relationships before adding more log volume.

References

• W3C: Trace Context
• OpenTelemetry: context propagation
• OpenTelemetry: Logs Data Model
• OpenTelemetry: baggage and sensitive data
• OWASP: Logging Cheat Sheet

Then Alice reloads the page. Her title is gone.

Nothing crashed. The database accepted both writes. The application simply allowed Bob's older copy of the article to replace Alice's newer one.

This is a lost update. A useful defence is optimistic concurrency control: return a version identifier when a client reads a resource, then accept its write only if that version is still current. For HTTP APIs, ETag and If-Match provide an existing vocabulary for this contract.

The header is only half the solution. The version check must stay attached to the database write, and the editor needs a sensible way to recover when a save is rejected.

Let's build the failure, fix the write, and follow the conflict back to the person using the editor.

The race starts when the form opens

Consider this illustrative article:

{
  "title": "Draft",
  "summary": "Old summary"
}

Alice and Bob both load version 7. Their screens now contain independent copies.

Bob never deliberately reverted the title. His form submitted a title that was correct when he opened the page.

This is why disabling the Save button while a request runs cannot solve the problem. The competing request can come from another tab, another device, an administrator or a background worker.

It also explains why two writes do not need to arrive at precisely the same instant. Bob can save ten minutes later and still overwrite a change made after his original read.

Send the version back with the write

An ETag identifies a particular representation. The server chooses its value; it does not have to be a content hash.

An API might return the following simplified exchange:

GET /articles/42 HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Content-Type: application/json
ETag: "article-42-v7"

{"title":"Draft","summary":"Old summary"}

The client keeps the ETag alongside the form's original data. When Alice saves, it sends the tag unchanged, including the quotes:

PUT /articles/42 HTTP/1.1
Host: api.example.com
Content-Type: application/json
If-Match: "article-42-v7"

{"title":"Ready to publish","summary":"Old summary"}

The condition means: apply this change only if the selected representation still matches this tag. RFC 9110 defines this use of If-Match, including its role in preventing accidental overwrites.

Alice's save can succeed because version 7 is current. Suppose that write advances the resource to version 8.

Bob then submits his full copy with the same version-7 condition. The server rejects the stale write:

HTTP/1.1 412 Precondition Failed
Content-Type: application/json

{"error":"article_changed","message":"Reload and compare your changes."}

That response is a deliberately simple API design, rather than a universal error-body format. The 412 status documents a failed precondition. For this workflow, Bob's proposed update has not been applied.

ETags do not reserve an editing session. Alice and Bob can work freely; the conflict becomes visible when a stale copy tries to save.

Put the comparison inside the update

A tempting implementation is:

1. Read the current version.
2. Compare it with the client's version.
3. Run an unconditional update.

There is still a gap between steps two and three. Another request can change the row after the check passes.

Instead, make the expected version part of the write's predicate:

UPDATE articles
SET title = ?,
    summary = ?,
    version = version + 1
WHERE id = ?
  AND version = ?;

The last parameter is the version associated with the representation the editor originally loaded.

A matching row is updated and its version advances together. A stale version matches no row. SQLite's UPDATE documentation explicitly notes that a condition matching no rows produces a zero-row update rather than a SQL error.

This is a compare-and-set pattern. Its success signal comes from the database operation, not an earlier application-side guess.

The SQL version column and the HTTP ETag are related design choices, but they are not interchangeable syntax. An HTTP handler must validate and interpret the client's condition before invoking the storage operation. Do not implement a general ETag parser by blindly splitting any incoming header on -v.

Reproduce both outcomes without a web framework

Save the following as lost_update_demo.py and run it with Python 3.12:

python3 lost_update_demo.py

On Windows, use py -3.12 lost_update_demo.py if you installed Python through the Windows launcher.

This example uses Python's sqlite3 module and an in-memory database. It creates no database file and installs no packages. It deterministically models two readers loading the same version before either writes; it does not start an HTTP server or rely on thread timing.

"""Deterministic stale-write demonstration; no server or files required."""
import sqlite3


def run(guarded):
    db = sqlite3.connect(":memory:")
    db.row_factory = sqlite3.Row
    db.execute("""
        CREATE TABLE articles (
            id INTEGER PRIMARY KEY,
            title TEXT NOT NULL,
            summary TEXT NOT NULL,
            version INTEGER NOT NULL
        )
    """)
    db.execute("INSERT INTO articles VALUES (1, 'Draft', 'Old summary', 7)")
    db.commit()

    def read():
        return dict(db.execute("SELECT * FROM articles WHERE id = 1").fetchone())

    def save(copy):
        sql = """
            UPDATE articles
            SET title = ?, summary = ?, version = version + 1
            WHERE id = ?
        """
        params = (copy["title"], copy["summary"], copy["id"])
        if guarded:
            sql += " AND version = ?"
            params += (copy["version"],)
        with db:
            changed = db.execute(sql, params).rowcount
        return changed == 1

    # Both editors read before either saves. No timing tricks needed.
    alice = read()
    bob = read()
    alice["title"] = "Ready to publish"
    bob["summary"] = "New summary"

    alice_saved = save(alice)
    bob_saved = save(bob)
    final = read()
    db.close()
    label = "guarded" if guarded else "unguarded"
    print(f"{label}: Alice={alice_saved}, Bob={bob_saved}")
    print(f"  title={final['title']!r}, summary={final['summary']!r}, "
          f"version={final['version']}")
    return alice_saved, bob_saved, final


if __name__ == "__main__":
    run(False)
    run(True)

The observed output on Linux with Python 3.12.14 was:

unguarded: Alice=True, Bob=True
  title='Draft', summary='New summary', version=9
guarded: Alice=True, Bob=False
  title='Ready to publish', summary='Old summary', version=8

The unguarded run accepts Bob's outdated title and loses Alice's edit. The guarded run preserves Alice's title and reports that Bob did not save.

Notice that Bob's new summary is also absent in the guarded result. The operation rejects his whole proposed replacement. It has no rule for deciding which parts to merge.

The example uses Python's Cursor.rowcount after an ordinary UPDATE. The connection context commits a successful transaction before save() returns. An SQL or commit error raises an exception; it is not converted into a successful save.

For a real endpoint, a zero-row result also needs context: the row might have been deleted, or a tenant or authorisation predicate might not match. Preserve your access-control rules and documented error policy instead of reporting every database miss as an edit conflict.

A database transaction does not span a person's thinking time

SQLite already serialises writes. How can this example still lose an update?

The reads and saves are separate operations. Serialising Alice's write before Bob's write does not tell the database that Bob's values came from an obsolete screen. An unconditional update asks it to replace those values, so it does.

You generally should not hold a database transaction open while someone spends ten minutes editing a form. The version travels across that gap and lets the eventual write express its original assumption.

For operations involving several rows, the single-row example is not the whole design. Put related writes and their checks in an appropriate transaction, define the invariant you need, and handle the database's concurrency errors. One article-version column does not protect every relationship in an application.

The conflict screen is part of the feature

A correct 412 response can still produce a miserable editor if the frontend immediately reloads and discards the user's draft.

Keep three things separate:

• Base: the article Bob originally loaded.
• Local: Bob's unsaved edits.
• Latest: the server's current article, fetched after the conflict.

In this example, comparing the three reveals a straightforward merge: Alice changed the title, Bob changed the summary. The editor can offer a combined draft with both changes.

That is an application policy. Two people changing the same title, or changes to fields whose meanings depend on each other, require a different decision. Even edits to separate fields can conflict semantically.

After reviewing the merged draft, submit it with the ETag belonging to Latest. Another person could save during the review, so a second conflict remains possible.

Do not automatically fetch a fresh ETag and resend the same stale full document. That changes the condition while preserving the overwrite. It turns a detected conflict back into lost data.

Give users a way to copy their draft, inspect the changed fields and retry deliberately. A short message such as “This article changed while you were editing. Your draft is still here” is more useful than an unexplained technical error.

Three details that can quietly undo the protection

Weak ETags cannot satisfy If-Match

A tag such as W/"article-42-v7" is weak. If-Match uses strong comparison, so a weak tag will not match even if its quoted text looks identical.

A revision-based strong ETag requires a disciplined representation contract: the same tag must not describe different bytes. Advance the revision for relevant changes, keep serialisation stable, and account for representation variants. Avoid reusing old identifiers after deletion and recreation.

If-Match: * does not check which version the editor saw

The wildcard checks that a current representation exists. It does not mean “the resource is unchanged since I loaded it”.

For stale-form protection, send the specific tag captured with the original read. Treat it as opaque client-side data.

Optional conditions leave an unconditional path

If your endpoint accepts writes without a condition, those callers can still overwrite newer data.

An API can require conditional requests and use 428 Precondition Required when the required condition is missing. Explain the expected request in the error response and plan compatibility for existing clients.

A useful contract distinguishes:

Caching, retries and stale writes need different checks

The same ETag can participate in different HTTP workflows.

For cache validation, a conditional GET uses If-None-Match: if the stored representation still matches, the server can respond with 304 Not Modified.

For an edit, If-Match asks the server to apply a change only while the supplied version still matches.

Retry deduplication answers another question: is this another attempt at the same intended operation? A version precondition alone is not a stored record of an operation's outcome. If a successful save's response disappears, the old tag may fail on a retry; the client still needs a way to establish what happened.

Choose each mechanism for the uncertainty it resolves. A cache header cannot merge edits, and a retry key does not, by itself, prove that a form was based on current data.

Test with two copies before you ship

Open the same resource in two editors before saving either one. Save a change in the first editor, then submit the second editor's stale copy.

The result you want is observable: the first change survives, the second save is rejected clearly, and the second person's draft remains available for comparison.

Also test a missing condition, a weak tag, deletion during editing, writes from background jobs, and a second conflict during merge. Ensure every path that changes the protected representation maintains its version.

Two green Save messages are a poor success criterion when one person's work has disappeared. Test whether the application preserves both people's intent when their assumptions stop matching.

Sources and further reading

• RFC 9110: If-Match and conditional request semantics.
• RFC 6585: 428 Precondition Required.
• MDN: ETag identifiers and edit collisions.
• MDN: If-Match syntax, strong comparison and wildcard behaviour.
• MDN: 412 Precondition Failed.
• MDN: If-None-Match and cache validation.
• SQLite: UPDATE semantics and transaction isolation.
• Python 3.12: sqlite3 and affected-row counts.