error_reporting/error_reporter_example library

CANONICAL error-reporter examples for dreamic — the single source of truth.

Dreamic is backend-agnostic — it ships no concrete reporter and depends on no crash-reporting SDK. To report errors you implement ErrorReporter in your app and register it. These COMMENTED examples are the canonical references every consumer copies/reconciles against; the dreamic-dev scaffolding/app/template_*_error_reporter.dart files are retired and point here (ERH-024). Consumers self-sync against the dreamic CHANGELOG.md version-bump entry — there is no automated parity test (ERH-025).

All backend imports are kept commented so dreamic-public stays dependency-free (no Sentry/Crashlytics/Firebase dependency is added here).

What each canonical reporter must carry (the full hardening of this package's error-reporting contract — see the ErrorReporter docstring + CHANGELOG):

  • Full parity: override recordError, recordFlutterError, addBreadcrumb, setUser, and clearUser (extend, not implement, so a backend without one of these can omit it).
  • maxBreadcrumbs = 250 on ALL platforms (Sentry) so verbose logd volume does not evict the high-signal info/warn/error trail. Measure against the ~1 MB per-event payload limit at breadcrumbLevel = debug; lower (e.g. 150) if a realistic verbose event approaches it (BEH-10).
  • A beforeBreadcrumb / beforeSend redaction safety net (Sentry) for SDK-auto / web-JS breadcrumbs that bypass Logger.breadcrumb()'s central redaction. dreamic's Logger redacts everything routed through it; this is the second layer for what isn't (BEH-8).
  • The LogLevel→SentryLevel map IN THE SENTRY EXAMPLE ONLY (ERH-026) — it is Sentry-specific and must NOT live in dreamic-public (which has no Sentry type). dreamic-public gating uses LogLevel only.
  • The spike-gated web-capture config — Path A′ (the recorded decision, see the Sentry example): options.autoInitializeNativeSdk = false PLUS an explicit options.transport = HttpTransport(...) on web. Do NOT attempt the infeasible globalHandlersIntegration exclusion (ERH-042 / ERH-002 superseded).

The load-bearing rules (also in the ErrorReporter contract docstring + CHANGELOG):

  • All breadcrumbs flow through Logger.breadcrumb() (never Sentry.addBreadcrumb() directly) — the central-redaction ingress contract (ERH-020).
  • main() wraps runApp in DreamicErrorHandling.runGuarded(...).
  • Wakelock is mobile-only (dreamic guards it !kIsWeb for you).

Functions

exampleBreadcrumb() → void
Breadcrumbs — the ingress contract (ERH-020).
exampleMainComposite() → void
main() — pass the OR'd config flags across the children you compose (the flags live on ErrorReportingConfig, not on the individual reporters — ERH-007). Any Firebase-dependent child ⇒ requiresFirebase: true; any child that manages its own handlers ⇒ managesOwnErrorHandlers: true. (A Sentry + Crashlytics composite where dreamic owns the handlers ⇒ requiresFirebase: true, managesOwnErrorHandlers: false.)
exampleMainCrashlytics() → void
main() — Crashlytics REQUIRES Firebase first, so flag requiresFirebase: true (dreamic attaches it at the post-Firebase bootstrap step) and enableOnWeb: false (no web SDK). Under Path A′, web capture is owned by the Dart web-JS handler + a web-capable backend (e.g. Sentry); Crashlytics stays mobile.
exampleMainSentry() → void
RECOMMENDED main() — dreamic owns the handlers; main() wraps runApp in the guarded zone and (Path A′) installs the early web-JS handlers.
exampleNoReporting() → void
No reporting (the default): omit configureErrorReporting entirely, or pass const ErrorReportingConfig() with a null reporter. dreamic logs to the console only.
exampleUserContext() → void
Wiring user context from auth-lifecycle callbacks (any reporter that overrides setUser/clearUser):