Docs

Drift detection

Drift detection answers one question continuously: is this integration still behaving the way the evidence says it used to? It works entirely on structural shapes and fingerprints, so it needs no payload values, and it distinguishes provider changes from your own deployments using release context.

What a finding looks like

When observed structure disagrees with the expectation, the comparison produces findings with a stable kind and an exact path:

Code example

{  "kind": "type-changed",  "path": "$.candidate.salary",  "expected": "string",  "observed": "number"}

The four structural kinds are field-removed (a previously expected field stopped appearing), field-added (a new field appeared), field-renamed (deterministic evidence links one removal and one addition as a rename candidate), and type-changed (a field changed primitive type, which short-circuits deeper comparison at that path). Behavioral findings complement them: status and authentication shifts, median latency shifts, retry anomalies, ordering changes, and missing business outcomes.

Where baselines come from

  • Declared contracts. Register an OpenAPI document containing many supported operations, or bind JSON Schema to one explicit operation. Seamward matches each observation to an operation before comparing its shape with that schema. This is the strongest signal because "required" is explicit.
  • Established behavior. Without a declared contract, Seamward groups observations by fingerprint and treats the dominant shape as the baseline, diffing minority shapes against it. This needs at least two distinct shapes to say anything, so a brand-new integration reports nothing until evidence accumulates.
  • Behavioral windows. Each stable operation identity compares a recent 15-minute receipt window against the prior day, so one slow endpoint cannot distort another. Status and authentication shifts use response codes. Latency analysis requires at least 30 observations in each window and reports when median latency rises by at least 100 ms and 50 percent. Retry analysis requires at least 30 privacy-safe correlated operations in each window and reports when the retry rate reaches 20 percent and rises by at least 15 percentage points. A persisting condition re-records at most hourly rather than flooding the timeline.

Retry analysis groups attempts only when observations carry both a keyed idempotencyKeyHash and its non-secret hashNamespace. A logical operation belongs to the window containing its first server receipt, so a late retry does not become a new operation. Neither hash is copied into finding evidence. Counts, exact medians, retry totals, and sequence transitions are aggregated in the database. The worker reads compact distinct operation identities for contract matching rather than individual traffic envelopes. These aggregates preserve the existing windows and thresholds; medians are not sampled or approximated.

The current release also uses an observed-evidence group when an observation does not match any registered operation. It does not compare that traffic with an unrelated declared schema. See Contracts and operations for import formats, operation identity, and current lifecycle limits.

Telling provider drift from your own deploy

Every observation carries optional release context (service, release, commitSha). When a shape changes at the same moment a new release starts processing traffic, the timeline shows both facts side by side, and the investigation starts from "our deploy changed the mapping" rather than a provider escalation. This is why setting release context is worth the two lines of configuration.

From finding to incident

Analysis runs within seconds of ingestion: the job is enqueued in the same transaction that stores your observations. Findings are deduplicated, then grouped with related evidence into an incident, which is the unit an engineer reviews. A finding is evidence that something changed, not proof of customer impact; the incident timeline is where impact gets established.

Structural comparison uses summaries of retained evidence. Late arrivals update counts and time ranges, and retention removes expired evidence from the baseline. Equal-frequency baselines use fingerprint order for a deterministic tie-break. Very large schema sets can pause structural analysis while behavioral detection and expected-outcome reconciliation continue.

Behavioral capacity

Behavioral analysis also bounds the distinct identity metadata processed in a pass: at most 1,000 identities and 8 MiB, with at most 5,000 new findings per pass. Overflow records an independent behavioralAnalysis capacity pause without retrying the job indefinitely or blocking structural analysis and reconciliation. See capacity recovery.

Boundaries

  • No payload values are needed, stored, or compared: structure only.
  • An unexpected field is reported, never silently ignored, but reporting is not judging; harmless additions are yours to dismiss.
  • Detection never modifies your integration or contacts the provider.

Next steps