tolvitty
22fd818668
Add English README with badges, installation guide, usage examples, and architecture overview. Bump version to 1.0.0 in manifest and package. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
201 lines
6.2 KiB
Markdown
201 lines
6.2 KiB
Markdown
<div align="center">
|
||
|
||
# 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)
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
## Features
|
||
|
||
</div>
|
||
|
||
### 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
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
## Installation
|
||
|
||
</div>
|
||
|
||
### 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 `<your-vault>/.obsidian/plugins/logfire/`
|
||
3. Copy the three files into that folder
|
||
4. Install the native SQLite dependency:
|
||
```bash
|
||
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:
|
||
```bash
|
||
# 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
|
||
|
||
```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.
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
## Usage
|
||
|
||
</div>
|
||
|
||
### 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 |
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
## Architecture
|
||
|
||
</div>
|
||
|
||
```
|
||
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
|
||
```
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
## License
|
||
|
||
MIT
|
||
|
||
</div>
|