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, dedicated sequence/trace fields, event name, transition index, state kinds, optional state labels, nested eventMetadata / stateMetadata, duration, errors, and stack traces.

EventLogRecord.metadata does not flatten into top-level logger fields anymore. Use the dedicated BlocpodLogEntry.sequence, traceId, spanId, and parentSpanId fields, and read remaining payload from attributes.

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, pair PrettyEventLogRecordFormatter with PrettyLogEncoder:

eventLoggerProvider.overrideWithValue(
  BlocpodEventLogger(
    DebugPrintLogSink(
      encoder: const PrettyLogEncoder(
        detail: PrettyLogDetail.verbose,
      ),
    ),
    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.

Example pretty entry:

12:00:00.000Z INFO  ✅ CounterController · IncrementEvent completed data(count:0) → data(count:1) in 12ms
  sequence=42 trace=trace-1/span-2 parent=span-1
  attributes={phase: event.completed, controllerName: CounterController, eventName: IncrementEvent, durationMicros: 12000, previousStateKind: data, nextStateKind: data, eventMetadata: {feature: counter}, stateMetadata: {changedBy: 1}}

Migration details:

• recordSequence now maps to BlocpodLogEntry.sequence.
• Trace IDs no longer travel inside metadata; they map to dedicated trace fields.
• Event payload lives under attributes['eventMetadata'].
• State payload lives under attributes['stateMetadata'].
• Sensitive-data policy belongs to the application or sink adapter that forwards logs beyond Blocpod.