obsidian-logfire/README.md

Logfire

Track everything. Query anything. Visualize it all.

An Obsidian plugin that logs all vault activity into a local SQLite database, makes it queryable via SQL, and visualizes results with charts and dashboards.

---

Features

Event Tracking

Logfire silently records vault activity in the background — file operations, content changes, navigation, editor keystrokes, and command executions. Events are buffered, debounced, and flushed to SQLite in batches for minimal performance impact.

SQL Query Engine

Query your vault data with full SQL support. Use the interactive query editor with shorthand syntax (events today, stats this-week group by file) or write raw SQL. Includes autocomplete for table names, columns, functions, and event types.

Data Visualization

• 10 SVG chart types — bar, line, area, pie, donut, scatter, gauge, sparkline, stacked bar, horizontal bar
• 6 render formats — table, timeline, summary, metric, list, heatmap
• Multi-widget dashboards with configurable grid layouts and auto-refresh
• Vim-style keyboard navigation (j/k/h/l, gg/G, /, y, Enter) for tables

Virtual Tables

Query live vault metadata alongside event data:

Table	Contents
_files	path, name, extension, size, created, modified, folder
_links	from_path, to_path, display_text, link_type
_tags	path, tag
_headings	path, level, heading

Projections & Reports

Automatically generate Markdown reports from event data. Built-in presets for daily logs, session logs, and weekly digests — or create custom projection templates with scheduling.

Query Management

• History — automatic tracking of all executed queries with metrics
• Favorites — save, categorize, and tag frequently used queries
• Templates — 9 built-in templates with parameter substitution, plus custom templates
• Export — CSV (Excel-compatible with BOM) and JSON export

---

Installation

Manual Installation

1. Download main.js, styles.css, and manifest.json from the latest release
2. Create a folder <your-vault>/.obsidian/plugins/logfire/
3. Copy the three files into that folder
4. Install the native SQLite dependency:

   cd <your-vault>/.obsidian/plugins/logfire/
   mkdir -p node_modules
   npm install better-sqlite3 --prefix .
   

5. Rebuild better-sqlite3 for your Obsidian's Electron version:

   # Find your Electron version (check Obsidian > Help > About)
   npx @electron/rebuild -v <electron-version> -m . --only better-sqlite3
   

6. Restart Obsidian and enable Logfire in Settings → Community Plugins

Build from Source

git clone git@github.com:tolvitty/obsidian-logfire.git
cd obsidian-logfire
npm install
npm run build

Then copy main.js, styles.css, and manifest.json to your plugin folder and follow steps 4–6 above for the native module setup.

Note: Logfire is desktop-only. It requires better-sqlite3, a native Node.js module that must match your Obsidian's Electron ABI version. Mobile is not supported.

---

Usage

Code Blocks

Embed live queries directly in your notes:

```logfire
range: today
group: file
format: table
```

```logfire-sql
SELECT source, COUNT(*) as events
FROM events
WHERE timestamp > (strftime('%s', 'now', 'start of day') * 1000)
GROUP BY source
ORDER BY events DESC
LIMIT 10
```

```logfire-dashboard
name: My Dashboard
columns: 12

[widget:chart row:0 col:0 width:6 height:2]
-- title: Events by Type
-- chart: pie
SELECT type, COUNT(*) as count FROM events GROUP BY type

[widget:stat row:0 col:6 width:3 height:1]
-- title: Total Events
SELECT COUNT(*) as value FROM events

[widget:query row:0 col:9 width:3 height:2]
-- title: Recent Files
SELECT source, COUNT(*) as n FROM events GROUP BY source ORDER BY n DESC LIMIT 5
```

Commands

All commands are available via the command palette (Ctrl/Cmd+P):

Command	Description
Show event stream	Real-time event sidebar
Show dashboard	Open dashboard view
Open query editor	Interactive SQL editor
Show schema browser	Browse tables, columns, indexes
Show query templates	Pick from built-in and custom templates
Run projection	Execute a Markdown report template
Toggle tracking	Pause/resume event collection
Toggle Vim navigation	Enable j/k/h/l navigation in tables

---

Architecture

src/
├── main.ts                    Plugin entry, lifecycle, commands
├── types.ts                   Event types, settings, query interfaces
├── core/
│   ├── database.ts            SQLite via better-sqlite3
│   ├── event-bus.ts           Circular buffer, pub/sub, auto-flush
│   ├── session-manager.ts     Session start/end, duration tracking
│   ├── content-analyzer.ts    Snapshot cache, word/link/tag diffs
│   └── query-builder.ts       QueryConfig → parameterized SQL
├── collectors/                File, content, nav, editor, system
├── query/                     Code-block processors, modal, virtual tables, autocomplete
├── viz/                       Table renderer, SVG charts, dashboards, Vim navigation
├── management/                History, favorites, templates
├── projection/                Report engine, formatters, presets
└── ui/                        Settings, status bar, event stream, schema browser

---

License

MIT