obsidian-observability

Obsidian Observability

Overview

Implement comprehensive logging, monitoring, and debugging capabilities for Obsidian plugins.

Prerequisites

• Working Obsidian plugin
• Understanding of Developer Tools
• Basic TypeScript knowledge

Observability Components

Key Metrics

Metric	Type	Purpose
Command execution time	Timer	Performance
File operations count	Counter	Usage patterns
Error rate	Counter	Reliability
Cache hit ratio	Gauge	Efficiency
Memory usage	Gauge	Resource health

Instructions

Step 1: Structured Logger

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

interface LogEntry {
  timestamp: string;
  level: LogLevel;
  message: string;
  context?: Record<string, any>;
  duration?: number;
}

export class Logger {
  private pluginId: string;
  private level: LogLevel;
  private history: LogEntry[] = [];
  private maxHistory: number = 100;

  private readonly levelPriority: Record<LogLevel, number> = {
    debug: 0,
    info: 1,
    warn: 2,
    error: 3,
  };

  constructor(pluginId: string, level: LogLevel = 'info') {
    this.pluginId = pluginId;
    this.level = level;
  }

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

  private shouldLog(level: LogLevel): boolean {
    return this.levelPriority[level] >= this.levelPriority[this.level];
  }

  private formatMessage(entry: LogEntry): string {
    const prefix = `[${this.pluginId}]`;
    const time = entry.timestamp.split('T')[1].split('.')[0];
    const level = entry.level.toUpperCase().padEnd(5);

    let message = `${prefix} ${time} ${level} ${entry.message}`;

    if (entry.duration !== undefined) {
      message += ` (${entry.duration.toFixed(2)}ms)`;
    }

    return message;
  }

  private log(level: LogLevel, message: string, context?: Record<string, any>): void {
    if (!this.shouldLog(level)) return;

    const entry: LogEntry = {
      timestamp: new Date().toISOString(),
      level,
      message,
      context,
    };

    // Store in history
    this.history.push(entry);
    if (this.history.length > this.maxHistory) {
      this.history.shift();
    }

    // Console output
    const formatted = this.formatMessage(entry);
    const consoleMethod = level === 'debug' ? 'log' : level;

    if (context) {
      console[consoleMethod](formatted, context);
    } else {
      console[consoleMethod](formatted);
    }
  }

  debug(message: string, context?: Record<string, any>): void {
    this.log('debug', message, context);
  }

  info(message: string, context?: Record<string, any>): void {
    this.log('info', message, context);
  }

  warn(message: string, context?: Record<string, any>): void {
    this.log('warn', message, context);
  }

  error(message: string, error?: Error, context?: Record<string, any>): void {
    const errorContext = error ? {
      ...context,
      error: {
        name: error.name,
        message: error.message,
        stack: error.stack,
      },
    } : context;

    this.log('error', message, errorContext);
  }

  // Timing helper
  time(label: string): () => void {
    const start = performance.now();
    return () => {
      const duration = performance.now() - start;
      const entry: LogEntry = {
        timestamp: new Date().toISOString(),
        level: 'debug',
        message: label,
        duration,
      };

      if (this.shouldLog('debug')) {
        console.log(this.formatMessage(entry));
      }

      this.history.push(entry);
    };
  }

  // Get log history for debugging
  getHistory(): LogEntry[] {
    return [...this.history];
  }

  // Export logs for support
  exportLogs(): string {
    return this.history.map(entry => {
      let line = `${entry.timestamp} [${entry.level}] ${entry.message}`;
      if (entry.duration) line += ` (${entry.duration}ms)`;
      if (entry.context) line += `\n  ${JSON.stringify(entry.context)}`;
      return line;
    }).join('\n');
  }
}

Step 2: Metrics Collector

// src/utils/metrics.ts
interface MetricValue {
  value: number;
  timestamp: number;
}

export class MetricsCollector {
  private counters = new Map<string, number>();
  private gauges = new Map<string, number>();
  private timers = new Map<string, MetricValue[]>();
  private maxTimerHistory = 100;

  // Counter operations
  increment(name: string, value: number = 1): void {
    const current = this.counters.get(name) || 0;
    this.counters.set(name, current + value);
  }

  getCounter(name: string): number {
    return this.counters.get(name) || 0;
  }

  // Gauge operations
  setGauge(name: string, value: number): void {
    this.gauges.set(name, value);
  }

  getGauge(name: string): number {
    return this.gauges.get(name) || 0;
  }

  // Timer operations
  recordTiming(name: string, durationMs: number): void {
    const timings = this.timers.get(name) || [];
    timings.push({ value: durationMs, timestamp: Date.now() });

    // Keep only recent timings
    while (timings.length > this.maxTimerHistory) {
      timings.shift();
    }

    this.timers.set(name, timings);
  }

