Metrics

File-first metrics for Obsidian that keep *.metrics.ndjson as the source of truth.

Metrics is an Obsidian plugin for viewing and editing canonical *.metrics.ndjson files inside your vault. It gives you a compact timeline, inline validation, cross-file search, filtering, grouping, summaries, and charts without introducing a hidden database or cache layer.

Why

The goal is to make metrics feel like normal vault data instead of app-owned state:

• metrics stay as plaintext files in your vault
• each line is one JSON object, so the data stays diffable and scriptable
• the plugin acts as a lens over the file instead of taking ownership of it
• validation issues are surfaced directly in the view instead of being silently swallowed

Features

• Dedicated metrics view for supported files
• Current-file record create, edit, and delete
• Missing-id assignment for legacy rows
• Metrics file create, rename, and delete
• Cross-file command-palette search that jumps to the matching row
• Filtering by time range, metric, source, validation status, and free text
• Sorting by newest, oldest, value high-low, and value low-high
• Grouping by day, week, month, year, metric, or source
• Optional derived summary rows for average, median, minimum, maximum, sum, and count
• Optional charts driven by the same visible rows as the timeline
• Per-file view state persistence
• Stable plain-text references such as metric:<id>
• Catalog-backed metric labels, units, icons, and formatting

Install

Metrics currently targets Obsidian 1.6.0+.

For a local install:

npm install
npm run build

Then copy these files into your vault plugin folder:

.obsidian/plugins/metrics-lens/
├── manifest.json
├── main.js
└── styles.css

After that, enable Metrics in Obsidian's community plugins screen.

Metric files

Each line in a metrics file is one JSON object.

Required fields:

• id
• ts
• key
• value
• source

Optional fields:

• date
• unit
• origin_id
• note
• context
• tags

Example:

{"id":"01JV7RK8Q4X60M0E2N0A6QK61V","ts":"2026-04-14T08:30:00+04:00","key":"body.weight","value":105.6,"unit":"kg","source":"withings"}
{"id":"01JV7RM60M9X1Y9G7TWJ3CF8ES","ts":"2026-04-14T09:10:00+04:00","key":"nutrition.energy_intake","value":720,"unit":"kcal","source":"manual","note":"breakfast"}

Default conventions:

• metrics root: Metrics/
• supported extension: *.metrics.ndjson
• default write target: Metrics/All.metrics.ndjson
• default record reference prefix: metric:

Validation behavior:

• unknown metric keys are allowed and shown as warnings
• unknown units are allowed and shown as warnings
• known-key and unit mismatches are warned instead of silently normalized
• duplicate id values are treated as errors and block safe record mutations

Commands

Current command set:

Open current file
Open view
Search
Add record to current file
New file
Rename current file
Delete current file
Assign missing ids in current file

Record-level copy, edit, and delete actions are available from the timeline row menu.

Settings

The plugin includes a small settings pane for vault-level conventions:

• metrics root folder
• supported extensions
• default write file
• record reference prefix
• week start day
• day start hour for time ranges and date-derived grouping
• metric label display mode: friendly names or canonical keys
• metric icon visibility
• custom metric catalog entries and advanced JSON

Built-in catalog

The first-party catalog lives in src/metric-catalog.json.

It drives:

• metric labels in rows, filters, and charts
• allowed units and unit formatting
• icon mapping
• record modal suggestions

Unknown keys remain allowed by the file contract so the plugin stays file-first and user-extensible.

Custom catalog

Custom catalog entries are stored in this plugin's per-vault settings as a versioned JSON object. The plugin merges custom entries over the built-in catalog and uses the merged catalog for validation warnings, labels, unit formatting, icons, and record modal suggestions.

The settings tab includes structured editors for custom metrics and custom units. Rows with catalog-related validation warnings also include catalog actions in the row menu, so an unknown metric can be added directly from the flagged record.

The advanced JSON editor stores only the custom delta:

{
  "schemaVersion": 1,
  "categories": {
    "training": {
      "label": "Training",
      "iconCandidates": ["activity"]
    }
  },
  "metrics": {
    "training.run_distance": {
      "label": "Run distance",
      "category": "training",
      "allowedUnits": ["km"],
      "defaultUnit": "km",
      "fractionDigits": 2,
      "iconCandidates": ["activity"]
    }
  },
  "units": {
    "serving": {
      "label": "Serving",
      "display": "serving",
      "aliases": ["servings"],
      "fractionDigits": 1
    }
  }
}

New metrics require label, category, and at least one allowedUnits entry. New units and categories require label. Existing built-in entries can be partially overridden by key.

Development

Install dependencies and start watch mode:

npm install
npm run dev

Build once:

npm run build

Run type-checking:

npm run check

For local vault development, place the built plugin in:

.obsidian/plugins/metrics-lens

Release process

Releases are published by GitHub Actions when you push a bare semantic version tag that matches manifest.json.

npm run check
npm run build
git tag 0.6.1 # replace with the manifest version
git push origin 0.6.1

Do not use a v prefix. Obsidian requires the GitHub Release tag to exactly match the version in manifest.json.

The release workflow validates the tag, manifest.json, and package.json, builds the production bundle, generates artifact attestations, writes categorized release notes from conventional commit messages, and uploads the Obsidian release assets:

• manifest.json
• main.js
• styles.css

License

MIT