blocpod_arch_logger

Bridge adapter between blocpod_arch event records and blocpod_logger sinks.

This package owns:

• BlocpodEventLogFormatter
• EventLogRecordFormatter
• PrettyEventLogRecordFormatter
• eventLogPhaseLabel
• BlocpodEventLogger

blocpod_arch_logger is the only package in this workspace that should depend on both blocpod_arch and blocpod_logger.

Usage

Install the bridge by overriding eventLoggerProvider at the application boundary:

import 'package:blocpod_arch/blocpod_arch.dart';
import 'package:blocpod_arch_logger/blocpod_arch_logger.dart';
import 'package:blocpod_logger/blocpod_logger.dart';
import 'package:flutter/widgets.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';

ProviderScope(
  overrides: [
    eventLoggerProvider.overrideWithValue(
      BlocpodEventLogger(DebugPrintLogSink()),
    ),
  ],
  child: const Placeholder(),
);

BlocpodEventLogger converts EventLogRecord values into BlocpodLogEntry values and isolates sink failures from application flow. The formatter includes the observer phase, trace/span ids, event name, transition index, state kinds, optional sanitized state labels/metadata, duration, errors, and stack traces.

Formatter Styles

The default EventLogRecordFormatter is compact and structured. It is best for log sinks that index metadata:

eventLoggerProvider.overrideWithValue(
  BlocpodEventLogger(DebugPrintLogSink()),
);

Compact output uses log-friendly phase labels such as state.established, event.started, state.transition, and event.completed. Use eventLogPhaseLabel when custom formatters need the same phase labels.

For local debugging, use PrettyEventLogRecordFormatter:

eventLoggerProvider.overrideWithValue(
  BlocpodEventLogger(
    DebugPrintLogSink(),
    formatter: const PrettyEventLogRecordFormatter(),
  ),
);

Build/dispatch records follow controllerCreated → initialStateEstablished → eventStarted → transition* → eventCompleted | eventFailed. state.established is emitted once for the first terminal, non-loading build state; canceled builds and intermediate retry loading states are ignored. It has no event or previous state; its sanitized state summaries come from stateLabel and stateMetadata, with the final state supplied as both previous and next. A synchronous or asynchronous terminal error carries its error and stackTrace. controllerDisposed records the first Riverpod ref disposal signal registered by the controller. Provider invalidation may emit it before a rebuild on the same notifier, so it is not proof that the notifier instance was destroyed.

Blocpod does not emit a separate BLoC-style onChange phase. transition is the canonical event-attributed state-assignment record, so direct assignments outside dispatch remain intentionally unobserved. Pretty output renders the same transition record in a human-readable form instead of duplicating the core record stream. Pretty messages show metadata key summaries only; metadata values remain in BlocpodLogEntry.metadata for sink-level redaction and indexing.