flutterrific_opentelemetry 0.3.2
flutterrific_opentelemetry: ^0.3.2 copied to clipboard
A Flutter package for OpenTelemetry based on dartastic_opentelemetry
Flutterrific OpenTelemetry SDK for Flutter #
Flutterrific OTel is an OpenTelemetry SDK for Flutter applications built on the Dartastic OpenTelemetry SDK, providing comprehensive observability for Flutter applications across all platforms.
Demo #
The Wondrous OpenTelemetry project instruments the Wondrous App for observability with Flutterrific OTel.
The main.dart
and router.dart
show how to set up your app with Flutterrific OpenTelemetry.
Overview #
This Flutter SDK implements the OpenTelemetry specification, enabling developers to collect distributed traces and metrics from Flutter applications (logs coming soon). OpenTelemetry is a vendor-neutral standard for observability and is the second most active Cloud Native Computing Foundation (CNCF) project, after Kubernetes.
Why OpenTelemetry for Flutter? #
- Report Errors: Get notified of errors in real time.
- Watch Your Users: Where do users spend their time? Increase conversion rates.
- Get Metrics: How fast do your routes load IRL?
- Future-Proof: OpenTelemetry is an industry standard with broad ecosystem support
- Vendor Neutral: Works with any OpenTelemetry-compatible backend
- Comprehensive: Covers traces, metrics, and logs in a unified approach
- Cross-Platform: Supports all Flutter platforms (Android, iOS, Web, Desktop)
- Performance: Designed for minimal overhead in production applications
Features #
- ๐ Simple Integration: Get started with just a few lines of code
- ๐ฃ Automatic Instrumentation: Navigation, app lifecycle, and user interaction tracking
- ๐ Performance Metrics: Web vitals, APDEX scores, and custom performance metrics
- ๐งฉ Widget Extensions: Easy-to-use extensions for widget-level observability
- ๐ Error Tracking: Comprehensive error handling and reporting
- ๐ Standards Compliant: Full adherence to OpenTelemetry specification
- ๐ Multi-Platform: Supports Android, iOS, Web, and Desktop platforms
- ๐ช Context Propagation: Seamless trace correlation across async boundaries
- ๐ง Configurable Sampling: Multiple sampling strategies for cost optimization
- ๐งท Type-Safe Semantics: Strongly-typed semantic conventions
Quick Start #
1. Add Dependency #
dependencies:
flutterrific_opentelemetry: ^0.3.0
2. Initialize OpenTelemetry #
import 'package:flutter/material.dart';
import 'package:flutterrific_opentelemetry/flutterrific_otel.dart';
void main() {
// Initialize error handling
FlutterError.onError = (FlutterErrorDetails details) {
FlutterOTel.reportError('FlutterError.onError', details.exception, details.stack);
};
runZonedGuarded(() {
// Initialize OpenTelemetry
FlutterOTel.initialize(
serviceName: 'my-flutter-app',
serviceVersion: '1.0.0',
tracerName: 'main',
// Configure your exporter endpoint
resourceAttributes: {
'deployment.environment': 'production',
'service.namespace': 'mobile-apps',
}
);
runApp(MyApp());
}, (error, stack) {
FlutterOTel.reportError('Zone Error', error, stack);
});
}
3. Automatic Instrumentation #
The SDK automatically instruments:
- Navigation: Track route changes and user flows
- App Lifecycle: Monitor foreground/background transitions
- Performance: Collect frame rates and rendering metrics
- Errors: Capture and report exceptions with context
Platform Support #
Platform | Support Level | Protocol | Notes |
---|---|---|---|
Android | Full | OTLP/gRPC | Complete feature support |
iOS | Full | OTLP/gRPC | Complete feature support |
Web | Full | OTLP/HTTP | Auto-switches due to browser limitations |
Windows | Beta | OTLP/gRPC | Desktop support |
macOS | Beta | OTLP/gRPC | Desktop support |
Linux | Beta | OTLP/gRPC | Desktop support |
Advanced Usage #
Custom Tracing #
void fetchUserData() async {
final tracer = FlutterOTel.tracer;
final span = tracer.startSpan('fetch_user_data', attributes: {
'user.id': userId,
'api.endpoint': '/users',
});
try {
final result = await apiClient.getUser(userId);
span.setStatus(SpanStatusCode.Ok);
return result;
} catch (e, stackTrace) {
span.recordException(e, stackTrace: stackTrace);
span.setStatus(SpanStatusCode.Error, e.toString());
rethrow;
} finally {
span.end();
}
}
Widget-Level Tracking #
// Track button interactions
ElevatedButton(
onPressed: handleSubmit,
child: Text('Submit'),
).withOTelButtonTracking('submit_form');
// Monitor widget performance
ComplexWidget().withOTelPerformanceTracking('complex_widget');
// Error boundaries
RiskyWidget().withOTelErrorBoundary('risky_operation');
Configuration #
Environment Variables #
Standard OpenTelemetry environment variables are supported:
# Exporter endpoint
--dart-define=OTEL_EXPORTER_OTLP_ENDPOINT=https://your-collector:4317
# Protocol selection (grpc or http/protobuf)
--dart-define=OTEL_EXPORTER_OTLP_PROTOCOL=grpc
# Service information
--dart-define=OTEL_SERVICE_NAME=my-flutter-app
--dart-define=OTEL_SERVICE_VERSION=1.0.0
Local Development #
For local development, run an OpenTelemetry collector on localhost:4317, the default.
docker run -p 4317:4317 -p 4318:4318 --rm -ti grafana/otel-lgtm
Documentation #
Examples #
- Basic Integration Example
- Wonderous OpenTelemetry - Complete app example
Contributing #
We welcome contributions! Please see our Contributing Guide for details.
Development Setup #
# Clone the repository
git clone https://github.com/MindfulSoftwareLLC/flutterrific_opentelemetry.git
cd flutterrific_opentelemetry
# Install dependencies
make install
# Run tests
make test
# Run all checks
make all
Governance #
This project follows the CNCF Code of Conduct and maintains open governance. We welcome community participation and contributions.
Security #
Security vulnerabilities should be reported privately to the maintainers. See our Security Policy for details.
Compatibility #
- Flutter: 3.7.0+
- Dart: 3.7.0+
- OpenTelemetry Specification: 1.31.0
- Platforms: Android, iOS, Web, Windows, macOS, Linux
Roadmap #
See our Roadmap for planned features and improvements.
License #
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Community #
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - Community discussions
- OpenTelemetry Community - Broader OpenTelemetry community
Acknowledgments #
Built on the foundation of:
Maintained by Michael Bushe and Mindful Software LLC.
This project aims to be contributed to the OpenTelemetry organization under the Cloud Native Computing Foundation.