Delivery and troubleshooting
Inspect durable delivery, diagnostics, limits, and interrupted work.
Spans are saved before the provider call and after completion. Finishing a trace writes its final payload to the durable outbox and schedules upload. Model responses and errors pass through even if saving or uploading telemetry fails.
Inspect delivery
let summary = await client.flush()
print("Delivered: \(summary.delivered), pending: \(summary.pending)")flush() waits for queued upload attempts and leaves active traces active. Counts
of delivered, rejected, dropped, and persistenceFailures are cumulative for
this client. pending and active describe its most recently inspected disk state.
A pending count is not a server receipt; inspect persistence failures as well.
Use onDiagnostic: during client construction for structured events:
captureFailed, persistenceFailed, payloadTooLarge, deliveryDeferred,
deliveryRejected, unreadablePayload, storageEvicted, and inactiveTrace.
The hook can include an error description; route it according to your app's logging policy.
Recovery and retry
Startup recovers saved active traces, marking unfinished spans interrupted. Their unknown end timestamps and durations remain absent. Completed spans retain their observed results. A new upload uses the same trace ID as its idempotency key.
Temporary transport failures keep files in Pending and retry on subsequent SDK
activity or flush(). HTTP 408, 425, 429, and 5xx are retryable. Permanent rejection
and unreadable payloads go to Rejected. Inspect credentials and validation errors
before retrying delivery with a corrected destination.
Limits
Each payload is limited to 4 MiB. Oversized finalized payloads are dropped with a diagnostic. Finalization, recovery, and delivery trim active, pending, and rejected storage to 500 files and 100 MiB, evicting the oldest files when necessary. Capture full content only when it is appropriate for your application's recording policy.
If a trace is missing, check the selected app/environment, matching service name, write-key access, connectivity, and diagnostics. Datasets use read keys; native reports use the separate evaluation delivery API.