feat(ground-suite): add replay observability console

This commit is contained in:
Onur Özkan committed 2026-08-10 15:24:39 +03:00
1 parent 1d28db2983
commit c06c293f49
33 files changed
+2636

No files matched your search

@@ -0,0 +1,273 @@
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../../../core/observations/observed_event.dart';
import '../../../shared/widgets/severity_badge.dart';
import '../../observability/presentation/observability_controller.dart';
enum _DiagnosticFilter { all, logs, errors, shutdowns }
class DiagnosticsPage extends ConsumerStatefulWidget {
const DiagnosticsPage({super.key});
@override
ConsumerState<DiagnosticsPage> createState() => _DiagnosticsPageState();
}
class _DiagnosticsPageState extends ConsumerState<DiagnosticsPage> {
_DiagnosticFilter _filter = _DiagnosticFilter.all;
String _query = '';
@override
Widget build(BuildContext context) {
final state = ref.watch(observabilityControllerProvider);
final events = state.events.where(_matches).toList(growable: false);
return ListView(
padding: const EdgeInsets.all(24),
children: [
Text('Diagnostics', style: Theme.of(context).textTheme.headlineMedium),
const SizedBox(height: 8),
const Text(
'Messages remain distinct by protocol class. A configuration result '
'will remain authoritative when configuration support is added.',
),
const SizedBox(height: 16),
Wrap(
spacing: 8,
runSpacing: 8,
children: _DiagnosticFilter.values
.map(
(filter) => ChoiceChip(
label: Text(_labelFor(filter)),
selected: _filter == filter,
onSelected: (_) => setState(() => _filter = filter),
),
)
.toList(growable: false),
),
const SizedBox(height: 12),
TextField(
decoration: const InputDecoration(
border: OutlineInputBorder(),
labelText: 'Filter diagnostics',
prefixIcon: Icon(Icons.search),
),
onChanged: (value) {
setState(() => _query = value.trim().toLowerCase());
},
),
const SizedBox(height: 16),
if (events.isEmpty)
const Card(
child: Padding(
padding: EdgeInsets.all(20),
child: Text('No diagnostic observations match this filter.'),
),
)
else
...events.map((event) => _DiagnosticCard(event: event)),
],
);
}
bool _matches(ObservedEvent event) {
final typeMatches = switch (_filter) {
_DiagnosticFilter.all =>
event is LogEvent || event is ErrorEvent || event is ShutdownEvent,
_DiagnosticFilter.logs => event is LogEvent,
_DiagnosticFilter.errors => event is ErrorEvent,
_DiagnosticFilter.shutdowns => event is ShutdownEvent,
};
if (!typeMatches) {
return false;
}
if (_query.isEmpty) {
return true;
}
return _searchableText(event).toLowerCase().contains(_query);
}
}
class _DiagnosticCard extends StatelessWidget {
const _DiagnosticCard({required this.event});
final ObservedEvent event;
@override
Widget build(BuildContext context) {
final theme = Theme.of(context);
final content = switch (event) {
LogEvent(:final level, :final message, :final flags) => _LogContent(
level: level,
message: message,
flags: flags,
),
ErrorEvent(:final path, :final additionalInformation, :final flags) =>
_ErrorContent(
path: path,
additionalInformation: additionalInformation,
flags: flags,
),
ShutdownEvent(:final reason) => _ShutdownContent(reason: reason),
_ => null,
};
if (content == null) {
return const SizedBox.shrink();
}
return Semantics(
container: true,
label: content.semanticLabel,
child: Card(
margin: const EdgeInsets.only(bottom: 12),
child: Padding(
padding: const EdgeInsets.all(16),
child: Row(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
content.leading,
const SizedBox(width: 12),
Expanded(
child: SelectionArea(
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(content.title, style: theme.textTheme.titleMedium),
const SizedBox(height: 4),
Text(content.detail),
if (content.additionalDetail case final detail?) ...[
const SizedBox(height: 8),
Text(detail),
],
const SizedBox(height: 8),
Text(
event.receivedAt.toIso8601String(),
style: theme.textTheme.bodySmall,
),
],
),
),
),
],
),
),
),
);
}
}
class _DiagnosticContent {
const _DiagnosticContent({
required this.leading,
required this.title,
required this.detail,
required this.semanticLabel,
this.additionalDetail,
});
final Widget leading;
final String title;
final String detail;
final String? additionalDetail;
final String semanticLabel;
}
class _LogContent extends _DiagnosticContent {
_LogContent({
required MavSeverity level,
required String message,
required int flags,
}) : super(
leading: SeverityBadge(level: level),
title: 'Log — ${level.label}',
detail: message,
additionalDetail: _formatLogFlags(flags),
semanticLabel: _semanticLogLabel(level, message, flags),
);
}
class _ErrorContent extends _DiagnosticContent {
_ErrorContent({
required String path,
required String additionalInformation,
required int flags,
}) : super(
leading: const SeverityBadge(level: MavSeverity.error),
title: 'Error',
detail: path,
additionalDetail: _formatErrorDetail(additionalInformation, flags),
semanticLabel: _semanticErrorLabel(path, additionalInformation, flags),
);
}
class _ShutdownContent extends _DiagnosticContent {
_ShutdownContent({required KaptanShutdownReason reason})
: super(
leading: const Icon(Icons.power_settings_new_outlined),
title: 'Orderly shutdown observed',
detail: 'Reason: ${reason.label}',
semanticLabel: 'Orderly shutdown observed: ${reason.label}',
);
}
String _labelFor(_DiagnosticFilter filter) => switch (filter) {
_DiagnosticFilter.all => 'All',
_DiagnosticFilter.logs => 'Logs',
_DiagnosticFilter.errors => 'Errors',
_DiagnosticFilter.shutdowns => 'Shutdowns',
};
String _searchableText(ObservedEvent event) => switch (event) {
LogEvent(:final level, :final message) => '${level.label} $message',
ErrorEvent(:final path, :final additionalInformation) =>
'$path $additionalInformation',
ShutdownEvent(:final reason) => reason.label,
_ => '',
};
String? _formatLogFlags(int flags) {
final labels = <String>[
if (flags & LogEvent.traceFlag != 0) 'Trace',
if (flags & LogEvent.truncatedFlag != 0) 'Truncated',
if (flags & LogEvent.coalescedFlag != 0) 'Coalesced',
if (flags & ~LogEvent.knownFlags != 0)
'Unknown bits 0x${(flags & ~LogEvent.knownFlags).toRadixString(16)}',
];
return labels.isEmpty ? null : 'Flags: ${labels.join(', ')}';
}
String? _formatErrorDetail(String additionalInformation, int flags) {
final flagDetail = _formatErrorFlags(flags);
final details = <String>[
if (additionalInformation.isNotEmpty) additionalInformation,
?flagDetail,
];
return details.isEmpty ? null : details.join('\n');
}
String? _formatErrorFlags(int flags) {
final labels = <String>[
if (flags & ErrorEvent.truncatedFlag != 0) 'Truncated',
if (flags & ErrorEvent.coalescedFlag != 0) 'Coalesced',
if (flags & ~ErrorEvent.knownFlags != 0)
'Unknown bits 0x${(flags & ~ErrorEvent.knownFlags).toRadixString(16)}',
];
return labels.isEmpty ? null : 'Flags: ${labels.join(', ')}';
}
String _semanticLogLabel(MavSeverity level, String message, int flags) {
final flagDetail = _formatLogFlags(flags);
return flagDetail == null
? '${level.label} log: $message'
: '${level.label} log: $message. $flagDetail';
}
String _semanticErrorLabel(
String path,
String additionalInformation,
int flags,
) {
final detail = _formatErrorDetail(additionalInformation, flags);
return detail == null ? 'Error: $path' : 'Error: $path. $detail';
}
@@ -0,0 +1,206 @@
import 'dart:async';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../../../core/observations/observed_event.dart';
import '../../../core/observations/vehicle_data_port.dart';
import '../../../core/observations/vehicle_data_update.dart';
import '../../../core/transport/replay_vehicle_data_port.dart';
final vehicleDataPortProvider = Provider<VehicleDataPort>((ref) {
final port = const ReplayVehicleDataPort();
ref.onDispose(() => unawaited(port.close()));
return port;
});
final observabilityControllerProvider =
NotifierProvider<ObservabilityController, ObservabilityState>(
ObservabilityController.new,
);
class ObservabilityController extends Notifier<ObservabilityState> {
static const _criticalAnnouncementWindow = Duration(seconds: 2);
StreamSubscription<VehicleDataUpdate>? _subscription;
DateTime? _lastCriticalAnnouncementAt;
@override
ObservabilityState build() {
final source = ref.read(vehicleDataPortProvider);
ref.onDispose(_cancelSubscription);
Future<void>.microtask(() => _observe(source));
return ObservabilityState.initial(source);
}
void _observe(VehicleDataPort source) {
_subscription = source.observe().listen(
_handleUpdate,
onError: (Object _, StackTrace _) {
state = state.copyWith(
status: ObservationStatus.disconnected,
accessibilityAnnouncement: 'Observation connection closed.',
replaceAccessibilityAnnouncement: true,
);
},
onDone: () {
state = state.copyWith(
status: source.isReplay
? ObservationStatus.replayComplete
: ObservationStatus.disconnected,
accessibilityAnnouncement: source.isReplay
? 'Replay complete.'
: 'Observation connection closed.',
replaceAccessibilityAnnouncement: true,
);
},
);
}
void _handleUpdate(VehicleDataUpdate update) {
switch (update) {
case ObservationReceived(:final event):
_record(event);
case ObservationDropped(:final kind, :final count):
state = state.copyWith(
status: ObservationStatus.receiving,
parserDropCount:
state.parserDropCount +
(kind == ObservationDropKind.parser ? count : 0),
semanticDropCount:
state.semanticDropCount +
(kind == ObservationDropKind.semantic ? count : 0),
);
}
}
void _record(ObservedEvent event) {
final announcement = _announcementFor(event);
state = state.copyWith(
status: ObservationStatus.receiving,
lastFrameAt: event.receivedAt,
events: [...state.events, event],
accessibilityAnnouncement: announcement.message,
replaceAccessibilityAnnouncement: true,
coalescedAlertCount:
state.coalescedAlertCount + (announcement.coalesced ? 1 : 0),
);
}
_AnnouncementDecision _announcementFor(ObservedEvent event) {
final candidate = switch (event) {
ErrorEvent(:final path) => 'Error received: $path',
ShutdownEvent(:final reason) =>
'Orderly shutdown observed: ${reason.label}',
_ => null,
};
if (candidate == null) {
return const _AnnouncementDecision();
}
final now = DateTime.now();
final previous = _lastCriticalAnnouncementAt;
if (previous != null &&
now.difference(previous) < _criticalAnnouncementWindow) {
return const _AnnouncementDecision(coalesced: true);
}
_lastCriticalAnnouncementAt = now;
return _AnnouncementDecision(message: candidate);
}
void _cancelSubscription() {
_subscription?.cancel();
}
}
enum ObservationStatus {
starting('Starting'),
receiving('Observing'),
replayComplete('Replay complete'),
disconnected('Disconnected');
const ObservationStatus(this.label);
final String label;
}
class ObservabilityState {
const ObservabilityState({
required this.sourceLabel,
required this.isReplay,
required this.status,
required this.events,
required this.parserDropCount,
required this.semanticDropCount,
required this.coalescedAlertCount,
this.lastFrameAt,
this.accessibilityAnnouncement,
});
factory ObservabilityState.initial(VehicleDataPort source) {
return ObservabilityState(
sourceLabel: source.label,
isReplay: source.isReplay,
status: ObservationStatus.starting,
events: const [],
parserDropCount: 0,
semanticDropCount: 0,
coalescedAlertCount: 0,
);
}
final String sourceLabel;
final bool isReplay;
final ObservationStatus status;
final List<ObservedEvent> events;
final int parserDropCount;
final int semanticDropCount;
final int coalescedAlertCount;
final DateTime? lastFrameAt;
final String? accessibilityAnnouncement;
HeartbeatEvent? get lastHeartbeat {
for (final event in events.reversed) {
if (event case HeartbeatEvent()) {
return event;
}
}
return null;
}
Set<TelemetryKind> get observedTelemetryKinds => {
for (final event in events)
if (event case TelemetryEvent(:final kind)) kind,
};
ObservabilityState copyWith({
ObservationStatus? status,
List<ObservedEvent>? events,
int? parserDropCount,
int? semanticDropCount,
int? coalescedAlertCount,
DateTime? lastFrameAt,
String? accessibilityAnnouncement,
bool replaceAccessibilityAnnouncement = false,
}) {
return ObservabilityState(
sourceLabel: sourceLabel,
isReplay: isReplay,
status: status ?? this.status,
events: events ?? this.events,
parserDropCount: parserDropCount ?? this.parserDropCount,
semanticDropCount: semanticDropCount ?? this.semanticDropCount,
coalescedAlertCount: coalescedAlertCount ?? this.coalescedAlertCount,
lastFrameAt: lastFrameAt ?? this.lastFrameAt,
accessibilityAnnouncement: replaceAccessibilityAnnouncement
? accessibilityAnnouncement
: this.accessibilityAnnouncement,
);
}
}
class _AnnouncementDecision {
const _AnnouncementDecision({this.message, this.coalesced = false});
final String? message;
final bool coalesced;
}
@@ -0,0 +1,147 @@
import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import '../../observability/presentation/observability_controller.dart';
class OverviewPage extends ConsumerWidget {
const OverviewPage({super.key});
@override
Widget build(BuildContext context, WidgetRef ref) {
final state = ref.watch(observabilityControllerProvider);
final heartbeat = state.lastHeartbeat;
final telemetry = state.observedTelemetryKinds
.map((kind) => kind.label)
.join(', ');
final identity = heartbeat == null
? 'Not observed'
: 'System ${heartbeat.systemId} / component ${heartbeat.componentId}';
final identityDetail = heartbeat == null
? 'Awaiting HEARTBEAT.'
: 'Reported by last HEARTBEAT: '
'${heartbeat.armed ? 'Armed' : 'Disarmed'} · ${heartbeat.vehicleState}';
return LayoutBuilder(
builder: (context, constraints) {
final horizontalPadding = constraints.maxWidth < 600 ? 16.0 : 24.0;
final cardWidth = constraints.maxWidth < 640
? constraints.maxWidth - (horizontalPadding * 2)
: 280.0;
return ListView(
padding: EdgeInsets.all(horizontalPadding),
children: [
Text('Overview', style: Theme.of(context).textTheme.headlineMedium),
const SizedBox(height: 8),
const Text(
'This workspace is receive-only. A link or replay never implies a '
'safe, armed, or command-capable vehicle.',
),
const SizedBox(height: 24),
Wrap(
spacing: 16,
runSpacing: 16,
children: [
_SummaryCard(
title: 'Source',
value: state.sourceLabel,
width: cardWidth,
detail: state.isReplay
? 'Deterministic replay; no physical vehicle is connected.'
: 'Receive-only transport.',
icon: Icons.visibility_outlined,
),
_SummaryCard(
title: 'Vehicle identity',
value: identity,
detail: identityDetail,
width: cardWidth,
icon: Icons.memory_outlined,
),
_SummaryCard(
title: 'Observed streams',
value: telemetry.isEmpty ? 'None' : telemetry,
detail: state.isReplay
? '${state.events.length} replayed observation(s).'
: '${state.events.length} observation(s).',
width: cardWidth,
icon: Icons.sensors_outlined,
),
_SummaryCard(
title: 'Decoder accounting',
value:
'${state.parserDropCount} parser / ${state.semanticDropCount} semantic',
detail: 'Counters are zero in the typed replay fixture.',
width: cardWidth,
icon: Icons.rule_outlined,
),
],
),
const SizedBox(height: 24),
Card(
child: Padding(
padding: const EdgeInsets.all(20),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Text(
'Configuration is unavailable',
style: Theme.of(context).textTheme.titleLarge,
),
const SizedBox(height: 8),
const Text(
'Kaptan firmware does not yet accept inbound configuration '
'authority. Ground Suite will not show upload, commit, arm, '
'or shutdown controls until the firmware exposes reviewed '
'authenticated ingress and safe activation.',
),
],
),
),
),
],
);
},
);
}
}
class _SummaryCard extends StatelessWidget {
const _SummaryCard({
required this.title,
required this.value,
required this.detail,
required this.icon,
required this.width,
});
final String title;
final String value;
final String detail;
final IconData icon;
final double width;
@override
Widget build(BuildContext context) {
return SizedBox(
width: width,
child: Card(
child: Padding(
padding: const EdgeInsets.all(20),
child: Column(
crossAxisAlignment: CrossAxisAlignment.start,
children: [
Icon(icon),
const SizedBox(height: 16),
Text(title, style: Theme.of(context).textTheme.labelLarge),
const SizedBox(height: 4),
Text(value, style: Theme.of(context).textTheme.titleLarge),
const SizedBox(height: 8),
Text(detail),
],
),
),
),
);
}
}