SDK telemetry
From v0.5.3 the Guardian SDK can send diagnostic events about its own behaviour to Surt: how long each phase of a call took, internal errors, and attestation failures. Surt uses them to detect latency and crash regressions per device model and OS version. Telemetry is off by default and needs no code change in your app.
Events
| Event | Sent | Contents |
|---|---|---|
sdk_timing | after every verify() and collect() | flow (verify or collect), outcome (succeeded or failed), milliseconds per phase (collection, permission, attestation, client_ip, network_intel, total), and the request time for verify() or the encryption time for collect() |
sdk_error | when a call fails inside the SDK | the error message, the operation that failed, and up to ten stack frames |
attestation_failure | when App Attest or Play Integrity does not produce a token | the failure reason |
Every event also carries the SDK version, the platform (ios or android), the device model (for example iPhone15,2 or Google Pixel 8), the OS version, the Android API level, the session ID of the call, and a timestamp.
What is not sent
- No customer ID, name, or email. Surt associates the event with your organization and the session through the JWT.
- No user-set device name. The model is the hardware identifier.
- No transaction data, location, or any other field of the verification payload.
How it is enabled
Telemetry is enabled per organization by Surt. Contact Surt to turn it on or off for your organization. There is no setting in GuardianOptions.
When it is enabled:
- The JWT your backend receives from the preflight endpoint carries the telemetry setting. Surt can sample, so the setting may differ between sessions.
- The SDK reads the setting once at the start of each
verify()orcollect()call. - If the setting is off, or the call has no JWT, the SDK sends nothing.
Effect on your app
- Events are sent on a background thread after your callback or promise has completed. They do not add latency to the result.
- Each event is one request with no retries. A failed send is dropped and logged at debug level.
- A telemetry failure does not change the result of
verify()orcollect(). - Events are a few kilobytes at most.
Reading the same timings locally
The per-phase durations in sdk_timing are the values returned in diagnostics.timings on every verify() and collect() result, on Android from v0.5.2 and on iOS from v0.5.3. See Result diagnostics.