  getTimerStats(name: string): {
    count: number;
    avg: number;
    min: number;
    max: number;
    p95: number;
  } | null {
    const timings = this.timers.get(name);
    if (!timings || timings.length === 0) return null;

    const values = timings.map(t => t.value).sort((a, b) => a - b);
    const sum = values.reduce((a, b) => a + b, 0);

    return {
      count: values.length,
      avg: sum / values.length,
      min: values[0],
      max: values[values.length - 1],
      p95: values[Math.floor(values.length * 0.95)],
    };
  }

  // Time a function
  async timeAsync<T>(name: string, fn: () => Promise<T>): Promise<T> {
    const start = performance.now();
    try {
      return await fn();
    } finally {
      this.recordTiming(name, performance.now() - start);
    }
  }

  timeSync<T>(name: string, fn: () => T): T {
    const start = performance.now();
    try {
      return fn();
    } finally {
      this.recordTiming(name, performance.now() - start);
    }
  }

  // Get all metrics
  getAllMetrics(): {
    counters: Record<string, number>;
    gauges: Record<string, number>;
    timers: Record<string, ReturnType<typeof this.getTimerStats>>;
  } {
    const timerStats: Record<string, ReturnType<typeof this.getTimerStats>> = {};
    for (const name of this.timers.keys()) {
      timerStats[name] = this.getTimerStats(name);
    }

    return {
      counters: Object.fromEntries(this.counters),
      gauges: Object.fromEntries(this.gauges),
      timers: timerStats,
    };
  }

  // Reset all metrics
  reset(): void {
    this.counters.clear();
    this.gauges.clear();
    this.timers.clear();
  }
}

Step 3: Error Tracking

// src/utils/error-tracker.ts
interface TrackedError {
  timestamp: string;
  error: {
    name: string;
    message: string;
    stack?: string;
  };
  context: Record<string, any>;
  count: number;
}

export class ErrorTracker {
  private errors = new Map<string, TrackedError>();
  private maxErrors = 50;

  track(error: Error, context: Record<string, any> = {}): void {
    const key = `${error.name}:${error.message}`;
    const existing = this.errors.get(key);

    if (existing) {
      existing.count++;
      existing.timestamp = new Date().toISOString();
      existing.context = { ...existing.context, ...context };
    } else {
      // Enforce max errors limit
      if (this.errors.size >= this.maxErrors) {
        const oldestKey = this.errors.keys().next().value;
        this.errors.delete(oldestKey);
      }

      this.errors.set(key, {
        timestamp: new Date().toISOString(),
        error: {
          name: error.name,
          message: error.message,
          stack: error.stack,
        },
        context,
        count: 1,
      });
    }
  }

  getErrors(): TrackedError[] {
    return Array.from(this.errors.values())
      .sort((a, b) => b.count - a.count);
  }

  getMostCommon(limit: number = 5): TrackedError[] {
    return this.getErrors().slice(0, limit);
  }

  clear(): void {
    this.errors.clear();
  }

  // Safe wrapper for async functions
  wrapAsync<T>(
    fn: () => Promise<T>,
    context: Record<string, any> = {}
  ): Promise<T> {
    return fn().catch((error: Error) => {
      this.track(error, context);
      throw error;
    });
  }

  // Export for debugging
  export(): string {
    return JSON.stringify(this.getErrors(), null, 2);
  }
}

Step 4: Debug Panel View

// src/ui/views/debug-view.ts
import { ItemView, WorkspaceLeaf } from 'obsidian';
import type MyPlugin from '../../main';

export const DEBUG_VIEW_TYPE = 'plugin-debug-view';

export class DebugView extends ItemView {
  private plugin: MyPlugin;
  private refreshInterval: number;

  constructor(leaf: WorkspaceLeaf, plugin: MyPlugin) {
    super(leaf);
    this.plugin = plugin;
  }

  getViewType(): string {
    return DEBUG_VIEW_TYPE;
  }

  getDisplayText(): string {
    return 'Plugin Debug';
  }

  getIcon(): string {
    return 'bug';
  }

  async onOpen() {
    const container = this.containerEl.children[1];
    container.empty();
    container.addClass('plugin-debug-view');

    this.render(container);

    // Auto-refresh every 5 seconds
    this.refreshInterval = window.setInterval(() => {
      this.render(container);
    }, 5000);

    this.registerInterval(this.refreshInterval);
  }

  private render(container: Element) {
    container.empty();

    // Metrics section
    container.createEl('h3', { text: 'Metrics' });
    const metricsDiv = container.createDiv({ cls: 'debug-section' });
    this.renderMetrics(metricsDiv);

    // Errors section
    container.createEl('h3', { text: 'Recent Errors' });
    const errorsDiv = container.createDiv({ cls: 'debug-section' });
    this.renderErrors(errorsDiv);

    // Logs section
    container.createEl('h3', { text: 'Re

---

*Content truncated.*