observability

# Observability

Production-grade logging, metrics, and debugging patterns using @side-quest/core/logging (LogTape + JSONL).

## Quick Navigation

- **[Core Concepts](#core-concepts)** - Correlation IDs, subsystem loggers, JSONL output
- **[Plugin Logger Setup](#plugin-logger-setup)** - Factory pattern, hierarchical categories
- **[Log Levels & Best Practices](#log-levels--best-practices)** - When to use DEBUG/INFO/WARN/ERROR
- **[Correlation ID Patterns](#correlation-id-patterns)** - Request tracing, operation tracking
- **[Performance Metrics](#performance-metrics)** - Automatic aggregation, session summaries
- **[Debugging Workflows](#debugging-workflows)** - grep patterns, jq queries, troubleshooting
- **[Testing](#testing)** - Log assertions, metrics validation
- **[Common Patterns](#common-patterns)** - Real-world examples
- **[Related Skills](#related-skills)** - Bun CLI, Bun Runtime

---

## Core Concepts

### Structured Logging with LogTape

**Why LogTape:** JSONL format enables programmatic analysis, grep filtering, and long-term storage.

**Log Location:** `~/.claude/logs/<plugin-name>.jsonl`

**Key Features:**
- JSONL (newline-delimited JSON) for machine parsing
- File rotation (1 MiB default, keeps 5 files)
- Hierarchical categories (plugin → subsystem)
- Tagged template literals for clean syntax
- Automatic timestamp, level, logger metadata

### Hierarchical Categories

```typescript
// Category hierarchy: [plugin, subsystem, ...submodule]
["para-obsidian"]                    // Root plugin logger
["para-obsidian", "inbox"]           // Inbox subsystem
["para-obsidian", "inbox", "pdf"]    // PDF submodule (if needed)

// Enables grep filtering:
// grep '"logger":"para-obsidian.inbox"' ~/.claude/logs/para-obsidian.jsonl
```

**Benefits:**
- Filter logs by subsystem
- Different log levels per category
- Trace operations across subsystems

### Correlation IDs

**Purpose:** Link related log entries across subsystems for request tracing.

```typescript
impo