Lightning Logs Analyzer

A VS Code extension for rapid analysis and comparison of PyTorch Lightning CSV log files.

Use cases include:

• Small-scale experiments where a dedicated experiment management tool like TensorBoard/MLFlow is overkill
• Quick iteration on training runs without leaving the editor
• Comparing multiple runs side-by-side with hyperparameter context

Features

• File browser — sidebar tree view with checkboxes to select CSV log files from a chosen directory
• Column selector — dynamically shows the union of all column headers from checked files; toggle which metrics to plot
• Interactive charts — Chart.js-powered line charts in the main editor area with color-coded runs
• X-axis selection — pick which column to use as X-axis (defaults to step)
• Hyperparameter display — loads hparams.yaml from each run directory and shows them in chart tooltips and a collapsible panel
• Summary statistics — min, max, mean, last value for each plotted series
• Live reload — file watcher detects CSV changes during training and auto-updates the plot
• Export — save charts as PNG images
• Theme integration — charts adapt to VS Code light/dark/high-contrast themes

Getting Started

1. Install dependencies

   npm install
   

2. Build

   npm run build
   

3. Debug — Press F5 in VS Code to launch the Extension Development Host

4. Use

   • Click the ⚡ Lightning Logs icon in the activity bar
   • Use the folder button to select your log directory (defaults to logs/)
   • Check CSV files in the file tree
   • Select columns to plot in the Columns panel
   • Click the graph button to open the analysis panel

Expected Directory Structure

The extension works with the standard PyTorch Lightning logging layout:

logs/
├── version_0/
│   ├── metrics.csv
│   └── hparams.yaml
├── version_1/
│   ├── metrics.csv
│   └── hparams.yaml
└── ...

CSV files should be UTF-8 encoded with a header row. The hparams.yaml file is optional but will be loaded automatically when present alongside a CSV.

Sample Data

The sample_logs/ directory contains example data for testing:

• version_0/ — lr=0.001, Adam optimizer, hidden_dim=256
• version_1/ — lr=0.01, SGD optimizer, hidden_dim=512

Configuration

Architecture

src/
├── extension.ts              # Entry point: activate/deactivate, command registration
├── state.ts                  # Central state manager with event emitters
├── services/
│   ├── csvParser.ts          # CSV header/data parsing with csv-parse
│   ├── hparamsLoader.ts      # YAML loader for hparams.yaml files
│   └── fileWatcher.ts        # Debounced FileSystemWatcher
└── views/
    ├── fileTreeProvider.ts   # TreeDataProvider for the log file browser
    ├── columnSelectorProvider.ts  # TreeDataProvider for metric column toggles
    └── webviewPanel.ts       # WebviewPanel manager, data→chart pipeline

media/
├── chart.min.js              # Chart.js UMD bundle (loaded in webview)
├── main.js                   # Webview client-side chart rendering logic
└── style.css                 # Webview styles (uses VS Code CSS variables)

Development

npm run watch    # esbuild in watch mode
# Press F5 to launch Extension Development Host

Packaging

npx vsce package

CI & Release Strategy

The project uses GitHub Actions (.github/workflows/ci.yml) with two jobs:

Test (all pushes & PRs to main)

Installs dependencies, builds the extension, and runs the full test suite under xvfb.

Release (merge to main only)

Runs after tests pass and automates the entire release cycle using Conventional Commits:

1. Detect bump level — scans commit messages since the last v* tag: | Commit prefix | Bump | |---|---| | feat: / feat(...): | minor | | fix:, perf:, refactor:, chore:, etc. | patch | | BREAKING CHANGE or !: suffix | major | | No conventional prefix | skip release |

2. Bump version — updates package.json via npm version.

3. Build & package — produces a .vsix file.

4. Commit back — pushes the version bump to main with [skip ci] to prevent loops.

5. Tag & release — creates a git tag vX.Y.Z and a GitHub Release with the VSIX attached.

6. Upload artifact — the VSIX is also available as a downloadable Actions artifact.

Commit message examples

fix(parser): handle empty CSV rows        → patch bump
feat: add multi-file export               → minor bump
feat!: redesign chart rendering API        → major bump
docs: update README                        → patch bump

Note: If the repo has branch protection on main, the GitHub Actions bot must be allowed to push, or a PAT should be configured as a repo secret.