Telling Logger 📊 #

A production-ready crash reporting, error tracking, and analytics SDK for Flutter applications. Monitor your app's health, track user behavior, and gain actionable insights with minimal setup.

✨ Features #

Core Capabilities #

• 🐛 Automatic Crash Reporting – Captures unhandled Flutter framework and platform errors
• 📊 Event Analytics – Track custom events, user actions, and business metrics
• 📱 Rich Device Context – Auto-collects platform, OS version, device model, and app info
• 🔄 Session Management – Automatic session tracking with app lifecycle hooks
• 📍 Screen Tracking – Built-in NavigatorObserver for automatic screen view analytics
• 👤 User Context – Associate logs with user IDs, names, and emails
• 🎯 Widget-Level Tracking – .nowTelling() extension for effortless view tracking
• ⚡ Smart Batching – Efficient log deduplication and batching to minimize network overhead
• � Offline Support – Persists logs when offline, auto-sends when connection is restored
• 🛡️ Rate Limiting – Built-in deduplication, throttling, and flood protection
• 🌍 Cross-Platform – Works on iOS, Android, Web, macOS, Windows, and Linux

Developer Experience #

• 🚀 5-Minute Setup – Initialize with a single line of code
• 📝 Production-Safe Logging – Debug logs automatically stripped from release builds
• 🔌 Backend Agnostic – Use our backend or build your own
• 🎨 Flexible API – Multiple log levels, types, and metadata support
• 📖 Type-Safe – Fully typed with comprehensive IntelliSense

📦 Installation #

Add telling_logger to your pubspec.yaml:

dependencies:
  telling_logger: ^1.0.0

Then install:

flutter pub get

🚀 Quick Start #

1. Initialize the SDK #

In your main.dart, initialize Telling before running your app:

import 'package:flutter/material.dart';
import 'package:telling_logger/telling_logger.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize Telling SDK
  await Telling.instance.init(
    'YOUR_API_KEY',
  );
  
  // Enable automatic crash reporting
  Telling.instance.enableCrashReporting();
  
  runApp(MyApp());
}

2. Log Events #

// Simple info log
Telling.instance.log('User completed onboarding');

// Log with metadata
Telling.instance.log(
  'Payment processed',
  level: LogLevel.info,
  metadata: {
    'amount': 29.99,
    'currency': 'USD',
    'payment_method': 'stripe',
  },
);

// Error logging
try {
  await processPayment();
} catch (e, stack) {
  Telling.instance.log(
    'Payment failed',
    level: LogLevel.error,
    error: e,
    stackTrace: stack,
  );
}

3. Track Analytics #

// Track custom events
Telling.instance.event(
  'button_clicked',
  properties: {
    'button_name': 'Sign Up',
    'screen': 'Landing Page',
    'user_segment': 'free_trial',
  },
);

📚 Core Concepts #

Log Levels #

Control the severity and visibility of your logs:

Log Types #

Categorize logs for better filtering and analytics:

🎯 Advanced Features #

User Context Tracking #

Associate logs with specific users for better debugging and analytics:

// Set user context after login
Telling.instance.setUser(
  userId: 'user_12345',
  userName: 'Jane Doe',
  userEmail: '[email protected]',
);

// Clear user context after logout
Telling.instance.clearUser();

All subsequent logs will automatically include user information until cleared.

Automatic Screen Tracking #

With MaterialApp

MaterialApp(
  navigatorObservers: [
    Telling.instance.screenTracker,
  ],
  home: HomeScreen(),
)

With go_router

final router = GoRouter(
  observers: [
    Telling.instance.goRouterScreenTracker,
  ],
  routes: [...],
);

MaterialApp.router(
  routerConfig: router,
)

Screen views are automatically logged with:

• Screen name
• Previous screen
• Time spent on previous screen
• Session context

Widget-Level Tracking #

Use the .nowTelling() extension to track any widget's visibility:

import 'package:telling_logger/telling_logger.dart';

// Basic usage - tracks when widget appears
Column(
  children: [
    Text('Welcome!'),
  ],
).nowTelling()

// With custom name
ProductCard(product: item).nowTelling(
  name: 'Product Card Impression',
)

// With metadata for context
PremiumFeature().nowTelling(
  name: 'Premium Feature Shown',
  metadata: {
    'feature_id': 'dark_mode',
    'user_tier': 'free',
  },
)

// Track every appearance (not just once)
AdBanner().nowTelling(
  name: 'Banner Ad Impression',
  trackOnce: false,
  metadata: {'ad_id': 'banner_123'},
)

