Identity correction and instrumentation doctor

Correct an identity link

Open Customers → a person → Identity links, choose the identifier and select Preview separation. The preview shows the current owner, number of linked identifiers, recent mapping history and the exact effects. Owners and administrators can select a reason and choose Separate identity. API keys require persons:correct; preview/history requires persons:read. SDK analytics:write cannot correct identities.

Separation creates a new anonymous person with no properties and moves one alias to it. The original person must retain at least one other alias. Existing profile properties and their mutation history remain on the original person because their alias ownership is unknown. Future property updates sent with the separated alias populate its new profile. Both historical and future signals carrying that alias resolve to the new person after the asynchronous identity mirror and dictionary update. Stored aggregates and account memberships are not rewritten. This is an all-time alias separation, not a date-based split of a recycled identifier.

The separated person blocks automatic identification links in both directions. Calling identify with the separated device as the anonymous ID will not promote or merge it into another user. Calling identify with it as the stable ID does not attach another alias. Use a new anonymous identifier after logout/shared-device changes in your SDK. There is no automatic undo or manual reattachment operation in this version.

History records new assignments, automatic repoints, and operator corrections with the operator's user/API-key identifier and a fixed reason. It returns the latest 50 changes. baseline_unknown describes an existing assignment at migration time; it does not claim to explain older merges. History is removed when the owning alias is erased, including organization/project deletion. It contains no profile property values.

A revision binds the preview to the source profile and its alias mappings. Concurrent changes cause HTTP 409 / gRPC Aborted: reload the preview and review it again. If a request times out, inspect history before retrying; reusing an applied revision cannot create a second person. Do not treat a conflict as proof that the earlier request failed.

CLI (uses the active --project):

anectico persons correct-identity 'device-id'
anectico persons correct-identity 'device-id' --apply --revision '<reviewed-revision>' --reason shared_device

REST: GET /api/v1/identity/corrections/preview?project_id=…&distinct_id=…, then POST /api/v1/identity/corrections?project_id=… with distinct_id, revision and reason (shared_device, recycled_id, or incorrect_identify). The server derives organization and actor from the credential; project-scoped credentials cannot select another project.

MCP: use execute_read_action with preview_identity_correction, then the write gateway's correct_identity action. The write gateway requires its normal confirmation token in addition to the reviewed revision. These actions belong to the admin profile.

Find out why data is missing

Open Check instrumentation from the telemetry setup checklist, or visit /configure/instrumentation. Select a project and run checks. The doctor queries traces and logs in the last 15 minutes. Optionally supply an environment and a trace ID produced by your own application. Generate a trace with your installed SDK, ensure it is sampled, flush the exporter and copy its 32-character hexadecimal trace ID into the doctor. Uppercase and lowercase hexadecimal IDs are accepted and searched in canonical lowercase.

The results distinguish:

• visible: at least one matching record reached queryable storage; this does not prove complete delivery.
• filtered: a search without the environment filter found traces, while a recheck with it found none. Inspect the returned traces' environments; the queries are separate snapshots and data can change between them.
• withheld: the credential cannot read the signal; presence was not checked.
• unavailable: the query failed; there is no missing-data conclusion.
• unknown: no matching record, or the relevant evidence is not available.

The doctor cannot currently observe your SDK configuration, export acceptance receipts, queue checkpoints, sampling decisions or retention outcomes. It explains these limits and provides next actions rather than diagnosing absence as data loss. The general check covers traces and logs; journey mode additionally checks errors, events and optional replay. Metrics are not checked. It never sends test telemetry automatically.

CLI: anectico doctor instrumentation [--trace-id ID] [--environment production]. REST: GET /api/v1/instrumentation/doctor?project_id=…; optional trace_id, environment, start_time and end_time (RFC3339, positive window of at most seven days). The response includes the actual project, event-time window, check time and explicit partial status. MCP: the instrumentation_doctor read action is available in investigate/admin profiles.

The entry requires query:read. Query independently enforces traces:read and logs:read; no elevated credential is used to bypass missing signal permissions. Selecting another project with a project-scoped key is refused.

Verify a customer story

Follow Verify your setup to create a controlled sample. The same endpoint and MCP action accept person, event_name, browser_service, backend_service and expect_replay. Supply all four string fields plus trace_id to request journey verification. Service names must differ. REST/MCP require replay only when expect_replay=true; REST rejects empty, malformed or repeated expect_replay values; the CLI enables it by default when --person is set.

The response adds journey_verified, canonical person_id, the observed issue_id and individual journey_* checks. A verified journey can still have partial=true: SDK configuration, sampling, queue lag and retention attribution remain unknown. The report is assembled from bounded reads, not an atomic snapshot. Concurrent identity corrections and arriving events can change later results.

Timeline reads stay pinned to the initially resolved person and only accept aliases from that profile. The named event and replay must match the same linked browser session. Start a fresh replay session inside the selected window for this controlled test: a replay that started before the window is not verified by these timeline reads.

Journey verification also needs persons:profile:read, persons:read, errors:read, analytics:read and, when replay is requested, replay:read, in addition to query:read and traces:read. Log access is optional for the connected story; its separate check remains withheld when logs:read is absent. No missing scope is bypassed.