Saropa Log Capture

      F5 debug  ──►  output  ──►  saved to  reports/*.log
                                        │
                                        ▼
                    ┌─────────────────────────────────────────┐
                    │  VIEWER (what VS Code doesn't give you) │
                    │  · Search all logs (regex, history)     │
                    │  · Click  file.dart:42  →  open source  │
                    │  · Filter by error / warning / level    │
                    │  · Keep many sessions, compare two      │
                    │  · Export HTML, CSV, or share .slc      │
                    └─────────────────────────────────────────┘

VS Code deletes your Debug Console the moment you stop debugging. Every print, every stack trace, every clue — gone. Saropa Log Capture fixes that. Install it, hit F5, and every debug session is automatically saved, searchable, and browsable. No configuration. Works with any debug adapter: Dart, Flutter, Node, Python, C++, Go, Java, and more.

Feedback or ideas? Open an issue.

Quick Start

1. Install from the VS Code Marketplace
2. Start a debug session (F5)
3. Output is automatically captured to reports/
4. Click the Saropa Log Capture icon on the activity bar to view output in real time

Testing the extension (F5): Use VS Code (not a downstream fork) to run the Extension Development Host: File → Open Folder → this repo, then press F5. Some forks may not load the extension when used as the F5 host.

Screenshots

Why Use This?

• Never lose output again — Debug Console output saved to reports/*.log automatically. Restart, switch targets — your logs survive.
• Click to source — Click file.ts:42 in any log line to jump to the code (Ctrl+Click for split editor).
• Search everything — Regex search with history, floating overlay (Ctrl+F), cross-session search.
• Filter the noise — Eight severity levels, log source tiers (Flutter DAP / Device / External), source tag chips, exclusion patterns, and saved presets. Tags & Origins side panel for browsing sources.
• Compare sessions — Side-by-side diff of any two runs.
• 100K+ lines, no lag — Virtual scrolling handles massive logs without freezing.
• Signals — Automatic detection of slow operations, N+1 queries, ANR risk, and error clusters with evidence-backed signal reports. Unified Signals panel with collections, all signals, hot files, and performance data.
• Error intelligence — Errors auto-classified as CRITICAL, TRANSIENT, or BUG with inline badges. Recurring patterns surfaced across sessions. Configurable alerts (flash, sound, badge, modal).
• SQL diagnostics — Drift ORM query fingerprinting, repeat compression, N+1 detection, slow query burst markers, and session SQL comparison.
• Structured file support — Open .md, .json, .csv, and .html files in the viewer with format-aware previews.
• Typography controls — Live font-size and line-height adjustment via keyboard shortcuts (Ctrl+=/-, Ctrl+Shift+=/-) or the Options panel.
• Post-capture workflow — Actionable end-of-capture toasts: Open Log, Always Open, or Don't Ask Again.
• Pop-out viewer — Move the viewer to a second monitor for full-screen analysis.
• Export anywhere — HTML, CSV, JSON, shareable .slc bundles, or push to Grafana Loki.
• Collections — Pin logs and files into named collections. Dedicated slide-out panel for merging and managing grouped sessions.
• Tail any log — Open any workspace .log file and watch new lines live.
• Run navigation — Jump between Flutter runs (launch, hot restart, hot reload) inside a single log.
• Session groups — A debug session and its sidecar logs collapse into one entry in the Logs panel with severity totals.
• Integration adapters — Opt-in adapters attach Git state, lockfile hashes, env snapshots, test results, crash dumps, Docker inspect, and more to each session header.

Features

Works Best With

Saropa Log Capture works standalone, but unlocks richer diagnostics when paired with these companion extensions:

One-click install: Get all three with the Saropa Suite extension pack.

Requirements

• VS Code ^1.108.1 — also available via Open VSX for compatible editors.
• Node.js >= 22 for building and tests. Optional: use the Dev Container (.devcontainer/devcontainer.json). See CONTRIBUTING.md.

Remote Development

Fully supports Remote SSH, WSL, and Dev Containers. Use a relative logDirectory (like reports or .logs) to keep captures inside your remote workspace. No extra setup required.

Configuration

All settings are prefixed with saropaLogCapture. — see docs/CONFIGURATION.md for the full settings reference.

Key settings:

Tip: To capture system/framework noise alongside your app logs, toggle App Only: OFF in the viewer or set captureAll to true.

Extension API

Other VS Code extensions can consume a typed API from Saropa Log Capture:

import * as vscode from 'vscode';

// In your extension's activate():
const ext = vscode.extensions.getExtension('saropa.saropa-log-capture');
if (!ext) { return; }
const api = ext.isActive ? ext.exports : await ext.activate();

// Subscribe to live log lines
context.subscriptions.push(
    api.onDidWriteLine((line) => {
        // `stderr` can carry non-error info; classify by text/category policy instead.
        if (/\b(error|exception|fatal|failed)\b/i.test(line.text)) {
            console.log(`Error: ${line.text}`);
        }
    }),
);

// Session lifecycle
context.subscriptions.push(
    api.onDidStartSession((session) => {
        console.log(`Capture started: ${session.projectName}`);
    }),
);

// Write lines into the active capture session
api.writeLine('Slow query detected (1250ms)', {
    category: 'drift-perf',
    timestamp: queryEndTime,
});

// Query current state
const info = api.getSessionInfo();
if (info?.isActive) {
    api.insertMarker('My extension checkpoint');
}

// Register an integration provider
context.subscriptions.push(
    api.registerIntegrationProvider({
        id: 'my-extension',
        isEnabled: () => true,
        onSessionStartSync: () => [{
            kind: 'header',
            lines: ['My Extension: active'],
        }],
    }),
);

See api-types.ts for the full type definitions.

Key Commands

Full command list available via Command Palette (Ctrl+Shift+P → "Saropa").

Keyboard Shortcuts

Press F1 inside the viewer for the full interactive reference with descriptions and rebinding.

See docs/walkthrough/keyboard-shortcuts.md for the complete list, or open Options → Keyboard shortcuts... in the viewer. All 51 power shortcuts are rebindable via saropaLogCapture.viewerKeybindings.

Known Limitations

• Empty or near-empty log files: If the Debug Console has output but the open log shows only a header, use Prev/Next in the viewer and enable diagnosticCapture to inspect the pipeline. See Runbook: Missing or empty log files.
• Viewer line cap: The viewer shows the first N lines (viewerMaxLines, default 50,000). The full file is kept on disk up to maxLines (default 100,000). Toolbar shows "Showing first X of Y lines" when truncated.
• Debug Console only: The main capture stream is from the VS Code Debug Console (DAP). Enable the terminal integration adapter to also capture Integrated Terminal output.

Accessibility

The webview viewer supports keyboard and assistive tech. Main content has a main landmark; the icon bar is a toolbar; the log area has role="log" with live region announcements. Slide-out panels have region landmarks; focus moves into them on open and returns on Escape. For the full audit, see plans/028_plan-webview-accessibility.md.

Contributing

Contributions and feedback are welcome.

• Broken — tell us what happened, we'll fix it
• Missing — propose it, or better yet, submit a PR
• Confusing — help us improve the docs or UX

See CONTRIBUTING.md for developer setup, code quality standards, and contribution guidelines.

Quick start: Fork → feature branch → npm run compile → Pull Request.

Testing (F5): Open in VS Code → F5 → Extension Development Host. For the test suite, install the recommended Extension Test Runner and use the Testing view, or run npm test.

Translations

The extension ships localized UI strings for 11 locales: Chinese (Simplified & Traditional), German, Spanish, French, Italian, Japanese, Korean, Portuguese (Brazil), and Russian. Corrections welcome — email language@saropa.com.

Documentation

License

MIT — see LICENSE. Use it however you like.

Built by Saropa. Questions? Ideas? Open an issue.

GitHub | Issues | Saropa