fespalier-observability
Observing a fespalier app (since 0.8.1) — observe.dart (onEnter, onFocus and onLeave hooks for analytics, logging and titles: which pages they run for, in which order, when they fire after the frame,
SKILL.mdskills/fespalier-observability/SKILL.md
GitHubfespalier-observability
Verified against fespalier
589cf391(2026-10-08), release v0.13.0. These skills ship in the fespalier repository, and CI checks them against its code on every change. Version-sensitive claims say the release they became true in; if your app pins another fespalier, trust that release's code over this page. See Versions.
Two features, both since 0.8.1 and both opt-in: route lifecycle hooks (observe.dart) and
telemetry (what fespalier reports to a FespalierTelemetry sink, and fespalier_otel, the sink that
makes OpenTelemetry spans). They share one watch on the router, so a page event means the same thing in
both. An app that uses neither generates the same app.g.dart as before and ships none of it.
observe.dart
// products/$id/observe.dart: /products/:id and every page below it
import 'package:fespalier/fespalier.dart';
import 'package:my_app/analytics.dart';
void onEnter(Ref ref, {required int id}) => ref.read(analytics).view('product', id);
void onFocus({required int id}) {}
void onLeave(Ref ref, {required int id}) => ref.read(analytics).left('product', id);
Any of onEnter, onFocus, onLeave (at least one), each a public top-level function that returns
void. Parameters: an optional positional Ref ref, then named ones: the segments of its folder and
above, optional nullable query parameters, Uri uri, and TypedLocation route (bound by its type: it
must be called route); onEnter alone may also take {required RouteScope scope} (since 0.11.0, bound by its type, called
scope: scope.hold(provider) keeps a provider loaded while the page is on a navigator, scope.onLeave(callback) runs
when the page is gone). It applies to every page (page.dart) at and below its folder, in
page-less (group) folders too, nest = false pages included; a redirect.dart route never enters.
Order for one page: onEnter and onFocus run outermost folder first, onLeave innermost first.
Read references/lifecycle.md for when each fires (the rule that decides it,
tabs, pushes, redirects), the Ref a hook gets, the page's RouteScope, errors, and the traps.
Telemetry
# pubspec.yaml
fespalier:
telemetry: true # since 0.8.1; run `fsp gen` after
Since 0.19.0, otel: true under the same key has the generated main() start otel_zone and install FespalierOtel
for you, in app.main.g.dart, so lib/main.dart is AppMain.run() and there is no hand wiring to write. It needs
fespalier_otel and otel_zone under dependencies:, and it is refused with main: manual:
fespalier:
telemetry: true
otel: true
By hand, without otel: true, in main.dart, before the router is built: FespalierTelemetry.install(sink). With
otel_zone, the sink is FespalierOtel(isReady: () => observability.isReady) from package:fespalier_otel
(a git dependency next to fespalier, same url, same ref). Nothing is reported until a sink is
installed. Read references/telemetry.md for the install and wiring,
FespalierOtel.endpoint(), OtelZone.runGuarded on the web (before otel_zone v0.8.1), go_router 17 and 18, and testing with
RecordingTelemetry.
Since 0.19.0, FespalierOtel(onScreen: observability.setCrashScreen) names the page a native crash happened on, as
otel_zone.crashed.screen (otel_zone v0.7.0 or later; the pattern only; it is set when the navigation commits,
before the new page is built, so a crash while a page opens names that page; any sink hears the commit through
FespalierTelemetry.commit). See references/telemetry.md, "Wire it".
Since 0.9.0, three more things, all in that page:
- Several sinks.
installholds one sink.FespalierTelemetry.combine([a, b])is one sink that tells each of them everything, in order, each with its own tokens (a sink never sees another's) and isolated from the others' errors;FespalierTelemetry.add(sink)puts one next to the installed one. within. A sink may overridevoid within(Object? token, Object? Function() body)to make a data or action span the current one whiledata()or the action runs (FespalierOteldoes), so an HTTP client's spans are its children, after anawaittoo. Callbodyonce, synchronously; use zone values only, neverrunZonedGuardedoronError:(fespalier refuses that zone and says so once). An app made withtelemetry: truecallsdata()throughtraceDataCall(..., () => data(...))for it.navigateFrom(NavigationSource.notification, () => router.go(...))marks the navigation it starts, and telemetry reportsfespalier.navigation.source(notification,shortcut,widget,link). fespalier sets onlylinkby itself, for a platform link (since 0.11.0).
Since 0.10.0 (fespalier_tolgee, fespalier_cratestack): no new TelemetryOp and no new convention (0.11.0 adds
TelemetryOp.custom, below), so an exhaustive sink still compiled on 0.10. A read through ref.serve and an action that calls intentQueue.submit run inside the existing
data and action spans. fespalier_tolgee has no telemetry in v1, and no sync span exists yet (it would be a custom op, fespalier.cratestack.sync: a new
TelemetryOp value breaks an exhaustive sink, as custom did; nothing from an intent, a row, a subject, a translation key or a server message would ever be sent).
Since 0.11.0: TelemetryOp.custom is a package's own operation, FespalierTelemetry.begin and finish with
TelemetryStart(TelemetryOp.custom, name: 'fespalier.<pkg>.<op>', attributes: {...}) (see
references/telemetry.md). A sink of your own with an exhaustive switch on TelemetryOp needs a
custom case. FespalierOtel exports the name and the attributes verbatim, so they must hold no user value (segment,
query, input, result, token) and the name must be a constant (fespalier.push.open, never fespalier.push.order_42).
FespalierSentry sends neither the attributes nor, by default, a failure as an event (a breadcrumb with the class only;
capture: opts in).
references/conventions.md is contract version 1: every span, event and
attribute name, for anyone building a dashboard or an alert. Adding is allowed within version 1; renaming
or removing is version 2.
Sentry (since 0.9.0)
package:fespalier_sentry is the sink for Sentry, and it is errors first. By default it sends every error and
crash tagged with the route pattern, the app file and the action (fespalier.route, .file, .operation,
.action; fingerprint = default + the file), names the scope after the screen (as soon as a navigation commits, before the page is built, since 0.19.0; its transaction and the tag
fespalier.route, so a crash caught by Sentry's own integrations says which screen it was on), makes one
breadcrumb per page change, and leaves release health to the SDK. Next to fespalier_otel in a
FespalierTelemetry.combine, each event carries otel.trace_id and otel.span_id, so an error links to its
trace. No transaction is sent by default: screen-load transactions, spans and TTID/TTFD are the opt-in,
FespalierSentry(tracing: true) plus tracing: true in FespalierSentry.configure, for a team that has only
Sentry. With Sentry's traceLifecycle: stream the same opt-in streams the spans instead (since 0.19.0).
FespalierTelemetry.add(FespalierSentry()); // in startup(), before the router; add keeps an adapter's sink (analytics); Sentry starts in zone()
Read references/sentry.md for the wiring (Sentry is the outermost zone: no
OtelZone.runGuarded next to it), the order rules, what is and is never sent, tracing: true (one transaction
per screen, the first screen on Android and iOS, no timer), the options, and testing with RecordingSentry.
Analytics with consent (since 0.13.0)
package:fespalier_analytics reports each page the person opens to an analytics service by its route pattern
(/products/:id, never the URL), and only while they have agreed. It is a telemetry sink that an adapter installs
(adapters: [fespalier_analytics]), so the app needs telemetry: true (the adapter reports once when it is missing), and it sits
next to fespalier_otel or fespalier_sentry in the one combine. No analytics SDK is a dependency: you write an
AnalyticsBackend (screenView, screenTime, consentChanged), and Firebase Analytics, PostHog, Mixpanel and Amplitude are
compiled recipes. One call in main() before AppMain.run(): FespalierAnalytics.configure(backend, screenName:); unconfigured, it
reports once and does nothing. Undecided and denied drop every event on the spot: nothing is buffered, granting does not replay,
and the stored answer is loaded in startup() (FespalierAnalytics.sink?.consent = stored) so the first screen is not lost.
Read references/analytics.md for the wiring, consent, screenName from meta.dart and testing, and
references/analytics-backends.md for the four vendor recipes.
The traps
- Hooks fire after the frame.
context.go('/x')followed at once by an assertion sees nothing:await tester.pump()first. A hook never runs insidebuild. - A different segment value is a different page.
/products/1to/products/2isonLeavethenonEnter, whateverremountsays; a query change is no transition. - To redirect, use a guard. A hook runs after the navigation committed; a
goinside one works but is looked at one frame later. (fespalier-guards.) ref.watchin a hook watches nothing that lasts: useref.read. Changing another provider from a hook is fine.- A hook that throws is reported, not swallowed:
FlutterError.reportError, contextwhile running onEnter of products/$id/observe.dart; the other hooks still run, and a widget test fails. - Telemetry on, no sink installed: nothing happens. It is not an error. Install the sink before
AppRoutes.router()runs, or the first navigation is not a span. - Analytics records nothing without
telemetry: true(since 0.13.0): page events reach a sink only from an app generated with it. Nothing is sent until the person has agreed, and what was dropped before is never sent later (no buffer, no replay). - A second
installreplaces the first (since 0.9.0: useFespalierTelemetry.add, orcombineboth). An app that installs Sentry in one place and OpenTelemetry in another has only the last. - Sentry and
OtelZone.runGuardeddo not mix (since 0.9.0). Sentry'sappRunneris the outermost zone;runGuarded's zone would send an uncaught async error to Talker only, and Sentry would never see it. - Two
ui.loadtransactions per screen (tracing: true): a plainSentryNavigatorObserver()makes its own. UseFespalierSentry.navigatorObserver(). - Nothing in Sentry: an empty
SENTRY_DSN(the SDK and the sink are off), noinstall, notelemetry: true, or, for transactions, notracing: truein both places or a release sample rate of 0.1. - A sink's
withinmust not give its zone an error handler (since 0.9.0).runZonedGuardedthere would strand a failingdata()on its loading view, so fespalier runs the call outside that zone and printsfespalier telemetry: <Sink>.within changed the error zone ...once. UserunZoned(body, zoneValues: {...}). fespalierandfespalier_otelmust be the same git dependency (sameurl, sameref), or pub refuses to resolve; see fespalier-troubleshooting (its observe.dart and telemetry page).otel_zonebefore the rc.4 line (up to v0.7.0) forces go_router 17 in an app that uses it (otel_go_router^0.2.0 caps it) and is on the rc.3 dartastic line, whichfespalier_otelno longer resolves with since 0.19.0. From v0.8.1 (64c4661) it accepts go_router 17 and 18; fespalier accepts both.OtelZone.runGuardedleft a Flutter web app blank before otel_zone v0.8.1. From v0.8.1 it runs its body on the web. On an older one, return the body withoutrunGuardedwhenkIsWebis true, and bump the ref.
Where the code is
- Hooks:
packages/fespalier/lib/src/lifecycle.dart(the router watch,RouteHooks,observeAttach);route_scope.dart(RouteScope,pageInstanceId); the generator readsobserve.dartincli/src/resolve.rsand writesRouteMatcher.observe,_observeAtandAppRoutes.attachintoapp.g.dart. - Telemetry:
packages/fespalier/lib/src/telemetry.dart(the sink API,combine,within,NavigationSourceandnavigateFrom, and what the generated call sites reach;traceDataCallis indevtools/devtools.dart),navigation_kind.dart(theinitial/go/push/pop/replace/refreshclassifier DevTools shares) andversion.dart; the adapters arepackages/fespalier_otel/and, since 0.9.0,packages/fespalier_sentry/(traceOfandlinkTraceintelemetry.dartare how the two share a trace). - Analytics (since 0.13.0):
packages/fespalier_analytics/(lib/src/sink.dartthe sink andFespalierAnalytics,lib/fespalier_adapter.dart,lib/testing.dart). - Scaffold:
fsp new 'orders/[id]' --observewritesobserve.dart. - The example is
examples/telemetry: lifecycle tests and span tests, on go_router 18 since 0.19.0.