setup-observer

This skill configures Superpowers.observer for performance tracking, analytics, and debugging of all mix() calls.

What This Skill Does

Sets up a global observer that:

• Tracks when operations start and complete
• Measures operation duration
• Captures errors and success states
• Sends data to analytics/monitoring services

Instructions

Step 1: Configure in main()

Set Superpowers.observer before runApp():

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

void main() {
  Superpowers.observer = (
    bool isStart,
    Object key,
    Object? metrics,
    Object? error,
    StackTrace? stackTrace,
    Duration? duration,
  ) {
    // Handle observation
  };

  runApp(
    Superpowers(
      child: MaterialApp(...),
    ),
  );
}

Step 2: Understand Parameters

| Parameter | When | Description | |-----------|------|-------------| | isStart | Always | true at start, false at end | | key | Always | The key from mix() call | | metrics | Always | Custom data from metrics callback | | error | End only | Exception if operation failed | | stackTrace | End only | Stack trace if operation failed | | duration | End only | How long the operation took |

Common Patterns

Basic Logging

Superpowers.observer = (isStart, key, metrics, error, stackTrace, duration) {
  if (isStart) {
    print('▶ Starting: $key');
  } else {
    if (error != null) {
      print('✗ Failed: $key after ${duration?.inMilliseconds}ms - $error');
    } else {
      print('✓ Completed: $key in ${duration?.inMilliseconds}ms');
    }
  }
};

Performance Monitoring

Superpowers.observer = (isStart, key, metrics, error, stackTrace, duration) {
  if (!isStart && duration != null) {
    // Log slow operations
    if (duration.inMilliseconds > 1000) {
      print('⚠ Slow operation: $key took ${duration.inMilliseconds}ms');
    }

    // Send to analytics
    analytics.logTiming(
      category: 'cubit_operation',
      name: key.toString(),
      duration: duration,
      success: error == null,
    );
  }
};

Analytics Integration

Superpowers.observer = (isStart, key, metrics, error, stackTrace, duration) {
  if (!isStart) {
    // Firebase Analytics
    FirebaseAnalytics.instance.logEvent(
      name: 'cubit_operation',
      parameters: {
        'key': key.toString(),
        'duration_ms': duration?.inMilliseconds,
        'success': error == null,
        'error_type': error?.runtimeType.toString(),
      },
    );

    // Or Amplitude
    Amplitude.instance.logEvent(
      'cubit_operation_completed',
      eventProperties: {
        'key': key.toString(),
        'duration_ms': duration?.inMilliseconds,
        'success': error == null,
      },
    );
  }
};

Error Monitoring

Superpowers.observer = (isStart, key, metrics, error, stackTrace, duration) {
  if (!isStart && error != null) {
    // Send to Sentry
    Sentry.captureException(
      error,
      stackTrace: stackTrace,
      hint: Hint.withMap({
        'key': key.toString(),
        'duration_ms': duration?.inMilliseconds.toString(),
      }),
    );

    // Or Crashlytics
    FirebaseCrashlytics.instance.recordError(
      error,
      stackTrace,
      reason: 'mix operation failed: $key',
    );
  }
};

Using Metrics

Pass custom data to the observer with the metrics parameter:

Pass Current State

void loadUser() => mix(
  key: this,
  metrics: () => state,  // Pass current state
  () async {
    final user = await api.getUser();
    emit(user);
  },
);

// In observer
Superpowers.observer = (isStart, key, metrics, error, stackTrace, duration) {
  if (metrics != null) {
    print('State at ${isStart ? "start" : "end"}: $metrics');
  }
};

Pass Cubit Instance

void loadData() => mix(
  key: this,
  metrics: () => this,  // Pass entire Cubit
  () async {
    final data = await api.getData();
    emit(data);
  },
);

// In observer - access Cubit state
Superpowers.observer = (isStart, key, metrics, error, stackTrace, duration) {
  if (metrics is MyCubit) {
    print('Cubit state: ${metrics.state}');
  }
};

Pass Custom Metrics

void processOrder(Order order) => mix(
  key: this,
  metrics: () => {
    'orderId': order.id,
    'itemCount': order.items.length,
    'total': order.total,
  },
  () async {
    await api.processOrder(order);
  },
);

// In observer
Superpowers.observer = (isStart, key, metrics, error, stackTrace, duration) {
  if (metrics is Map) {
    analytics.logEvent('order_processing', parameters: metrics);
  }
};

Behavior Notes

• Called twice: Once at start (isStart: true), once at end (isStart: false)
• Retry transparency: With retry, observer only sees the overall start/end, not individual attempts
• Error safety: If the metrics callback or observer throws, the error is captured safely
• Metrics called twice: The metrics callback runs at both start and end, so you can see state changes

Complete Example

void main() {
  _setupObserver();

  runApp(
    Superpowers(
      child: MyApp(),
    ),
  );
}

void _setupObserver() {
  Superpowers.observer = (
    bool isStart,
    Object key,
    Object? metrics,
    Object? error,
    StackTrace? stackTrace,
    Duration? duration,
  ) {
    final keyStr = _formatKey(key);

    if (isStart) {
      // Log operation start
      debugPrint('▶ [$keyStr] Starting');
    } else {
      // Log operation completion
      final durationMs = duration?.inMilliseconds ?? 0;

      if (error != null) {
        debugPrint('✗ [$keyStr] Failed after ${durationMs}ms: $error');

        // Report to crash analytics
        _reportError(key, error, stackTrace, duration);
      } else {
        debugPrint('✓ [$keyStr] Completed in ${durationMs}ms');

        // Report slow operations
        if (durationMs > 2000) {
          _reportSlowOperation(key, duration!);
        }
      }

      // Send analytics
      _sendAnalytics(key, duration, error == null);
    }
  };
}

String _formatKey(Object key) {
  if (key is Type) return key.toString();
  if (key is Record) return key.toString();
  return key.runtimeType.toString();
}

void _reportError(Object key, Object error, StackTrace? stack, Duration? duration) {
  FirebaseCrashlytics.instance.recordError(
    error,
    stack,
    reason: 'Operation failed: $key',
    information: ['Duration: ${duration?.inMilliseconds}ms'],
  );
}

void _reportSlowOperation(Object key, Duration duration) {
  FirebaseAnalytics.instance.logEvent(
    name: 'slow_operation',
    parameters: {
      'key': key.toString(),
      'duration_ms': duration.inMilliseconds,
    },
  );
}

void _sendAnalytics(Object key, Duration? duration, bool success) {
  FirebaseAnalytics.instance.logEvent(
    name: 'cubit_operation',
    parameters: {
      'key': key.toString(),
      'duration_ms': duration?.inMilliseconds,
      'success': success,
    },
  );
}

Testing

Reset the observer between tests:

setUp(() {
  Superpowers.clear();  // Removes observer and resets state
});

User Preferences

Ask the user:

1. What should be logged? (start, completion, errors, slow operations)
2. Where to send analytics? (Firebase, Amplitude, custom backend)
3. Need custom metrics? (state, order details, etc.)