NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
pub.dev
pub.dev, #1857 most downloaded on pub.dev
Grafana Faro SDK for Flutter applications - Monitor your Flutter app with ease.
Latest stable
0.18.0
Last release 24 days ago
29 Oct 2026
Ships fairly regularly
a new release about every 4 weeks
Nearly every release is documented
notes for 24 of 24 stable releases
Nothing withdrawn
no release was ever pulled
2 years old
27 releases · first in 2025
Drag across the ruler to compare, or tap a release to open it.
Requires `equatable` 3. The equatable dependency is now ^3.0.0 instead of ^2.0.8. Apps that pin equatable 2 must upgrade it (#356).
equatable 3. The equatable dependency is now ^3.0.0
instead of ^2.0.8. Apps that pin equatable 2 must upgrade it
(#356).Offline telemetry stays cached when delivery fails. Replay now waits for collector acceptance before removing data and ignores replay-related session invalidation. Online startup retries cached data after initialization; replay discards it when collection is disabled. Custom transports are no longer replay destinations; see the Reference docs for details (#375).
iOS device brand is now Apple in device_brand and
meta.device.brand, instead of iPhone or iPad. Filters and dashboards
that match the old values stop matching new data.
(#360).
iOS now reports meta.os.build_id, such as 24A437, as Android already
does. Simulators report the simulated iOS build.
(#360).
See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.17.0...v0.18.0
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Application-specific HTTP query values can be redacted alongside the built-in credential parameters. The same policy applies to spans, HTTP events and
Application-specific HTTP query values can be redacted alongside the built-in credential parameters. The same policy applies to spans, HTTP events and fallback network-error logs without changing requests. See the Reference docs for configuration and matching behavior (#346).
Known HTTP methods include http.request.method on spans and
faro.tracing.fetch events
(#109).
HTTP spans use stable attribute names, including url.full,
server.address, server.port, and http.response.status_code. Legacy
HTTP fields are removed from automatic spans. The faro.tracing.fetch
event retains its existing fields, with URL redaction as described below.
Update span consumers before adopting this private-preview schema.
See the Reference docs for details
(#346).
Known HTTP client span names are method-only, such as GET and
POST, instead of HTTP GET and HTTP POST. HTTP convenience methods use
uppercase verbs. When querying across an SDK upgrade, include both old
and new names. For example, a GET TraceQL filter can use
{ name = "GET" || name = "HTTP GET" || name = "HTTP get" }
(#109).
Automatic HTTP spans use the faro-mobile-flutter.http scope.
Queries that filter by instrumentation scope should include this scope
alongside faro-mobile-flutter when searching across SDK versions
(#109).
Use Dartastic OpenTelemetry stable 0.11.0, which preserves unset span
status when a span ends. This also includes upstream sampling fixes: child
spans respect an unsampled parent, and only sampled spans are exported.
get and GeT
produce GET. When the spelling differs from the canonical method, spans
and events record it in http.request.method_original
(#109).error.type. Faro HTTP events retain the legacy
http.status_code value of "0"
(#346).error.type, such as "404" or
"500", and omit the redundant status description. The HTTP event also
includes this attribute
(#24).See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.17.0-beta.3...v0.17.0
Direct crash-reporter setup is deprecated. Enable crash reporting and configure its transports through FaroConfig instead of calling Faro.enableCrashR…
Faro.resetSession() for logout, account changes, and custom session boundaries. It immediately starts and links a new session, restarts timing and sampling, emits session_start, and updates persisted session state (#315).X-Faro-Session-Status: invalid, following the Faro Web SDK response handling. Duplicate or delayed responses for an older session are ignored (#286).pushLog, pushEvent, pushError, and pushMeasurement while a span is active are now automatically stamped with the active span's trace_id/span_id. All four push methods accept an optional spanContext parameter (new FaroSpanContext(traceId:, spanId:) value type; use span.spanContext when you hold a Span) that always takes precedence over the active span.FaroWebViewBridge: instrumentedUrl accepts an optional span and propagates that span's traceparent instead of creating a span of its own, so repeated calls during one WebView session keep injecting the same traceparent. The bridge leaves a span you pass in untouched — no attributes, no status, and end() will not end it.FaroStartupProvider: A content provider merged into your Android manifest automatically. It samples process importance at startup so the SDK can tell a user-initiated launch from a background one; it stores no data and answers no queries. It can be removed with tools:node="remove", at the cost of cold start reporting on Android entirely.type: crash. The native signal and code remain available in context.nativeType. Dashboards and alerts matching signal names in exception.type should match crash and read context.nativeType instead (#269).pushEvent, pushLog, pushError, pushMeasurement, or unmarked spans to extend a session should wrap that work in startUserAction (#314).trace: Map<String, String>? parameter on pushLog and pushEvent is replaced by spanContext: FaroSpanContext?. pushError and pushMeasurement also gain the optional spanContext parameter (additive — they had no trace parameter before).FaroHttpOverrides from package:faro/faro.dart. The internal wrapper classes were previously exported unintentionally and are no longer part of the public API. Only FaroHttpOverrides is needed to enable HTTP tracking.Faro.init.app_startup measurements carry an additional prewarmed value (1 when iOS prewarmed the process, 0 otherwise).FaroConfig instead of calling Faro.enableCrashReporter.crashedSessionId and preserves the persisted sampling decision without changing the new live session (#151).session_start for every new session. Flutter no longer emits the Web-only session_extend event when rotation creates a new session (#316).dart_isolate_name=headless instead of main (#333).LOW_MEMORY exits for service and less important process states (#307).ApplicationExitInfo into the Faro exception context.See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.17.0-beta.2...v0.17.0-beta.3
Faro.resetSession() for logout, account changes, and custom session
boundaries. It immediately starts and links a new session, restarts timing
and sampling, emits session_start, and updates persisted session state
(#315).X-Faro-Session-Status: invalid, following the Faro Web SDK response
handling. Duplicate or delayed responses for an older session are ignored.
(#286)pushLog, pushEvent, pushError, and
pushMeasurement while a span is active are now automatically stamped
with the active span's trace_id/span_id, matching the Faro Web SDK
and the OpenTelemetry logs data model. All four push methods accept an
optional spanContext parameter (new FaroSpanContext(traceId:, spanId:)
value type; use span.spanContext when you hold a Span) that always
takes precedence over the active span. Span context is captured at push
time, so buffered signals keep the span that was active when they were
recorded.FaroWebViewBridge. instrumentedUrl accepts an
optional span and propagates that span's traceparent instead of
creating a span of its own, so repeated calls during one WebView session
keep injecting the same traceparent. The bridge leaves a span you pass
in untouched — no attributes, no status, and end() will not end it. See
the Reference docs for details.FaroStartupProvider, a content provider merged into your Android
manifest automatically. It samples process importance at startup so the SDK
can tell a user-initiated launch from a background one; it stores no data and
answers no queries. It can be removed with tools:node="remove", at the cost
of cold start reporting on Android entirely. See the Reference docs for
details.type: crash.
The native signal and code remain available in context.nativeType.
Dashboards and alerts matching signal names in exception.type should match
crash and read context.nativeType instead
(#269).pushEvent, pushLog, pushError,
pushMeasurement, or unmarked spans to extend a session should wrap that
work in startUserAction.
(#314)trace: Map<String, String>? parameter on pushLog and
pushEvent is replaced by spanContext: FaroSpanContext?. pushError and
pushMeasurement also gain the optional spanContext parameter (additive —
they had no trace parameter before). Migrate by wrapping ids in
FaroSpanContext(traceId:, spanId:), or use span.spanContext when you
hold a Span.FaroHttpOverrides from package:faro/faro.dart. The internal wrapper
classes (FaroHttpTrackingClient, FaroTrackingHttpClientRequest,
FaroTrackingHttpResponse) were previously exported unintentionally and
are no longer part of the public API. Only FaroHttpOverrides is needed
to enable HTTP tracking. This is a source-breaking change only for code
that imported those implementation-detail classes directly.Faro.init. An app that initialises Faro
after that frame is measured up to init instead, which is still shorter
than before.app_startup measurements carry an additional prewarmed value (1 when
iOS prewarmed the process, 0 otherwise). appStartDuration and coldStart
are unchanged, so existing dashboards keep working.FaroConfig instead of calling
Faro.enableCrashReporter.OfflineTransport because the native report is
already the durable retry copy
(#269).crashedSessionId and preserves the persisted
sampling decision without changing the new live session. Historical Android
exits are matched to their retained per-process sessions. When persistence
is active, crashes without a matching session are discarded instead of being
attributed to the new session
(#151).session_start for every new session.
Flutter no longer emits the Web-only session_extend event when rotation
creates a new session. Expect session_extend volume to drop to zero on
Flutter and session_start volume to increase by the same number of rotation
events. Dashboards and alerts matching session_extend should match
session_start and read meta.session.attributes.previousSession to
identify linked sessions
(#316).dart_isolate_name=headless instead of main.
Activity-backed engines remain main; dashboards filtering only for
dart_isolate_name=main no longer include Android background engines.
Pre-warmed UI engines can opt into FaroEngineRole.foreground, and
session-persistence ownership is unchanged
(#333).LOW_MEMORY exits for service and less important process
states regardless of whether Android records status 0 or SIGKILL.
Foreground, foreground-service, visible, and perceptible exits remain
reportable (#307).view_changed events.
(#305)network_error log now carries the HTTP span's
trace_id/span_id instead of no trace context.ApplicationExitInfo into
the Faro exception context instead of always reporting No stacktrace.Session rotation (#52): Sessions now rotate automatically after 15 minutes of inactivity or 4 hours of total lifetime. This change aligns with the Far
session_extend event is emitted (the initial session emits session_start). The previous session ID is recorded in the previousSession attribute to allow backends to link sessions. Note that automatic vitals (CPU, memory, etc.) count as activity only while the app is in the foreground. A foregrounded but idle app remains in one session, while a backgrounded app's vitals cannot keep its session alive. Sampling is not re-evaluated on rotation. See the Reference docs for full details.DateTime, custom object, or non-finite double) are dropped with a type-only diagnostic rather than failing the cache write.OfflineTransport to confirm internet access now has a 5-second timeout (previously it could hang indefinitely on some platforms, stalling online/offline decisions) and catches all probe errors instead of only SocketException. Any probe failure is treated as offline: while offline, payloads are cached on disk and flushed once connectivity returns, whereas a send attempted while actually offline is dropped without retry. This means a false "offline" only costs disk usage, while a false "online" could risk permanent data loss. Overlapping probes from rapid connectivity changes are now ordered, ensuring that a stale probe result that completes after a newer probe cannot overwrite the newer online/offline state. The lookup function is also injectable for testing via the new required addressLookup parameter and optional lookupTimeout parameter on InternetConnectivityService.See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.17.0-beta.1...v0.17.0-beta.2
session_extend event is
emitted (the initial session emits session_start), and the previous
id is recorded in the previousSession attribute so backends can link
sessions. Automatic vitals (CPU, memory, etc.) count as activity only
while the app is in the foreground: a foregrounded but idle app (e.g.
a user reading a screen) stays in one session, while a backgrounded
app's vitals cannot keep its session alive. Sampling is not
re-evaluated on rotation. See the Reference docs for full details.DateTime, custom object, or non-finite double) are dropped with a
type-only diagnostic rather than failing the cache write.OfflineTransport to confirm internet access now has a
5-second timeout (previously it could hang indefinitely on some
platforms, stalling online/offline decisions) and catches all probe
errors instead of only SocketException. Any probe failure is still
treated as offline: while offline, payloads are cached on disk and
flushed once connectivity returns, whereas a send attempted while
actually offline is dropped without retry — so a false "offline" only
costs disk usage, while a false "online" would risk permanent data
loss. Overlapping probes from rapid connectivity changes are now also
ordered: a stale probe result that completes after a newer probe can no
longer overwrite the newer online/offline state. The lookup function is
also injectable for testing via the new required addressLookup
parameter and optional lookupTimeout parameter on
InternetConnectivityService.DeviceId is deprecated; use InstallationId instead. The deprecated alias is kept for backward compatibility.
InstallationId / InstallationIdProvider. The persisted device_id
storage key and legacy flat session.attributes['device_id'] payload key are
unchanged for migration compatibility.opentelemetry Dart package to dartastic_opentelemetry for tracing.
(#242)DeviceId is deprecated; use InstallationId instead. The deprecated alias
is kept for backward compatibility.meta.device, meta.os, meta.app.installationId, and
exception.fatal, while keeping legacy flat session attributes during
migration.
The duplicated flat device_* session attributes are kept for compatibility
and can be removed after collector and plugin query parity is confirmed.dart-lang/setup-dart reusable publish workflow so we can
download the canonical archive pub.dev serves and attest those bytes via
actions/attest-build-provenance. Consumers can verify with
gh attestation verify <tarball> --repo grafana/faro-flutter-sdk.function field.
(#102)CrashReportingIntegration
unconditionally replaced non-empty stack traces with an empty array
before export. The dead sanitization has been removed so frames flow
through to the exported crash payload. Load/parse failures of pending
crash reports are now logged with a clearer message before the report
is purged. (#220)See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.16.0...v0.17.0-beta.1
Span exception handling control: Introduced SpanExceptionOptions for managing how exceptions are recorded on spans. This can be configured globally th
Span exception handling control: Introduced SpanExceptionOptions for managing how exceptions are recorded on spans. This can be configured globally through FaroConfig.spanExceptionOptions or on a per-span basis using the exceptionOptions parameter of startSpan(). The new options include:
ExceptionSanitizer callback for PII-safe error recording.recordException, setStatusOnException) for selective control.Per-span options are merged field-by-field with the global configuration, meaning omitted fields will inherit from the global settings. If the sanitizer callback throws an error, the span will be marked as failed with a generic status description to prevent PII leakage.
See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.15.0...v0.16.0
SpanExceptionOptions for
controlling how exceptions are recorded on spans. Configurable globally
via FaroConfig.spanExceptionOptions or per-span via the
exceptionOptions parameter of startSpan(). Includes
ExceptionSanitizer callback for PII-safe error recording and boolean
flags (recordException, setStatusOnException) for selective control.
Per-span options are merged field-by-field over the global config —
omitted fields inherit from global configuration. If the sanitizer
callback throws, the span is marked as failed with a generic status
description to avoid leaking PII.Breaking for consumers on Flutter < 3.29 / Dart < 3.7: Raised the declared Dart SDK lower bound to >=3.7.0 and Flutter lower bound to >=3.29.0 to matc
>=3.7.0 and Flutter lower bound to >=3.29.0 to match the effective device_info_plus dependency floor.device_info_plus dependency to >=12.3.0 <14.0.0 (adds v13.x support).package_info_plus dependency to >=8.0.1 <11.0.0 (adds v10.x support).See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.14.0...v0.15.0
Fix OOM crash in ANRTracker when capturing stack traces on low-memory Android devices (#174).
ANRTracker when capturing stack traces on low-memory Android devices (#174).'faro-flutter-sdk' to 'faro-mobile-flutter' to match naming convention discussed with Faro team.'1.3.5' workaround and now sends actual SDK version in meta.sdk.version.integrations field from SDK metadata (following Faro Web SDK pattern).Integration model class and its export from models barrel file.compileSdkVersion from 35 to 36 (aligned with Flutter default since May 2025).ios/Classes/ to ios/faro/Sources/faro/ to support the SPM directory convention.faro.podspec metadata (homepage, author, license type, summary/description).See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.13.0...v0.14.0
ANRTracker when capturing stack traces on low-memory Android devices (#174).'faro-flutter-sdk' to 'faro-mobile-flutter' to match naming convention discussed with Faro team'1.3.5' workaround and now sends actual SDK version in meta.sdk.versionintegrations field from SDK metadata (following Faro Web SDK pattern - this field provided no actionable insights)Integration model class and its export from models barrel filecompileSdkVersion from 35 to 36 (aligned with Flutter default since May 2025).ios/Classes/ to ios/faro/Sources/faro/ to support the SPM directory convention.faro.podspec metadata (homepage, author, license type, summary/description).FaroWebViewBridge — a public API for cross-boundary session and trace correlation between Flutter apps and web apps running in a WebView. It provides:
FaroWebViewBridge — a public API for cross-boundary session and trace correlation between Flutter apps and web apps running in a WebView. It provides:
instrumentedUrl() to decorate URLs with traceparent and session.parent_* query parameters.linkChildSession() to push a session.linked event correlating the web session.end() to close the WebView span.Span.traceparent getter — exposes the W3C Trace Context traceparent header value (00-{traceId}-{spanId}-01) directly on the Span interface, removing the need to cast to InternalSpan.
connectivity_plus dependency to >=6.1.2 <8.0.0 (adds v7.x support).package_info_plus dependency to >=8.0.1 <10.0.0 (adds v9.x support).Faro.init() now ignores repeated calls after the first successful initialization, preventing duplicate startup side effects such as extra transports, repeated session_start events, and duplicate widget observers.HttpClientRequest.done, or abort().See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.12.0...v0.13.0
markEventStart() and markEventEnd() are now deprecated. Use startSpan() for duration tracking. Use startUserAction() when you need interaction-level c…
markEventStart() and markEventEnd() are now deprecated. Use startSpan() for duration tracking. Use startUserAction() when you need interaction-level correlation across logs, events, exceptions, and spans. Use startSpanManual() for manual span lifecycle control.enableUiActivityMonitoring: false in FaroConfig.FaroAssetTracking now emit activity signals to keep user actions alive during resource loading.FaroAssetBundle now also tracks loadBuffer and loadStructuredBinaryData in addition to load and loadString.BREAKING: FaroAssetTracking replaces FaroAssetBundle in public API: FaroAssetBundle is no longer exported from package:faro/faro.dart. Use FaroAssetTracking(child: ...) instead of DefaultAssetBundle(bundle: FaroAssetBundle(), child: ...).
| Before | After |
|---|---|
| ```dart | ```dart |
| DefaultAssetBundle( | FaroAssetTracking( |
| bundle: FaroAssetBundle(), | child: const FaroUserInteractionWidget(child: MyApp()), |
| child: const FaroUserInteractionWidget(child: MyApp()), | ) |
| ) | ``` |
| ``` |
HTTP tracking no longer emits the legacy http_request custom event from HttpTrackingClient.
HTTP request telemetry continues to be available through span-derived faro.tracing.fetch events and OTLP spans.
Pending operation lifecycle signals are now span-driven via UserActionConstants.pendingOperationKey:
true.See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.11.0...v0.12.0
User Actions: Group related telemetry (logs, events, exceptions, traces) under a single action context to track end-to-end user interactions. (Resolve
User Actions: Group related telemetry (logs, events, exceptions, traces) under a single action context to track end-to-end user interactions. (Resolves #131)
Faro().startUserAction('name') starts a new action that buffers and enriches telemetry with action context.Faro().getActiveUserAction() returns the currently active action handle.action.name and action.id for correlation in Grafana.null.faro.action.user.name and faro.action.user.parentId attributes via FaroUserActionSpanProcessor.HTTP Tracking Filter: New HttpTrackingFilter for controlling which URLs are instrumented.
ignoreUrls patterns from FaroConfig to skip custom URL patterns.New dependency: Added dartypod (^0.2.0) for lightweight dependency injection.
Getting Started.md, Features.md, and Configurations.md with a single comprehensive Reference.md.See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.10.0...v0.11.0
Session sampling support: New sampling configuration option allows controlling what percentage of sessions send telemetry data. This enables cost mana
Session sampling support: New sampling configuration option allows controlling what percentage of sessions send telemetry data. This enables cost management and traffic reduction for high-volume applications. (Resolves #89)
SamplingRate(0.5) for fixed 50% samplingSamplingFunction((context) => ...) for dynamic sampling based on session context (user attributes, app environment, etc.)sampling: SamplingFunction((context) => context.meta.user?.attributes?['role'] == 'beta' ? 1.0 : 0.1)ContextScope for span context lifetime control: New contextScope parameter on startSpan() controls how long a span remains active in zone context for auto-assignment. ContextScope.callback (default) deactivates the span when the callback completes, preventing timer/stream callbacks from inheriting it. ContextScope.zone keeps the span active for the entire zone lifetime, useful when you want timer callbacks to be children of the parent span. (Resolves #105)
Span.noParent sentinel: New Span.noParent static constant allows explicitly starting a span with no parent, ignoring the active span in zone context. Useful for timer callbacks or event-driven scenarios where you want to start a fresh, independent trace. (Resolves #105)
http.status_code, http.request_size, http.response_size) are now sent as integers instead of strings, enabling proper numeric queries in Tempo (e.g., status_code > 400).sessionAttributes config now accepts Map<String, Object> allowing typed custom attributes. The device_is_physical attribute is now sent as a boolean instead of a string. (Resolves #133)See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.9.0...v0.10.0
OTLP Trace Attributes Now Preserve Types
Span attributes and event attributes now correctly preserve their original types (int, double, bool, String) when sent via OTLP.
Before: All attribute values were converted to strings, making numeric querying impossible.
user.account_count: "42" ❌ String - can't query account_count > 10
After: Attributes keep their native types, enabling proper queries and histogram bucketing in Grafana/Tempo.
user.account_count: 42 ✅ Integer - full numeric query support
| Method | Before | After |
|---|---|---|
Span.setAttribute() |
String value only |
Object value (String, int, double, bool) |
Span.setAttributes() |
Map<String, String> |
Map<String, Object> |
Span.addEvent() |
Map<String, String> attributes |
Map<String, Object> attributes |
Note: Existing code using string-only methods continues to work unchanged.
See CHANGELOG.md for complete details.
Full Changelog: v0.8.0...v0.9.0
user.account_count: 42 are sent as integers, enabling queries like account_count > 10 and proper histogram bucketingTraceAttributeValue to support stringValue, intValue, doubleValue, and boolValue fields per OTLP specificationSpan.setAttributes() and Span.addEvent() to accept Map<String, Object> for typed valuesSpan.setAttribute(String key, Object value) to accept any supported type (previously only String)Span.setAttribute(String key, String value) still works for string-only use casessetUserMeta() is now deprecated. Update your code:
This release introduces comprehensive user identity management with persistence, replacing the legacy setUserMeta() API.
FaroUser ModelA feature-rich user model that aligns with the Faro Web SDK MetaUser for cross-platform consistency.
Faro().setUser(FaroUser(
id: 'user-123',
username: 'johndoe',
email: 'john@example.com',
attributes: {'plan': 'premium', 'team': 'mobile'},
));
User identity is now automatically persisted across app restarts (enabled by default).
| Config Option | Default | Description |
|---|---|---|
persistUser |
true |
Save user to device storage |
initialUser |
null |
Set user on SDK initialization |
FaroConfig(
// ... other config
persistUser: true, // User survives app restarts
initialUser: FaroUser(id: 'known-user'), // Set immediately at startup
)
setUserMeta()setUserMeta() is now deprecated. Update your code:
// Before
Faro().setUserMeta(userId: 'x', userName: 'y', userEmail: 'z');
// After
Faro().setUser(FaroUser(id: 'x', username: 'y', email: 'z'));
Breaking behavior change:
setUserMeta()now requires SDK initialization before calling. Previously it could be called beforeinit()orrunApp().
See CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.7.0...v0.8.0
User management with FaroUser model: New FaroUser class for comprehensive user identification
User model with a more feature-rich implementationid, username, email, and custom attributes fieldsFaroUser.cleared() constructor to explicitly clear user dataUser persistence: New persistUser option in FaroConfig (default: true)
appStart include user data when persistence is enableduser_set event on restore and user_updated event on changesInitial user configuration: New initialUser option in FaroConfig
FaroUser.cleared() to explicitly clear any persisted user on startNew setUser() API: Streamlined method for setting user identity
Faro().setUser(FaroUser(...)) to set userFaro().setUser(FaroUser.cleared()) to clear userFuture<void> for awaiting persistence completionsetUser(FaroUser(...)) instead
setUserMeta(userId: 'x', userName: 'y', userEmail: 'z') with setUser(FaroUser(id: 'x', username: 'y', email: 'z'))init() or runApp()) before calling. Previously, setUserMeta() could be called before initialization. Calls made before initialization will now be silently ignored.This release updates Android build requirements due to the device_info_plus v12 upgrade. Your Android project now requires:
This release updates Android build requirements due to the device_info_plus v12 upgrade. Your Android project now requires:
| Requirement | Minimum Version |
|---|---|
| Android Gradle Plugin | ≥8.7.0 |
| Gradle wrapper | ≥8.10 |
| Kotlin | ≥2.2.0 |
| Java | 17 |
Added new deviceModelName field to DeviceInfo and device_model_name session attribute for human-readable device names.
| Platform | device_model |
device_model_name |
|---|---|---|
| iOS | iPhone16,1 |
iPhone 15 Pro ✨ |
| Android | SM-A155F |
SM-A155F |
Note: Android does not provide a mapping from model codes to marketing names, so
device_model_nameequalsdevice_modelon Android.
device_info_plus to v12.3.0modelName property on iOSSee CHANGELOG.md for complete details.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.6.0...v0.7.0
⚠️ Note: This release updates Android build requirements.
Due to the
device_info_plusv12 upgrade, your Android project now requires:
- Android Gradle Plugin ≥8.7.0
- Gradle wrapper ≥8.10
- Kotlin ≥2.2.0
- Java 17
deviceModelName field to DeviceInfo and device_model_name session attribute
deviceModel - Android does not provide a mapping from model codes to marketing namesdevice_info_plus from v11.4.0 to v12.3.0
modelName property on iOS for human-readable device namesfeat: allow disabling of reporting Flutter errors by @devmil in https://github.com/grafana/faro-flutter-sdk/pull/101
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.5.0...v0.6.0
enableFlutterErrorReporting in FaroConfig to control Flutter error reporting (default = true)Add custom labels to all your telemetry data with the new optional sessionAttributes parameter in FaroConfig.
Add custom labels to all your telemetry data with the new optional sessionAttributes parameter in FaroConfig.
Use cases:
Example:
await Faro().runApp(
optionsConfiguration: FaroConfig(
appName: "MyApp",
// ... other config
sessionAttributes: {
'team': 'mobile-platform',
'department': 'engineering',
'region': 'us-west',
},
),
appRunner: () => runApp(MyApp()),
);
Custom attributes are automatically included in all telemetry types (logs, events, exceptions, traces, measurements) and merged with default SDK attributes.
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.4.2...v0.5.0
sessionAttributes parameter in FaroConfig for adding custom labels to all telemetry
sessionTracking.session.attributes in Faro Web SDKrefactor(deps): remove intl dependency and use built-in DateTime.toIso8601String() by @robert-northmind in https://github.com/grafana/faro-flutter-sdk
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.4.1...v0.4.2
DateTime.toIso8601String() method
intl package dependency to reduce package footprintDateTime.toIso8601String() methodSDK Consistency & Span Status Management
SDK Consistency & Span Status Management
FaroConstants.sdkName instead of hardcoded valuesstatusHasBeenSet property in Span interfaceFull Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.4.0...v0.4.1
SDK name consistency across telemetry types: Updated SDK identification to use consistent naming
FaroConstants.sdkName for consistency with OpenTelemetry tracesFaroZoneSpanManager span status preservation: Fixed issue where manually set span statuses were overridden by automatic status setting
statusHasBeenSet property to Span interface to track when status has been manually setFaroZoneSpanManager.executeWithSpan() to respect manually set span statuses for both success and error casesv0.4.0 - Package Structure & API Improvements
v0.4.0 - Package Structure & API Improvements
faro_sdk.dart to faro.dartpushEvent(), pushLog(), etc.LogLevel enum - pushLog() now requires LogLevel parameter instead of stringstartSpan<T>(), startSpanManual(), and getActiveSpan() methodsSessionIdProvider// Update imports
import 'package:faro/faro.dart'; // was: faro_sdk.dart
// Remove await from telemetry methods
Faro().pushEvent('event_name'); // was: await Faro().pushEvent(...)
// Use LogLevel enum
Faro().pushLog('message', level: LogLevel.info); // was: level: 'info'
Breaking Change: Main entry point changed from faro_sdk.dart to faro.dart
lib/<package_name>.dart conventionlib/faro_sdk.dart file entirelylib/faro.dart is now the single main entry point with selective barrel exportsMigration: Update your imports to use the new main entry point
// Before
import 'package:faro/faro_sdk.dart';
// After
import 'package:faro/faro.dart';
Architecture Improvements:
Faro class implementation from lib/faro.dart to lib/src/faro.dartlib/faro.dart now serves as a clean barrel export file exposing only public APIslib/src/ directoryBenefits:
No functionality changes: All existing public APIs remain the same, only import paths have changed
Type-Safe Log Level API: New LogLevel enum for improved logging reliability and developer experience
LogLevel enum with values: trace, debug, info, log, warn, errorfromString() method for backward compatibility, supporting both 'warn' and 'warning' variantsEnhanced Tracing and Span API: Major improvements to distributed tracing capabilities
startSpan<T>() method for automatic span lifecycle management with callback-based executionstartSpanManual() method for manual span lifecycle management when precise control is neededgetActiveSpan() method to access the currently active span from anywhere in the execution contextsession_id and session.id attributesCentralized Session Management: New SessionIdProvider for consistent session handling across the SDK
SDK Constants Management: New centralized constants system
FaroConstants class for SDK version and name managementBREAKING: Synchronous API for telemetry methods: Refactored telemetry methods to remove unnecessary async patterns for improved performance and developer experience
Breaking Change: The following methods changed from Future<void>? to void:
pushEvent() - Send custom eventspushLog() - Send custom logspushError() - Send custom errorspushMeasurement() - Send custom measurementsmarkEventEnd() - Mark event completionMigration: Remove await keywords from calls to these methods as they are now synchronous
// Before
await Faro().pushEvent('event_name');
await Faro().pushLog('message', level: LogLevel.info);
// After
Faro().pushEvent('event_name');
Faro().pushLog('message', level: LogLevel.info);
Benefits:
Internal Architecture: Introduced BatchTransportFactory singleton pattern for better dependency management and testing
BREAKING: pushLog API requires LogLevel enum: Enhanced logging API for better type safety and consistency
pushLog() now requires a LogLevel parameter instead of optional String?level: "warn" with level: LogLevel.warn in your pushLog callsTracing Architecture Refactoring: Complete redesign of the internal tracing system
tracer.dart and tracer_provider.dart with new FaroTracer implementationFaroZoneSpanManager for robust zone-based span context managementSpan class with cleaner API and better OpenTelemetry integrationSession Management: Extracted session logic from distributed components
generate_session.dart utilitydocs: add comprehensive cursor rules and project overview documentation by @robert-northmind in https://github.com/grafana/faro-flutter-sdk/pull/67
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.3.6...v0.3.7
http.request_size attribute with request content lengthhttp.response_size attribute with response content lengthhttp.content_type attribute with response content typeDartOtelTracerResourcesFactorytimestamp_readable_utc field alongside existing timestamp fieldTimestampExtension utility for reusable timestamp conversionduration_ns attribute with span duration in nanosecondsendTime - startTime when both timestamps are validfaro.tracing.fetch event namespan.{name} format for better event categorizationhttp.scheme or http.method attributeschore: add project governance and improve documentation by @robert-northmind in https://github.com/grafana/faro-flutter-sdk/pull/63
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.3.5...v0.3.6
enableDataCollection setting now persists across app restarts
stopFrameMonitoring() to remove Choreographer callbackshandleFrameDrop(), handleSlowFrameDrop(), and handleRefreshRate() methodsfeat: add header to config to send with each request by @mrgnhnt96 in https://github.com/grafana/faro-flutter-sdk/pull/59
Full Changelog: https://github.com/grafana/faro-flutter-sdk/compare/v0.3.4...v0.3.5
FaroConfig via the collectorHeaders field
Automated pub.dev deployment with GitHub Actions
Updated intl dependency to newer version to be compatible with latest flutter version
### Changed - Maintenance release
This release focuses on project structure improvements and build process optimization, making the SDK easier to maintain and contribute to. The core f
This release focuses on project structure improvements and build process optimization, making the SDK easier to maintain and contribute to. The core functionality remains unchanged, but the development workflow has been significantly streamlined.
packages/faro to root directory for improved maintainability and simpler package structurepackages/faro to root. Since we only have one package in this repo for nowOne column per month.