Recording and .uyava Logs

Uyava logs use the .uyava extension. They are NDJSON session streams (usually gzip-compressed) with a sessionHeader followed by event records.

Need the exact wire contract to generate .uyava files manually? See Session File Format (.uyava).

You can inspect a file locally with:

gunzip -c session.uyava > session.ndjson

Desktop recording

Desktop can record live sessions and save .uyava archives for replay.

Workflow:

  1. Connect to a live VM Service session.
  2. Start recording from the Record/Replay bar.
  3. Save the recording to finalize a .uyava file.
  4. Switch to File mode to replay the saved log.

Recording uses a ring buffer so long sessions remain manageable. Defaults:

  • window duration: 5 minutes
  • window size: 50 MB (pre-compression)

Older events are dropped as needed, and the UI shows drop counts so you know when the buffer trimmed.

Where files are saved

Desktop saves recordings to a default directory. The app prefers:

  • the last used recording folder
  • the sandbox temp folder (when sandboxed)
  • the configured output directory (if set)
  • the system temp directory

After saving, the app can reveal the current recording in your file explorer.

SDK file logging (record in your app)

To capture .uyava logs from your own app, enable file logging in the SDK:

import 'package:path_provider/path_provider.dart';
import 'package:uyava/uyava.dart';

Future<void> startLogging() async {
  final dir = await getApplicationDocumentsDirectory();
  await Uyava.enableFileLogging(
    config: UyavaFileLoggerConfig(
      directoryPath: dir.path,
      maxFileSizeBytes: 32 * 1024 * 1024,
      maxDuration: const Duration(minutes: 30),
      maxFileCount: 5,
      realtimeSamplingRate: 1.0,
      minLevel: UyavaSeverity.trace,
    ),
  );
}

Important notes:

  • directoryPath is required. Use path_provider to pick a stable path.
  • Files are gzip-compressed NDJSON with a .uyava extension.
  • A background worker handles rotation and compression to avoid UI jank.
  • Keep graph hierarchy meaningful in recorded snapshots; avoid a single synthetic global root if you want readable replay layouts.

Advanced file logger options

UyavaFileLoggerConfig also supports:

  • Export retention: maxExportCount, maxExportTotalBytes
  • Archive retention mode: retainLatestOnly
  • Realtime controls: realtimeEnabled, realtimeSamplingRate, realtimeBurstLimitPerSecond
  • Event/severity filters: includeTypes, excludeTypes, minLevel
  • Write pacing: flushInterval
  • Redaction: redaction (allowRawData, maskFields, dropFields, tag allow/deny lists, custom handler)
  • Crash-safe file name: panicMirrorFileName (used when crashSafePersistence: true)
  • Streaming journal: streamingJournalEnabled, streamingJournalFileName, streamingJournalFlushInterval

When realtime events are dropped by filters/sampling/burst limits, the logger emits aggregated discard control records in the archive and updates Uyava.discardStatsStream.

Exporting logs

Use the SDK helpers to export or snapshot logs without stopping recording:

final archive = await Uyava.exportCurrentArchive();
final snapshot = await Uyava.cloneActiveArchive();

Exports are copied into an exports/ subfolder inside the logging directory. By default, Uyava.latestArchiveSnapshot() also considers exported copies. Use includeExports: false to restrict it to rotated archives only.

Crash-safe logs (panic tail)

File logging supports crash-safe persistence. Enable it to mirror the last error into panic-tail.jsonl and seal the current archive after a fatal error. This is useful for collecting logs from end users after a crash.

Replay basics

Desktop can open .uyava files directly (double-click or File mode). The playback timeline supports speed changes and event markers, and Pro adds advanced seek controls for long sessions.

Known issue: some .uyava files may fail to open

In the current public beta, a subset of recordings may fail to open in Desktop.

If this happens:

  1. Try the latest Desktop build first.
  2. Open the file from Desktop File mode (instead of relying on OS file association).
  3. Verify the archive can be decompressed:
gunzip -c session.uyava > /tmp/session.ndjson

If decompression succeeds but Desktop still cannot open the file, report it with app version and platform details.