Operate and evolveLogging and diagnostics

Logging and diagnostics

Record bounded operational context without exposing keys or confusing logs with application state.

Log local commits, authorization, transport, and subscription outcomes separately. A queued sample does not confirm remote consumption.

Configure the process owner

Configure managed logging once under its process owner. The API controls runtime context, process context, sampling, sinks, flush, and health. Logging and Platform sessions have separate lifetimes. Do not reinstall the logger for each screen or peer-session restart.

Rust can compose the tracing pipeline through its public logging extension surface. Generated bindings use managed logging operations rather than Rust subscriber traits.

Select a local sink appropriate to your deployment. Browser logs use memory-supported behavior rather than native file assumptions. Configure an exporter only when your deployment authorizes its endpoint and network disclosure.

Record outcomes with stable context

Use structured attributes for operation kind, public peer identity, scope, event identity, stream session, selected transport, and stable error code. Bound attribute sizes and sampling rates. Keep high-cardinality values out of metric labels unless your telemetry contract explicitly permits them.

Useful diagnostic distinctions include:

ObservationInterpretation
Local commit succeededLocal durable boundary passed
Event locally acceptedNotification entered the publication path
Delivery unavailableNo permitted live path completed the requested delivery
Record pendingThis peer still lacks the resolved durable context
Subscription endedThis receiver no longer receives samples
Samples droppedCapacity or transport policy omitted data

Log these as separate outcomes. A successful local save must not mask a failed publication. A disconnected sample path must not be reported as a storage failure.

Protect secrets

Never record private keys, database encryption keys, mnemonic phrases, access tokens, or serialized delegation credentials. Scrub untrusted payloads and exceptions before writing them. Do not rely only on a logger's default redaction for newly introduced secret fields.

Peer and operation identifiers can support correlation without recording the application payload. Apply your deployment's data classification to coordinates, measurements, documents, and external protocol packets.

Flush and inspect health

A flush reports the logger's flush outcome. It does not certify remote storage, peer synchronization, or external ingestion unless the selected sink explicitly supplies that acknowledgment.

Inspect queue pressure, dropped entries, and sink health. Keep application work usable when an optional log exporter is offline. Bound retry and shutdown flush time so diagnostics do not hold local startup or UI work open.

Include these inputs in a fault report:

  • Documentation edition, SDK package version, binding API version, and target.
  • Selected behavior defaults and public peer identities.
  • Operation correlation and the exact structured error.

Exclude credentials and raw secure-store contents. Use offline recovery and errors to choose the recovery action.