Network diagnostics (unreleased source)

Release status

This page describes source completed on 2026-10-14. JS SDK 0.4.0 and Flutter 0.2.1 are not yet published to their registries. Collector/Dashboard deployments and consuming applications have not automatically upgraded. Test a reviewed source revision before adopting a published release.

JS integration

Use createHealthGuardClient for Web, createMiniProgramClient for mini-programs and createUniAppClient for uni-app. Each accepts optional networkDiagnostics:

import { createHealthGuardClient } from '@health-guard/sdk-web';
const client = createHealthGuardClient({
  appKey: 'your-app-key',
  endpoint: 'https://collector.example.com/api/events/batch',
  release: 'your-app-version',
  environment: 'production',
  autoCapture: true,
  networkDiagnostics: true
});

Consume source that contains the implementation, or install the corresponding SDK after publication. Business apps configure the SDK rather than copying classification and replay logic. Advanced options are networkDiagnostics: { cooldownMs: 30000, maxPendingEvents: 100, storage }, where storage supplies synchronous getItem/setItem. Platform storage is used by default, with an in-memory fallback when unavailable. Initialize once and call dispose() when the client lifecycle ends.

Evidence

• category: offline / dns / connect / tls / timeout / cancelled / http / unknown. Classification is a request/device hint, not a confirmed root cause.
• network: supported online state, transport, effectiveType, OS validated/metered/VPN hints. Unsupported fields are omitted.
• targetOrigin: scheme, host and port only; no path, credentials, query or fragment.
• timing: readable DNS, connect and TTFB milliseconds; missing data stays unavailable rather than zero. Cross-origin H5 phases depend on Timing-Allow-Origin, and timings from an earlier request to the same URL are not reused.
• recentChanges: up to five platform status notifications in the last two minutes, without network identifiers.

JS collection is passive. Flutter 0.2.0 supports explicitly allowlisted DNS/TCP/TLS/health probes, disabled by default; arbitrary targets are rejected. Generic browser Failed to fetch cannot distinguish DNS, TLS, CORS or server reachability. An online device does not prove the business service is reachable.

Privacy and replay

Detailed enrichment defaults to once per origin per 30 seconds, with at most 20 remembered origins. Throttling does not discard HTTP failures. JS and Flutter queues retain at most 100 events, dropping the oldest on overflow. Replay keeps original IDs, times and versions; the collector accepts an event ID idempotently.

New network evidence and HTTP replay omit headers/bodies, SSID/BSSID, IP and carrier identity. Persisted request URLs remove user information, all queries and fragments. Existing manually supplied context/request data still requires application privacy controls. With diagnostics enabled, default transport requires accepted to match batch size; HTML 200 is not acknowledgement. Custom transport must resolve only after actual acknowledgement.

Rollout and acceptance

Update and verify Collector/Dashboard, publish SDKs, then upgrade and release consumers. Existing apps and historical events do not gain missing fields automatically. Review handled exceptions and configuration before removing duplicate app reporting. Offline/restart replay, network switching, VPN and real alert delivery need separate acceptance.

See the main-repository guide and Flutter integration.

See Flutter integration for detailed diagnostics and migration configuration.

Occurrences versus historical summaries

New HTTP fingerprints include origin, method, path, environment, platform, status and original failure phase. Historical IDs, fingerprints and repair records remain intact; mixed legacy groups are not automatically split, so new and legacy groups may coexist. Alerts identify the triggering occurrence separately from historical issue summaries. Late events and startup backfill use event time for the latest summary/release.

Flutter 0.2.1 offers optional IO acquisition/header-wait evidence; see Flutter SDK. Unmeasured original subphases stay unavailable. A connection timeout can coexist with healthy server HTTP logs; correlate X-Request-ID and use original-connection tracing or packet capture for further DNS/TCP/TLS/device attribution.