Obsidian Observability

Overview

Implement production observability for Obsidian plugins: a structured logger with levels and ring buffer history, a metrics collector with counters/gauges/timers, an error tracker with deduplication, and a debug sidebar panel that displays all of it in real time. Every component is copy-pasteable and uses only Obsidian's built-in APIs.

Prerequisites

• Working Obsidian plugin (see obsidian-core-workflow-a)
• TypeScript strict mode enabled
• Familiarity with ItemView for the debug panel

Instructions

Step 1: Structured Logger with Levels and History

// src/services/logger.ts
type LogLevel = 'debug' | 'info' | 'warn' | 'error';

const LEVEL_PRIORITY: Record<LogLevel, number> = {
  debug: 0, info: 1, warn: 2, error: 3,
};

interface LogEntry {
  timestamp: number;
  level: LogLevel;
  message: string;
  data?: unknown;
}

export class Logger {
  private history: LogEntry[] = [];
  private maxHistory = 200;
  private level: LogLevel;
  private prefix: string;

  constructor(pluginId: string, level: LogLevel = 'info') {
    this.prefix = `[${pluginId}]`;
    this.level = level;
  }

  setLevel(level: LogLevel) { this.level = level; }

  debug(msg: string, data?: unknown) { this.log('debug', msg, data); }
  info(msg: string, data?: unknown)  { this.log('info', msg, data); }
  warn(msg: string, data?: unknown)  { this.log('warn', msg, data); }
  error(msg: string, data?: unknown) { this.log('error', msg, data); }

  /** Start a timer, returns a function that stops it and logs duration */
  time(label: string): () => number {
    const start = performance.now();
    return () => {
      const ms = performance.now() - start;
      this.debug(`${label} (${ms.toFixed(2)}ms)`);
      return ms;
    };
  }

  /** Get last N log entries */
  getHistory(count?: number): LogEntry[] {
    return count ? this.history.slice(-count) : [...this.history];
  }

  /** Export history as JSON string */
  export(): string {
    return JSON.stringify(this.history, null, 2);
  }

  private log(level: LogLevel, message: string, data?: unknown) {
    if (LEVEL_PRIORITY[level] < LEVEL_PRIORITY[this.level]) return;

    const entry: LogEntry = { timestamp: Date.now(), level, message, data };
    this.history.push(entry);
    if (this.history.length > this.maxHistory) {
      this.history.splice(0, this.history.length - this.maxHistory);
    }

    const fn = level === 'debug' ? console.debug
             : level === 'warn' ? console.warn
             : level === 'error' ? console.error
             : console.log;
    if (data !== undefined) {
      fn(this.prefix, message, data);
    } else {
      fn(this.prefix, message);
    }
  }
}

Step 2: Metrics Collector with Counter

Obsidian Prod Checklist

Overview

Pre-release verification for Obsidian plugins covering manifest validation, production build quality, mobile compatibility, memory leak prevention, settings migration, and community plugin submission readiness.

Prerequisites

• Completed plugin development with all features working
• Tested in at least one vault manually
• GitHub repository with source code committed
• Node.js build toolchain configured

Instructions

Step 1: Validate manifest.json

// Run: node -e '<paste this>'
const m = require('./manifest.json');

const required = ['id', 'name', 'version', 'minAppVersion', 'description', 'author'];
const missing = required.filter(f => !m[f]);
if (missing.length) {
  console.error('FAIL: Missing fields:', missing.join(', '));
  process.exit(1);
}

// id must be kebab-case, no spaces
if (!/^[a-z0-9-]+$/.test(m.id)) {
  console.error('FAIL: id must be lowercase alphanumeric with hyphens:', m.id);
  process.exit(1);
}

// minAppVersion should be a recent Obsidian version
const [major, minor] = m.minAppVersion.split('.').map(Number);
if (major < 1 || (major === 1 && minor < 4)) {
  console.warn('WARN: minAppVersion', m.minAppVersion, 'is very old — consider 1.5.0+');
}

console.log('manifest.json OK:', m.id, 'v' + m.version, '(requires Obsidian >=' + m.minAppVersion + ')');

Step 2: Validate versions.json

// Run: node -e '<paste this>'
const manifest = require('./manifest.json');
const versions = require('./versions.json');
const pkg = require('./package.json');

let fail = false;

// manifest.version should match package.json version
if (manifest.version !== pkg.version) {
  console.error('FAIL: manifest.version (' + manifest.version + ') !== package.json (' + pkg.version + ')');
  fail = true;
}

