Skip to main content
Sentrial deduplicates repeated OTLP spans using their trace and span identities within the resolved session. A retry must preserve those identities. Recording a new tool attempt should use a new span identity so the attempt remains visible.

​
Retrying a telemetry request

The current SDK sends telemetry to POST /api/otel/v1/traces. The TypeScript 0.6.0 transport serializes a request once and reuses that body for its bounded HTTP retries. Re-delivery of the same identified spans does not insert another copy of each event into the same session. Prefer the SDK’s built-in transport retry over calling the tracking method again to recreate an already-recorded event. A new tracking call can generate a new span ID. Sentrial cannot infer that two different span IDs represent the same telemetry delivery just because their text matches. For a custom OTLP exporter, retain valid identifiers across network retries and keep session identity and parent relationships consistent. The database deduplication key includes the resolved session, trace ID and span ID. It is not a global content hash or a promise to merge different sessions.

​
Re-delivery is not an event-edit API

Do not reuse a span ID to replace a previous tool result with different content. Preserve the original result and record a distinct later result or attempt. Re-declaring incompatible retained content references can be rejected. Session completion is a separate supported lifecycle operation. The SDK can repost its root span to finalize a session without inserting another root event. This does not make arbitrary changes to previously ingested child events an update contract.

​
Legacy REST compatibility

Older SDKs can use POST /api/sdk/sessions and POST /api/sdk/events through compatibility adapters. Those adapters generate internal trace/span identities for each new POST. Repeating a session-create or event-append POST must not be assumed idempotent. In the legacy event body, caller-supplied traceId and spanId are retained as client tracing metadata; they do not become the adapter’s internal event deduplication key. Do not depend on an Idempotency-Key header to change this behavior. Use the current SDK or a correctly identified OTLP exporter for retryable telemetry delivery. See Sessions Ingestion and Events Ingestion for the supported transports and required scopes.

​
Business actions need their own guarantees

Telemetry deduplication does not prevent a tool from charging twice, creating two tickets or submitting two claims. Your tool or business service must provide its own idempotency mechanism and authoritative receipt. Keep that business action identifier alongside the trace evidence. A trace ID identifies execution, and a span ID identifies a recorded operation; neither is a substitute for a downstream service’s idempotency key or completion receipt.

​
Verify what arrived

After a completed example prints its session ID, inspect delivery with the published CLI and an appropriately scoped workspace key:
Inspect reported delivery gaps and warnings, and compare the recorded tool arguments, results and attempts with the source run. Follow pagination when reading events. An acknowledgment or a successful Doctor check does not establish signal accuracy or prove that the business action completed. The CLI reference describes read scopes and diagnostic outcomes.