Skip to main content
A correlation ID is an opaque value you attach to an event so Reconify can show you every other piece of evidence that came from the same business transaction, even when that transaction crossed several services and produced several operations. Reconify stores it as metadata. It never changes which operation an event belongs to.

​
Three identities on one event

Every event already carries reference and entity_id. correlation_id is a third, optional identity that answers a different question. Correlation is shared context; causation points to one earlier event. See Causation IDs for the distinction. reference is local to one flow: the service that owns a payment names it, and every event for that payment repeats it. correlation_id is shared: every service touching the same checkout, order, or saga repeats the same value on whatever flow it happens to report.

​
What a correlation ID does not do

The field adds a link, and it changes nothing about identity or evaluation.
A correlation ID never merges operations. Two events that share a correlation ID but carry different references remain two separate operations, with separate flows, deadlines, and findings.
Operation identity stays exactly what it was before you added the field:
  • Events are grouped into an operation by organization and reference.
  • Flow definitions, stages, SLAs, and deadlines are unchanged.
  • Findings are opened and resolved per operation, not per correlation ID.
  • Adding the field to a service that did not send it before changes nothing about existing monitoring.
This is deliberate. Deadlines and findings depend on a single, stable operation identity, and a value propagated by many services is not a safe identity to evaluate against.

​
Where it shows up

One correlation ID reaches every operation that carries it: One correlation ID linking two separate operations, each with its own flow and its own events. Search in the dashboard returns two collections, bounded independently:
  • Direct results match the value you typed against events, operations, and issues, including a partial match on a correlation ID.
  • Related activity expands an exact match into the other evidence that shares a correlation ID, marked so you can tell it apart from what you searched for. Searching a reference also expands through the correlation ID its events carry.
Provider evidence keeps the value too. When Reconify generates a terminal payment event from a tracked provider integration, it copies the correlation ID from the initiating payment.initiated event. If that event had none, the generated event has none. Related activity is a dashboard investigation surface. The public API has no search endpoint, and event reads return both optional identifiers.

​
Value rules

Four rules govern the value itself, and ingestion enforces all of them. A value that fails these rules is rejected for that item with code invalid_event and field: "correlation_id", while other items in the same batch are unaffected. See the error catalog.
correlation_id is part of the event payload used for idempotency. Retrying a stored id with a correlation ID that was added, removed, or changed returns idempotency_conflict for that item, so the value belongs on the event before it is first sent.

​
Keep the value opaque

Reconify treats the value as an opaque string and never parses it, so the only requirement is that it stays safe to store and display:
  • Secrets, tokens, card data, email addresses, and other personal data stay out of it.
  • The same value in another organization is a different, unrelated value, because correlation never crosses tenants.
  • Correlation values never become metric labels.
Next: Trace a flow across services covers choosing a value, propagating it, and investigating with it.