// Custom log type and level
CriticalAlert().nowTelling(
  name: 'Security Alert Displayed',
  type: LogType.security,
  level: LogLevel.warning,
)

Parameters:

• name – Custom name (defaults to widget's runtimeType)
• type – Log type (defaults to LogType.analytics)
• level – Log level (defaults to LogLevel.info)
• metadata – Additional context data
• trackOnce – Track only first appearance (defaults to true)

Built-in Rate Limiting #

Telling includes intelligent rate limiting to prevent log flooding and protect your backend:

Automatically configured with optimal values:

• Deduplication Window: 5 seconds – Identical logs (same message, level, stackTrace) are merged
• Crash Throttle: 5 seconds – Only one crash with the same stackTrace per window
• General Throttle: 1 second – Prevents rapid-fire duplicate logs
• Rate Limit: 10 logs/second maximum

How it protects you:

• Deduplication: Prevents accidental log spam from loops or rapid state changes
• Crash Throttling: Stops crash storms from overwhelming your backend
• Rate Limiting: Ensures your app doesn't exceed reasonable logging volume
• Smart Throttling: Different limits for crashes vs general logs

No configuration needed – works out of the box! 🎯

Session Management #

Sessions are automatically managed based on app lifecycle:

• Session Start: When app launches or returns from background
• Session End: When app goes to background or terminates
• Session Data: Duration, user context, device info

// Session data is automatically included in all logs
{
  "sessionId": "user_123_1700745600000",
  "userId": "user_123",
  "userName": "Jane Doe",
  "userEmail": "[email protected]"
}

Crash Reporting #

Enable automatic crash capture for both Flutter and platform errors:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Telling.instance.init('YOUR_API_KEY');
  
  // Captures:
  // - Flutter framework errors (FlutterError.onError)
  // - Platform dispatcher errors (PlatformDispatcher.onError)
  // - Render issues (marked as warnings)
  Telling.instance.enableCrashReporting();
  
  runApp(MyApp());
}

Crash Intelligence:

• Render/layout issues are logged as warnings
• Actual crashes are logged as fatal errors
• Full stack traces included
• Automatic retry with exponential backoff

🔧 Configuration Options #

Initialization Parameters #

await Telling.instance.init(
  String apiKey,                      // Required: Your API key
  {
    String? userId,                   // Initial user ID
    String? userName,                 // Initial user name
    String? userEmail,                // Initial user email
  }
);

Environment-Specific Setup #

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  const isProduction = bool.fromEnvironment('dart.vm.product');
  
  await Telling.instance.init(
    isProduction ? 'PROD_API_KEY' : 'DEV_API_KEY',
  );
  
  runApp(MyApp());
}

🌐 Backend Integration #

Using the Official Backend #

Deploy the open-source Telling backend with one click:

# Clone the backend
git clone https://github.com/ThatSaxyDev/telling.git
cd telling

# Deploy (supports Dart Frog, Globe.dev, etc.)
dart pub get
dart run bin/server.dart

Custom Backend #

Build your own backend that accepts logs via POST /api/v1/logs:

Request Headers:

Content-Type: application/json
x-api-key: YOUR_API_KEY

Request Body:

[
  {
    "id": "1700745600000",
    "type": "analytics",
    "level": "info",
    "message": "User logged in",
    "timestamp": "2024-11-23T10:30:00.000Z",
    "stackTrace": null,
    "metadata": {
      "screen": "Login",
      "method": "email"
    },
    "device": {
      "platform": "iOS",
      "osVersion": "17.0",
      "deviceModel": "iPhone 15 Pro",
      "appVersion": "1.2.0",
      "appBuildNumber": "42"
    },
    "userId": "user_123",
    "userName": "Jane Doe",
    "userEmail": "[email protected]",
    "sessionId": "user_123_1700745600000"
  }
]

Response:

• 200 OK – Logs accepted
• 403 Forbidden – Invalid API key
• 4xx/5xx – Retry with exponential backoff

📱 Platform Support #

⚡ Performance #

Production Optimizations #

• Zero Debug Overhead: Debug logs are tree-shaken from release builds
• Asynchronous: All network operations run in background
• Batched Sending: Logs are batched every 5 seconds
• Smart Deduplication: Prevents duplicate logs from consuming bandwidth
• Memory Efficient: Bounded buffer with automatic cleanup
• Offline Resilient: Persists unsent logs to disk

Benchmarks #