// versions.json must have an entry for current version
if (!versions[manifest.version]) {
  console.error('FAIL: versions.json missing entry for', manifest.version);
  fail = true;
} else if (versions[manifest.version] !== manifest.minAppVersion) {
  console.error('FAIL: versions.json[' + manifest.version + '] = ' +
    versions[manifest.version] + ' but manifest.minAppVersion = ' + manifest.minAppVersion);
  fail = true;
}

if (fail) process.exit(1);
console.log('versions.json OK: all versions consistent');

Step 3: Production Build Checks

set -euo pipefail
# Clean build
rm -f main.js
npm ci
npm run build

# Verify main.js exists and is reasonable size
test -f main.js || { echo "FAIL: main.js not generated"; exit 1; 

Obsidian Rate Limits

Overview

Obsidian has no traditional API rate limits, but it runs on Electron with a single-threaded UI. This skill covers debouncing, batching, throttling, and async queue patterns to keep plugins responsive and prevent UI freezes.

Prerequisites

• Understanding of JavaScript event loop and requestAnimationFrame
• Familiarity with async/await and Promises
• Working Obsidian plugin with file operations

Instructions

Step 1: Debounce vault.on('modify') Events

vault.on('modify') fires on every keystroke when a user types in a note. Without debouncing, your handler runs hundreds of times per second.

import { Plugin, TFile, debounce } from 'obsidian';

export default class ThrottledPlugin extends Plugin {
  async onload() {
    // Obsidian provides a built-in debounce utility
    const debouncedHandler = debounce(
      (file: TFile) => this.handleFileModified(file),
      500,   // wait 500ms after last keystroke
      true   // run on leading edge too (immediate first call)
    );

    this.registerEvent(
      this.app.vault.on('modify', debouncedHandler)
    );
  }

  private async handleFileModified(file: TFile) {
    // This runs at most once per 500ms per burst of edits
    const cache = this.app.metadataCache.getFileCache(file);
    if (cache?.frontmatter?.tracked) {
      await this.updateIndex(file);
    }
  }
}

If you need per-file debouncing (common when multiple files change simultaneously):

private fileTimers = new Map<string, NodeJS.Timeout>();

private debouncedPerFile(file: TFile, fn: () => void, delay = 500) {
  const existing = this.fileTimers.get(file.path);
  if (existing) clearTimeout(existing);

  const timer = setTimeout(() => {
    this.fileTimers.delete(file.path);
    fn();
  }, delay);

  // Use activeWindow for Obsidian's timeout tracking
  this.fileTimers.set(file.path, timer);
}

Step 2: Batch File Operations with UI Yielding

Processing hundreds of files synchronously locks the UI. Yield back to the main thread between batches.

async processAllFiles(): Promise<void> {
  const files = this.app.vault.getMarkdownFiles();
  const BATCH_SIZE = 50;
  const results: ProcessResult[] = [];

  for (let i = 0; i < files.length; i += BATCH_SIZE) {
    const batch = files.slice(i, i + BATCH_SIZE);

    // Process one batch
    for (const file of batch) {
      const content = await this.app.vault.cachedRead(file);
      results.push(this.processContent(file.path, content));
    }

    // Yield to UI thread between batches
    await sleep(0);

    // Update progress if you have a status bar or notice
    const pct = Math.round(((i + batch.length) / files.length) * 100);
    this.statusBar?

Obsidian Reference Architecture

Overview

Architecture patterns for complex Obsidian plugins: modular project structure with separate files for views, commands, settings, and services; state management; a service layer for vault operations; command registry; view manager; and CSS scoping.

Prerequisites

• TypeScript and Obsidian API familiarity
• Working build pipeline (esbuild recommended)
• Plugin scaffolding complete (manifest.json, package.json, tsconfig.json)

Instructions

Step 1: Project Structure

my-plugin/
├── src/
│   ├── main.ts              # Plugin entry — thin orchestrator
│   ├── types.ts              # Shared interfaces and type definitions
│   ├── constants.ts          # Plugin-wide constants
│   ├── commands/
│   │   ├── index.ts          # Command registry
│   │   ├── insert-template.ts
│   │   └── toggle-sidebar.ts
│   ├── views/
│   │   ├── index.ts          # View registry
│   │   ├── sidebar-view.ts
│   │   └── modal-view.ts
│   ├── settings/
│   │   ├── settings.ts       # Settings interface and defaults
│   │   └── settings-tab.ts   # Settings UI tab
│   └── services/
│       ├── vault-service.ts  # File read/write/search operations
│       ├── metadata-service.ts  # Frontmatter and cache operations
│       └── sync-service.ts   # External sync or background tasks
├── styles.css
├── manifest.json
├── versions.json
├── package.json
├── tsconfig.json
└── esbuild.config.mjs

Step 2: Thin Main Entry Point

// src/main.ts — orchestrates, does not implement
import { Plugin } from 'obsidian';
import { MyPluginSettings, DEFAULT_SETTINGS } from './settings/settings';
import { MySettingTab } from './settings/settings-tab';
import { registerCommands } from './commands';
import { registerViews } from './views';
import { VaultService } from './services/vault-service';

export default class MyPlugin extends Plugin {
  settings: MyPluginSettings;
  vaultService: VaultService;

  async onload() {
    await this.loadSettings();
    this.vaultService = new VaultService(this.app);

    registerCommands(this);
    registerViews(this);
    this.addSettingTab(new MySettingTab(this.app, this));
  }

  onunload() {
    // Services clean up their own resources
    this.vaultService.destroy();
  }

  async loadSettings() {
    this.settings = Object.assign({}, DEFAULT_SETTINGS, await this.loadData());
  }

  async saveSettings() {
    await this.saveData(this.settings);
  }
}

Step 3: Command Registry Pattern

// src/commands/index.ts
import type MyPlugin from '../main';
import { insertTemplate } from './insert-template';
import { toggleSidebar } from './toggle-sidebar';

export function registerCommands(plugin: MyPlugin) {
  plugin.addCo

Obsidian SDK Patterns

Overview

Six production patterns that prevent the most common Obsidian plugin bugs: lost settings on upgrade, null-reference crashes on deleted files, memory leaks from unregistered events, stale metadata, and UI jank from rapid file changes. Each pattern is self-contained and copy-pasteable.

Prerequisites

• A working Obsidian plugin (see obsidian-core-workflow-a)
• TypeScript strict mode enabled ("strictNullChecks": true in tsconfig)
• Familiarity with Plugin.onload() / onunload() lifecycle

Instructions

Step 1: Typed settings with versioned migration

Settings break when you add or rename fields between releases. Version the settings object and migrate on load so existing users keep their data.

// src/settings.ts
interface PluginSettingsV1 {
  apiKey: string;
  interval: number;
}

interface PluginSettingsV2 {
  version: 2;
  apiKey: string;
  syncInterval: number;      // renamed from "interval"
  excludedFolders: string[]; // new field
  theme: "default" | "minimal";
}

// Current version is always the latest
type PluginSettings = PluginSettingsV2;

const DEFAULTS: PluginSettings = {
  version: 2,
  apiKey: "",
  syncInterval: 300,
  excludedFolders: [],
  theme: "default",
};

export async function loadSettings(plugin: Plugin): Promise<PluginSettings> {
  const raw = (await plugin.loadData()) as any;
  if (!raw) return { ...DEFAULTS };

  // Migrate v1 -> v2
  if (!raw.version || raw.version < 2) {
    raw.version = 2;
    if (raw.interval !== undefined) {
      raw.syncInterval = raw.interval;
      delete raw.interval;
    }
    raw.excludedFolders = raw.excludedFolders ?? [];
    raw.theme = raw.theme ?? "default";
    await plugin.saveData(raw);
  }

  // Merge with defaults to pick up any newly added fields
  return { ...DEFAULTS, ...raw };
}

Why: Object.assign({}, DEFAULTS, raw) handles new fields added in patch releases. The explicit migration block handles renames and type changes between major versions.

Step 2: Safe vault operations (check-before-act)

The Vault API throws if you create a file that exists or read one that was deleted between your check and your call. Wrap every operation.

// src/vault-helpers.ts
import { App, TFile, TFolder, TAbstractFile, normalizePath } from "obsidian";

export class VaultHelper {
  constructor(private app: App) {}

  /** Read file content, return null if file doesn't exist */
  async safeRead(path: string): Promise<string | null> {
    const file = this.app.vault.getAbstractFileByPath(normalizePath(path));
    if (!(file instanceof TFile)) return null;
    return this.app.vault.read(file);
  }

  /** Create or overwrite

Obsidian Security Basics

Overview

Security practices for Obsidian plugin development. Plugins run with full vault filesystem access and can make arbitrary network requests inside Electron. Responsible development requires protecting credentials, sanitizing external data, validating URI handlers, minimizing permissions, and following Obsidian's plugin guidelines to avoid community submission rejection.

Prerequisites

• Obsidian plugin development environment
• Understanding that .obsidian/plugins/<id>/data.json is synced by cloud services
• Awareness of Obsidian Plugin Guidelines

Instructions

Step 1: Credential Storage — Never in data.json

Plugin settings (data.json) live inside the vault and are synced by iCloud, Dropbox, Obsidian Sync, and Git. API keys stored here are effectively public.

// BAD: API key stored in plugin settings (synced to cloud, committed to Git)
interface BadSettings {
  apiKey: string; // This ends up in .obsidian/plugins/my-plugin/data.json
}

// GOOD: Use Electron's safeStorage for desktop (encrypted at OS level)
import { Platform } from 'obsidian';

export class SecureStorage {
  private plugin: Plugin;

  constructor(plugin: Plugin) { this.plugin = plugin; }

  async storeSecret(key: string, value: string): Promise<void> {
    if (Platform.isDesktopApp) {
      // Electron's safeStorage uses OS keychain (Keychain on macOS, DPAPI on Windows)
      const { safeStorage } = require('electron').remote || require('@electron/remote');
      if (safeStorage.isEncryptionAvailable()) {
        const encrypted = safeStorage.encryptString(value);
        const data = await this.plugin.loadData() ?? {};
        data[`_encrypted_${key}`] = encrypted.toString('base64');
        await this.plugin.saveData(data);
        return;
      }
    }
    // Fallback for mobile or when encryption unavailable: prompt each session
    // Store only in memory — never persisted
    this.memoryStore.set(key, value);
  }

  async getSecret(key: string): Promise<string | null> {
    if (Platform.isDesktopApp) {
      const { safeStorage } = require('electron').remote || require('@electron/remote');
      const data = await this.plugin.loadData();
      const encrypted = data?.[`_encrypted_${key}`];
      if (encrypted && safeStorage.isEncryptionAvailable()) {
        return safeStorage.decryptString(Buffer.from(encrypted, 'base64'));
      }
    }
    return this.memoryStore.get(key) ?? null;
  }

  private memoryStore = new Map<string, string>();
}

// Alternative: prompt user each session (simplest, most secure)
async onload() {
  if (!this.apiKey) {
    this.apiKey = await this.promptForApiKey();
  }
}

Step 2: In

Obsidian Webhooks & Events

Overview

Complete guide to Obsidian's event system: vault events (create, modify, delete, rename), workspace events (layout, leaf changes, editor state), metadataCache events, DOM events, custom EventRef patterns, and periodic tasks. Every event registration uses this.registerEvent() for automatic cleanup on plugin unload.

Prerequisites

• Working Obsidian plugin with onload() / onunload() lifecycle
• Understanding of TypeScript event handler signatures
• Familiarity with Obsidian's TFile, TFolder, and WorkspaceLeaf types

Instructions

Step 1: Vault Events — File Lifecycle

Vault events fire when files and folders are created, modified, deleted, or renamed.

import { Plugin, TFile, TFolder, TAbstractFile } from 'obsidian';

export default class EventPlugin extends Plugin {
  async onload() {
    // File created
    this.registerEvent(
      this.app.vault.on('create', (file: TAbstractFile) => {
        if (file instanceof TFile) {
          console.log('New file:', file.path);
          this.onFileCreated(file);
        }
        if (file instanceof TFolder) {
          console.log('New folder:', file.path);
        }
      })
    );

    // File content modified (fires on save and on every sync update)
    this.registerEvent(
      this.app.vault.on('modify', (file: TAbstractFile) => {
        if (file instanceof TFile) {
          this.onFileModified(file);
        }
      })
    );

    // File deleted
    this.registerEvent(
      this.app.vault.on('delete', (file: TAbstractFile) => {
        if (file instanceof TFile) {
          this.removeFromIndex(file.path);
        }
      })
    );

    // File renamed or moved (includes folder moves)
    this.registerEvent(
      this.app.vault.on('rename', (file: TAbstractFile, oldPath: string) => {
        if (file instanceof TFile) {
          this.updatePathReferences(oldPath, file.path);
        }
      })
    );
  }
}

Note: modify fires on every keystroke during live editing in some configurations. Always debounce if your handler does non-trivial work (see obsidian-rate-limits).

Step 2: Workspace Events — UI State Changes

Workspace events track what the user is looking at and how the UI layout changes.

async onload() {
  // Active file changed (user clicked a different tab/pane)
  this.registerEvent(
    this.app.workspace.on('active-leaf-change', (leaf) => {
      if (leaf) {
        const view = leaf.view;
        if (view.getViewType() === 'markdown') {
          const file = (view as any).file as TFile;
          if (file) {
            this.onActiveFileChanged(file);
          }
        }
      }
    })
  );

  /