Optional SDK diagnostics

Flutter and Web reporting is off by default. Without a diagnostics configuration, the SDK sends no telemetry requests. The application owner explicitly decides whether to enable it. Only SDK failures are reported; the host application’s general exceptions, user identity and device identity are not collected.

Permissions and setup

An operator first configures a public HTTPS diagnosticsEndpoint in the public SDK configuration file. It must end in /telemetry/v1/sdk-events. The management API must be able to reach the private Collector. The public setup response never includes Collector addresses or credentials.

1. As a workspace Owner/Admin, open Distributions, choose a distribution, and find Diagnostic keys.
2. Enter a label, select Preview or Production, then choose Create diagnostic key.
3. Copy the key immediately and select I have saved the key. Only its hash is stored. If a response was lost or the key was not saved, revoke it and create another; repeating the same request does not reveal it again.
4. In SDK setup, choose Flutter or Web and follow the optional diagnostics example. Supply the diagnostic key separately from the read key.
5. For browser applications, add the exact application origin to that distribution. Cookie-based sign-in is not used for diagnostic submission.

Diagnostic keys cannot download translations or manage projects. Read keys cannot submit diagnostics. Members do not receive Grafana access or a customer error-list screen.

Web

Add this optional field to the configuration already passed to createClient or the Node adapter:

const diagnostics = {
  endpoint: publicConfiguration.diagnosticsEndpoint,
  key: diagnosticKey
}
// Include { diagnostics } only after validating that an endpoint is configured.

The existing onDiagnostic(error, stage) callback remains available. Callback exceptions and reporting failures cannot replace valid translation content. dispose() cancels queued reports. If a Content Security Policy is used, allow the explicitly configured diagnostic origin in connect-src.

Flutter

Add the optional field to LocalisyncConfig used by createLocalisyncClient:

diagnostics: DiagnosticsConfig(
  endpoint: Uri.parse(diagnosticsEndpoint),
  key: diagnosticKey,
),

Keep application versions as strict SemVer. Development HTTP remains an explicit isolated-loopback exception; it is unavailable in release-mode Flutter applications. Reporting uses the platform adapter; custom core clients may inject a DiagnosticSink without coupling the core to HTTP.

What is sent

Reports include SDK family/version, application version, fixed failure code, operation stage, occurrence count and time. Available release/revision context may be included. No key name, translation, interpolation argument, raw message/stack, arbitrary metadata, persistent device identifier or user identifier is accepted.

The memory-only buffer holds at most 100 grouped events, below 128 KiB, for at most 15 minutes. Serialization and networking happen after the synchronous read returns. Batches contain at most 20 events / 32 KiB. Repeated failures are counted; each batch has at most two attempts with finite timeouts. No polling or extra publication check starts. There is no persistent reporting queue. Delivery is best-effort: a lost acknowledgement can result in a duplicate report, and unavailable storage can result in a dropped report.

Failures, privacy and revocation

• 401: check key type, channel and revocation; verify the browser origin.
• 400: check SDK/schema version and clock accuracy; old events expire.
• 429: reduce failure volume and respect the rate limit. Reports may be dropped.
• 503: ingestion or Collector is unavailable. Translations continue; acceptance is not invented.
• No configured endpoint: ask the operator to configure it, or keep reporting disabled.

Revoke diagnostic key takes effect for subsequent authorization checks. Requests already accepted before revocation are not erased. Remove the diagnostics configuration to stop future reporting from an application. Revocation does not delete downloaded translations or revoke a separate read key.

See the diagnostic API and monitoring guide for operator access and retention. SDK diagnostics are not a replacement for the application’s own consent/privacy review.