An interactive guide to the diagnostics client contract, real production signals, and the storage-to-upload machinery beneath each SDK.
@RestrictedAmplitudeFeature; Swift exposes it through @_spi(Internal); TypeScript exports the core type while prefixing control methods such as _flush.All three platform implementations speak in four signal types—tags, counters, histograms, and events—and expose a flush operation. The shape is intentionally small; persistence and concurrency are runtime-native.
| Method / setting | Browser / TS | iOS / Swift core | Android / Kotlin core |
|---|---|---|---|
setTag | ✓ shared | ✓ shared | ✓ shared |
increment | ✓ shared | ✓ shared | ✓ shared |
recordHistogram | ✓ shared | ✓ shared | ✓ shared |
recordEvent | ✓ shared | ✓ shared | ✓ shared |
flush | _flush() | flush() | flush() |
setTags | — | ✓ | ✓ |
| Read tags | — | getTag(s) | — |
| Lifecycle extra | _setSampleRate | didLastRunCrash | close |
| Customer setting | enableDiagnostics? | enableDiagnostics | enableDiagnostics |
Search or expand a card. These are production call sites in the SDKs, not invented examples.
A last-write-wins string label. Tags identify the SDK/runtime rather than count an occurrence. They survive flushes so the next payload keeps its context.
// Browser initialization
diagnosticsClient.setTag('library', LIBPREFIX + '/' + VERSION);
diagnosticsClient.setTag('platform', 'Web');
diagnosticsClient.setTag('web_environment', getRuntimeEnvironment());Production call site ↗Merges app version, device, OS, platform, and SDK version in one operation. Browser performs the equivalent through repeated setTag calls.
val staticContext = buildMap {
put("version_name", contextInfo?.appVersion ?: "")
put("device_model", contextInfo?.model ?: "")
put("platform", contextInfo?.platform ?: "")
}
setTags(staticContext)Production call site ↗Counters add deltas across calls and storage ticks. This powers sent/dropped totals. Passing a batch size avoids one call per analytics event.
if (status in 200..299) {
increment("analytics.events.sent", events.size.toLong())
} else {
increment("analytics.events.dropped", events.size.toLong())
}Production call site ↗Each value updates count, min, max, and sum. Upload computes avg = sum / count; raw observations are not included. There are no percentiles.
const startTime = performance.now(); // Build autocapture hierarchy… this.diagnosticsClient?.recordHistogram( 'autocapturePlugin.getHierarchy', performance.now() - startTime, );Production call site ↗
Events include a timestamp and JSON-compatible properties. A counter answers “how many?”; events explain “what happened?”. Only ten survive in a reporting window.
recordEvent(
name = "analytics.events.dropped",
properties = mapOf(
"events" to events.map { it.eventType },
"count" to events.size,
"code" to status,
"message" to message,
),
)Production call site ↗Forces the normal five-minute operation. Counters, histograms, and events clear before or as upload starts; tags remain. Browser’s underscore signals SDK-internal ownership.
public func flush() async {
guard shouldTrack,
let snapshot = await storage.dumpAndClearCurrentSession()
else { return }
await uploadSnapshot(snapshot)
}iOS implementation ↗getTag/getTags wait for startup tags. didLastRunCrash reads crash-marker state. Callback conveniences serve non-async callers.
Android adds close() for client/storage channels and registers a weak JVM shutdown hook. Browser adds _setSampleRate, recomputing lifecycle sampling from the original timestamp.
Defaults to true on all three platforms. That does not guarantee collection: default sample rate is zero and remote config must select the client. The sample decision is stable for the client lifecycle.
Browser configs.diagnostics.browserSDK
iOS diagnostics.iosSDK
Android diagnostics.androidSDK
fields: { enabled, sampleRate }Browser config gate ↗A simplified but faithful model: calls update memory, the one-second tick persists a snapshot, and flush builds the upload payload while retaining tags.
The client is local-first: compact in memory, persist after one second, upload after five minutes. Terminated mobile-session data is recovered and attempted on next launch.
AMP_diagnostics_{first 10 API-key chars}, schema version 1.com.amplitude.diagnostics / hashed instance / session timestamp.events.log.close() closes channels; JVM shutdown hook is best-effort.Tags overwrite. Counters add. Histograms merge count/sum and min/max, then calculate average at payload time. Events keep full structured examples up to the cap.
Demand-driven, not permanent polling. The first mutation schedules persistence and flush. Browser also stores its last-flush timestamp and can flush overdue data after restart.
All POST JSON to the regional US/EU /v1/capture endpoint with X-ApiKey. Swift/Kotlin also send X-Client-Sample-Rate; current TS does not.
iOS consumes a previous crash on next run. Browser adds global error/rejection listeners only when sampled and only records errors matching a registered SDK script URL.
Panel names below were read from the supplied live dashboards.
All three clear/delete active counters, histograms, and events before the network result is known. Failed requests are logged but not re-queued: at-most-once attempt, not guaranteed telemetry.
Properties may contain event types, server messages, stack traces, filenames, and crash reports. Avoid user identifiers and raw customer payloads; assume fields leave the device.
Clients hash their initialization timestamp against a clamped 0…1 rate. Remote-config updates reuse the seed, avoiding a new random decision on every call.
enabled && sampledIn gates timers/storage. Swift deletes stored files when disabled. Kotlin stops deadlines. Browser returns early when tracking or IndexedDB is absent.
Every platform caps current-window structured events at 10. Browser also caps unique in-memory tag/counter/histogram keys at 10,000 each. Mobile logs rotate at 256 KiB.
An AsyncStorage adapter exists, but IS_DIAGNOSTICS_CAPTURED is currently false and the default sample rate is zero. If enabled later, one serialized blob is used; without AsyncStorage it degrades to memory-only.
Commit-pinned links keep the guide auditable after main moves. The iOS implementation lives in AmplitudeCore-Swift, which Amplitude-Swift consumes.