Dart best practices
Release, sampling, analytics, and feature flags for the talaria package.
Release
Pass release as a version or git SHA through --dart-define=APP_RELEASE=… or your own environment. Local runs should still send one. Release health groups on that string.
API key and environment
The API key chooses the environment. Do not add an environment field to TalariaOptions. Compile the define into the binary you ship. A development key is for local runs. Restart after rotating a rejected key. The failure is cached for about 24 hours.
Sampling
Successful traces follow the traces sample rate from Project settings. Error traces stay. A response with retry: false stops that signal until the process starts again.
Project settings
Tracing and analytics follow Project configuration. Dart always fetches sdk/getConfig.
Analytics
Enable Analytics in Project settings. This package has no consent-banner integration. optIn is the call that allows sending when you have already collected consent in the app. Server-side tools pass userId or anonymousId on the call.
await Talaria.analytics.identify('user_42', traits: {'plan': 'pro'});
await Talaria.analytics.track(
'Invoice Sent',
properties: {'plan': 'pro'},
userId: 'user_42',
);page and screen are on the same client. See Product analytics setup.
Feature flags
final on = await Talaria.flags.boolVariation('new-checkout', false);stringVariation and jsonVariation take a key and a default. When you need local evaluation (a server that should not round-trip on every read), call Talaria.flags.loadDefinitions() once at startup. That requires flags:definitions on the API key. Mobile clients should stay on remote evaluate.
Privacy in events
setExtra is a map of app metadata. Do not put tokens or raw queries there. DbSpan stores a sanitized statement, not bind values, when you pass SQL through it.
Verify
search_errors with environment: development for a local key. get_project_stats analytics counts stay at 0 while analytics is off.