# 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.
[](https://github.com/tolvitty/obsidian-logfire/releases)
[](LICENSE)
[](https://obsidian.md)
[](https://sqlite.org)
---
## 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](https://github.com/tolvitty/obsidian-logfire/releases/latest)
2. Create a folder `/.obsidian/plugins/logfire/`
3. Copy the three files into that folder
4. Install the native SQLite dependency:
```bash
cd /.obsidian/plugins/logfire/
mkdir -p node_modules
npm install better-sqlite3 --prefix .
```
5. Rebuild `better-sqlite3` for your Obsidian's Electron version:
```bash
# Find your Electron version (check Obsidian > Help > About)
npx @electron/rebuild -v -m . --only better-sqlite3
```
6. Restart Obsidian and enable **Logfire** in Settings → Community Plugins
### Build from Source
```bash
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:
````markdown
```logfire
range: today
group: file
format: table
```
````
````markdown
```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
```
````
````markdown
```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