• Initialization: ~50ms (includes device metadata collection)
• Log call overhead: <1ms (async, non-blocking)
• Memory footprint: ~2MB (including buffer)
• Battery impact: Negligible (<0.1% on mobile)

🎓 Best Practices #

1. Initialize Early #

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize BEFORE runApp
  await Telling.instance.init('API_KEY');
  Telling.instance.enableCrashReporting();
  
  runApp(MyApp());
}

2. Use Appropriate Log Levels #

// ✅ Good
Telling.instance.log('User login successful', level: LogLevel.info);
Telling.instance.log('Database query slow', level: LogLevel.warning);
Telling.instance.log('Payment failed', level: LogLevel.error);

// ❌ Avoid
Telling.instance.log('Button clicked', level: LogLevel.fatal); // Wrong severity

3. Add Context with Metadata #

// ✅ Good - rich context
Telling.instance.event('purchase_completed', properties: {
  'product_id': 'premium_monthly',
  'price': 9.99,
  'currency': 'USD',
  'payment_method': 'stripe',
  'user_segment': 'trial_converted',
});

// ❌ Poor - no context
Telling.instance.event('purchase');

4. Track User Context #

// Set user context after authentication
await signIn(email, password);
Telling.instance.setUser(
  userId: user.id,
  userName: user.name,
  userEmail: user.email,
);

// Clear on logout
await signOut();
Telling.instance.clearUser();

5. Use Widget Tracking Wisely #

// ✅ Good - track important screens/components
HomeScreen().nowTelling(name: 'Home Screen');
PremiumPaywall().nowTelling(name: 'Paywall Viewed');

// ❌ Avoid - don't track every tiny widget
Text('Hello').nowTelling(); // Too granular
Container().nowTelling();   // Not meaningful

6. Handle Sensitive Data #

// ❌ Don't log PII or sensitive data
Telling.instance.event('login', properties: {
  'password': '123456', // NEVER
  'credit_card': '4111...', // NEVER
});

// ✅ Hash or omit sensitive fields
Telling.instance.event('login', properties: {
  'email_hash': hashEmail(user.email),
  'login_method': 'email',
});

🧪 Testing #

Unit Testing #

Mock Telling in your tests:

// test/mocks.dart
import 'package:mocktail/mocktail.dart';
import 'package:telling_logger/telling_logger.dart';

class MockTelling extends Mock implements Telling {}

// test/my_test.dart
void main() {
  late MockTelling mockTelling;
  
  setUp(() {
    mockTelling = MockTelling();
  });
  
  test('logs event on button press', () async {
    when(() => mockTelling.event(any(), properties: any(named: 'properties')))
        .thenAnswer((_) async {});
    
    // Test your code
    
    verify(() => mockTelling.event('button_clicked', properties: any(named: 'properties')));
  });
}

Integration Testing #

void main() {
  testWidgets('tracks screen view', (tester) async {
    await Telling.instance.init('TEST_API_KEY');
    
    await tester.pumpWidget(MyApp());
    await tester.pumpAndSettle();
    
    // Verify screen tracking occurred
    // (check your test backend)
  });
}

🔍 Troubleshooting #

Logs Not Appearing #

1. Check API Key: Ensure your API key is valid
2. Check Network: Verify backend URL is reachable
3. Check Initialization: Confirm Telling.instance.init() was called
4. Check Rate Limiting: You may be hitting rate limits

// Enable debug mode to see what's happening
if (kDebugMode) {
  // Telling automatically prints debug info in debug mode
  // Check console for messages starting with "Telling:"
}

Common Errors #

"Telling SDK not initialized"

• Call await Telling.instance.init() before using the SDK

"Invalid API Key" (403)

• Verify your API key is correct
• Check backend is running and accessible

"Logs being dropped"

• Check rate limiting configuration
• Reduce log volume or increase limits

🤝 Contributing #

We welcome contributions! Please see our Contributing Guide.

Development Setup #

git clone https://github.com/ThatSaxyDev/telling-logger.git
cd telling-logger
flutter pub get
flutter test

📄 License #

MIT License - see the LICENSE file for details.

🙋 Support #

• � Documentation
• 🐛 Report Issues
• � Discussions
• 📧 Email: [email protected]

🌟 Show Your Support #

If Telling Logger helped you build better apps, please:

• ⭐ Star this repo
• 🐦 Share on Twitter
• 📝 Write a blog post
• 💬 Tell your friends

Made with ❤️ by the Telling team

Website • Twitter • GitHub