@moonwatch/js 0.1.10 → 0.1.12

package/README.md

@@ -1,206 +1,190 @@
-# Moonwatch SDK
-
-A lightweight logging SDK that sends structured logs to a Moonwatch backend via HTTP or WebSocket, while echoing to the local console.
-
-## Quick Start
-
-```ts
-import { createLogger } from '@moonwatch/js';
-
-const logger = createLogger({
-  logId: 'your-log-file-id',
-  apiKey: 'your-api-key',
-});
-
-logger.info("server started", { port: 3000 });
-logger.warn("slow query", { duration: 1200, query: "SELECT ..." });
-logger.error("payment failed", { orderId: "abc-123" });
-```
-
-## Configuration
-
-```ts
-const logger = createLogger({
-  // Required
-  logId: 'uuid',             // Log file ID from the dashboard
-  apiKey: 'your-api-key',    // API key for ingestion auth
-
-  // Optional
-  group: 'api',              // Default group for all entries
-  traceId: 'req-123',        // Default trace ID
-  silent: false,             // Set true to suppress console output (default: false)
-  level: 'DEBUG',            // Only send logs at this level and above (default: 'DEBUG')
-  onError: (err, logs) => {  // Custom error handler for flush failures
-    // handle error
-  },
-});
-```
-
-### `level` option
-
-Controls which logs are sent to the remote service. Defaults to `'DEBUG'` (send everything). Logs below this level are silently dropped — they won't be sent remotely or printed to the console.
-
-This is useful when you want full remote logging in production but don't need to send every debug log during local development where you're already watching the console:
-
-```ts
-const logger = createLogger({
-  logId: 'your-log-file-id',
-  apiKey: 'your-api-key',
-  level: process.env.NODE_ENV === 'production' ? 'DEBUG' : 'ERROR',
-});
-```
-
-In this setup, local dev only sends errors remotely (you're already seeing everything in your terminal), while production captures the full picture for dashboard viewing and LLM analysis.
-
-### `silent` option
-
-By default, every `logger.*` call also prints to the local console so developers don't lose visibility when replacing `console.log` with `logger.info`. Set `silent: true` in production to disable this.
-
-## Log Methods
-
-Every level supports two call styles:
-
-### Simple form — message + optional metadata
-
-```ts
-logger.debug("cache miss", { key: "user:42" });
-logger.info("request handled", { method: "GET", path: "/api/users", ms: 12 });
-logger.warn("rate limit approaching", { current: 95, max: 100 });
-logger.error("query failed", { table: "orders" });
-logger.fatal("database unreachable");
-```
-
-The second argument is a plain metadata object. It can contain nested objects and arrays — the SDK sends it as-is.
-
-### Object form — for per-call group or trace ID
-
-```ts
-logger.info({
-  message: "user signed in",
-  group: "auth",
-  traceId: "req-abc",
-  metadata: { userId: 123, method: "oauth" },
-});
-```
-
-Use this when you need to override `group` or `traceId` on a single call without changing the logger's defaults.
-
-## Error Logging
-
-`error()` and `fatal()` accept Error objects directly — the SDK extracts the message, stack trace, and error type automatically:
-
-```ts
-try {
-  await processPayment(order);
-} catch (err) {
-  logger.error(err as Error, { orderId: order.id });
-}
-```
-
-This populates the `stack` and `error_type` columns in ClickHouse so stack traces and exception class names are stored as structured fields, not mashed into the message.
-
-## Scoped Loggers
-
-### Group Logger
-
-```ts
-const authLogger = logger.withGroup("auth");
-authLogger.info("login attempt", { email: "user@example.com" });
-// → group: "auth"
-```
-
-### Trace Logger
-
-```ts
-const reqLogger = logger.withTraceId("req-abc-123");
-reqLogger.info("handling request");
-reqLogger.warn("slow downstream call", { service: "billing", ms: 800 });
-// → trace_id: "req-abc-123" on both entries
-```
-
-### Mutating defaults
-
-```ts
-// Set for all subsequent calls
-logger.setGroup("worker");
-logger.setTraceId("job-456");
-
-// Clear
-logger.setGroup(undefined);
-logger.setTraceId(undefined);
-```
-
-## Console Interception
-
-Capture existing `console.*` calls without changing application code:
-
-```ts
-logger.interceptConsole();       // uses group "console"
-logger.interceptConsole("app");  // uses custom group
-
-// Later, to restore original console behavior:
-logger.restoreConsole();
-```
-
-This wraps `console.debug`, `console.log`, `console.info`, and `console.warn`. Errors are captured via `window.addEventListener('error')` and `unhandledrejection` listeners instead of wrapping `console.error`, to avoid polluting stack traces in frameworks like Next.js/React.
-
-## Source Map Support (Vite)
-
-Automatically resolve minified production stack traces back to original source. The Vite plugin uploads source maps at build time, and the ingestion service resolves stack traces before storing them.
-
-```ts
-// vite.config.ts
-import moonwatchPlugin from '@moonwatch/js/vite';
-
-export default defineConfig({
-  plugins: [
-    moonwatchPlugin({
-      apiKey: process.env.MOONWATCH_API_KEY!,
-      logFileId: 'your-log-file-id',
-    }),
-  ],
-  build: { sourcemap: true },
-});
-```
-
-The plugin:
-- **Skips in dev mode** — stacks are already readable
-- **Generates a release UUID** per build, injected as `__MOONWATCH_RELEASE__`
-- **Uploads `.map` files** from the build output to the ingestion service on `closeBundle`
-- **Multi-bundle (Electron):** All plugin instances in the same Node process share one release ID, so main + renderer maps are grouped under the same release
-
-No SDK configuration needed — the SDK automatically detects `__MOONWATCH_RELEASE__` and attaches it to every log entry.
-
-## AI Assistant Integration
-
-Run the init command to configure your AI coding assistant (Claude Code, Cursor, etc.) to use the SDK:
-
-```bash
-npx @moonwatch/js init
-```
-
-This adds a reference to the SDK's workflow guide in your `CLAUDE.md` and `.cursorrules`. Once configured, your AI assistant will know how to place logs using the SDK and query them via MCP — no copy-pasting logs needed.
-
-To set up manually, add this line to your `CLAUDE.md`:
-
-```md
-> See node_modules/@moonwatch/js/SKILL.md for the @moonwatch/js logging workflow.
-```
-
-## MCP Server (AI Log Analysis)
-
-Moonwatch includes an MCP server that lets AI assistants query your logs directly.
-
-### Add
-
-```bash
-claude mcp add --transport http moonwatch https://moonwatch.dev/mcp --header "Authorization: Bearer YOUR_API_KEY"
-```
-
-### Remove
-
-```bash
-claude mcp remove moonwatch
-```
-
-> **Note:** The `--transport http` flag is required — without it, `claude` defaults to stdio transport which won't work with a remote server.
+# Moonwatch SDK
+
+A lightweight logging SDK that sends structured logs to a Moonwatch backend via HTTP or WebSocket, while echoing to the local console.
+
+## Quick Start
+
+```ts
+import { createLogger } from '@moonwatch/js';
+
+const logger = createLogger({
+  logId: 'your-log-file-id',
+  apiKey: 'your-api-key',
+});
+
+logger.info("server started", { port: 3000 });
+logger.warn("slow query", { duration: 1200, query: "SELECT ..." });
+logger.error("payment failed", { orderId: "abc-123" });
+```
+
+## Configuration
+
+```ts
+const logger = createLogger({
+  // Required
+  logId: 'uuid',             // Log file ID from the dashboard
+  apiKey: 'your-api-key',    // API key for ingestion auth
+
+  // Optional
+  group: 'api',              // Default group for all entries
+  traceId: 'req-123',        // Default trace ID
+  silent: false,             // Set true to suppress console output (default: false)
+  level: 'DEBUG',            // Only send logs at this level and above (default: 'DEBUG')
+  onError: (err, logs) => {  // Custom error handler for flush failures
+    // handle error
+  },
+});
+```
+
+### `level` option
+
+Controls which logs are sent to the remote service. Defaults to `'DEBUG'` (send everything). Logs below this level are silently dropped — they won't be sent remotely or printed to the console.
+
+This is useful when you want full remote logging in production but don't need to send every debug log during local development where you're already watching the console:
+
+```ts
+const logger = createLogger({
+  logId: 'your-log-file-id',
+  apiKey: 'your-api-key',
+  level: process.env.NODE_ENV === 'production' ? 'DEBUG' : 'ERROR',
+});
+```
+
+In this setup, local dev only sends errors remotely (you're already seeing everything in your terminal), while production captures the full picture for dashboard viewing and LLM analysis.
+
+### `silent` option
+
+By default, every `logger.*` call also prints to the local console so developers don't lose visibility when replacing `console.log` with `logger.info`. Set `silent: true` in production to disable this.
+
+## Log Methods
+
+Every level supports two call styles:
+
+### Simple form — message + optional metadata
+
+```ts
+logger.debug("cache miss", { key: "user:42" });
+logger.info("request handled", { method: "GET", path: "/api/users", ms: 12 });
+logger.warn("rate limit approaching", { current: 95, max: 100 });
+logger.error("query failed", { table: "orders" });
+logger.fatal("database unreachable");
+```
+
+The second argument is a plain metadata object. It can contain nested objects and arrays — the SDK sends it as-is.
+
+### Object form — for per-call group or trace ID
+
+```ts
+logger.info({
+  message: "user signed in",
+  group: "auth",
+  traceId: "req-abc",
+  metadata: { userId: 123, method: "oauth" },
+});
+```
+
+Use this when you need to override `group` or `traceId` on a single call without changing the logger's defaults.
+
+## Error Logging
+
+`error()` and `fatal()` accept Error objects directly — the SDK extracts the message, stack trace, and error type automatically:
+
+```ts
+try {
+  await processPayment(order);
+} catch (err) {
+  logger.error(err as Error, { orderId: order.id });
+}
+```
+
+This populates the `stack` and `error_type` columns in ClickHouse so stack traces and exception class names are stored as structured fields, not mashed into the message.
+
+## Scoped Loggers
+
+### Group Logger
+
+```ts
+const authLogger = logger.withGroup("auth");
+authLogger.info("login attempt", { email: "user@example.com" });
+// → group: "auth"
+```
+
+### Trace Logger
+
+```ts
+const reqLogger = logger.withTraceId("req-abc-123");
+reqLogger.info("handling request");
+reqLogger.warn("slow downstream call", { service: "billing", ms: 800 });
+// → trace_id: "req-abc-123" on both entries
+```
+
+### Mutating defaults
+
+```ts
+// Set for all subsequent calls
+logger.setGroup("worker");
+logger.setTraceId("job-456");
+
+// Clear
+logger.setGroup(undefined);
+logger.setTraceId(undefined);
+```
+
+## Console Interception
+
+Capture existing `console.*` calls without changing application code:
+
+```ts
+logger.interceptConsole();       // uses group "console"
+logger.interceptConsole("app");  // uses custom group
+
+// Later, to restore original console behavior:
+logger.restoreConsole();
+```
+
+This wraps `console.debug`, `console.log`, `console.info`, and `console.warn`. Errors are captured via `window.addEventListener('error')` and `unhandledrejection` listeners instead of wrapping `console.error`, to avoid polluting stack traces in frameworks like Next.js/React.
+
+## Source Map Support (Vite)
+
+Automatically resolve minified production stack traces back to original source. The Vite plugin uploads source maps at build time, and the ingestion service resolves stack traces before storing them.
+
+```ts
+// vite.config.ts
+import moonwatchPlugin from '@moonwatch/js/vite';
+
+export default defineConfig({
+  plugins: [
+    moonwatchPlugin({
+      apiKey: process.env.MOONWATCH_API_KEY!,
+      logFileId: 'your-log-file-id',
+    }),
+  ],
+  build: { sourcemap: true },
+});
+```
+
+The plugin:
+- **Skips in dev mode** — stacks are already readable
+- **Generates a release UUID** per build, injected as `__MOONWATCH_RELEASE__`
+- **Uploads `.map` files** from the build output to the ingestion service on `closeBundle`
+- **Multi-bundle (Electron):** All plugin instances in the same Node process share one release ID, so main + renderer maps are grouped under the same release
+
+No SDK configuration needed — the SDK automatically detects `__MOONWATCH_RELEASE__` and attaches it to every log entry.
+
+## MCP Server (AI Log Analysis)
+
+Moonwatch includes an MCP server that lets AI assistants query your logs directly.
+
+### Add
+
+```bash
+claude mcp add --transport http moonwatch https://mcp.moonwatch.dev/mcp --header "Authorization: Bearer YOUR_API_KEY"
+```
+
+### Remove
+
+```bash
+claude mcp remove moonwatch
+```
+
+> **Note:** The `--transport http` flag is required — without it, `claude` defaults to stdio transport which won't work with a remote server.

package/dist/index.d.mts

@@ -60,6 +60,7 @@ declare class Logger {
     private wsReconnectTimer;
     private wsReconnectAttempts;
     private maxWsReconnectAttempts;
+    private traceIdProvider?;
     private _onVisibilityChange;
     private _onBeforeUnload;
     constructor(config: LoggerConfig);
@@ -87,6 +88,9 @@ declare class Logger {
     withGroup(group: string): ScopedLogger;
     withWatcher(watcherId: string): ScopedLogger;
     setTraceId(traceId: string | undefined): void;
+    /** Register a dynamic trace ID provider. Called on every log to resolve the current trace ID.
+     *  Useful with Node.js AsyncLocalStorage for per-request tracing in concurrent servers. */
+    setTraceIdProvider(fn: (() => string | undefined) | undefined): void;
     setGroup(group: string | undefined): void;
     interceptConsole(group?: string, options?: {
         wrapErrors?: boolean;

package/dist/index.d.ts

@@ -60,6 +60,7 @@ declare class Logger {
     private wsReconnectTimer;
     private wsReconnectAttempts;
     private maxWsReconnectAttempts;
+    private traceIdProvider?;
     private _onVisibilityChange;
     private _onBeforeUnload;
     constructor(config: LoggerConfig);
@@ -87,6 +88,9 @@ declare class Logger {
     withGroup(group: string): ScopedLogger;
     withWatcher(watcherId: string): ScopedLogger;
     setTraceId(traceId: string | undefined): void;
+    /** Register a dynamic trace ID provider. Called on every log to resolve the current trace ID.
+     *  Useful with Node.js AsyncLocalStorage for per-request tracing in concurrent servers. */
+    setTraceIdProvider(fn: (() => string | undefined) | undefined): void;
     setGroup(group: string | undefined): void;
     interceptConsole(group?: string, options?: {
         wrapErrors?: boolean;

package/dist/index.js

@@ -32,7 +32,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
-// ../node_modules/non-error/index.js
+// ../../node_modules/non-error/index.js
 var isNonErrorSymbol = /* @__PURE__ */ Symbol("isNonError");
 function defineProperty(object, key, value) {
   Object.defineProperty(object, key, {
@@ -144,7 +144,7 @@ handleCallback_fn = function(callback, arguments_) {
 __privateAdd(_NonError, _NonError_static);
 var NonError = _NonError;
 
-// ../node_modules/serialize-error/error-constructors.js
+// ../../node_modules/serialize-error/error-constructors.js
 var list = [
   // Native ES errors https://262.ecma-international.org/12.0/#sec-well-known-intrinsic-objects
   Error,
@@ -165,7 +165,7 @@ var list = [
 var errorConstructors = new Map(list);
 var errorFactories = /* @__PURE__ */ new Map();
 
-// ../node_modules/serialize-error/index.js
+// ../../node_modules/serialize-error/index.js
 var errorProperties = [
   {
     property: "name",
@@ -348,7 +348,7 @@ var LEVEL_ORDER = {
   FATAL: 4
 };
 var SDK_VERSION = "0.1.4";
-var DEFAULT_BASE_URL = "https://moonwatch.dev";
+var DEFAULT_BASE_URL = "https://ingest.moonwatch.dev";
 var BATCH_SIZE = 50;
 var MAX_BUFFER_SIZE = 1e3;
 var FLUSH_INTERVAL_MS = 1e3;
@@ -517,7 +517,7 @@ ${arg.stack}`;
       message,
       logId: this.config.logId,
       group: options?.group ?? this.config.group,
-      trace_id: options?.traceId ?? this.config.traceId,
+      trace_id: options?.traceId ?? this.traceIdProvider?.() ?? this.config.traceId,
       stack: options?.stack,
       error_type: options?.errorType,
       release_id: RELEASE_ID,
@@ -594,6 +594,11 @@ ${arg.stack}`;
   setTraceId(traceId) {
     this.config.traceId = traceId;
   }
+  /** Register a dynamic trace ID provider. Called on every log to resolve the current trace ID.
+   *  Useful with Node.js AsyncLocalStorage for per-request tracing in concurrent servers. */
+  setTraceIdProvider(fn) {
+    this.traceIdProvider = fn;
+  }
   setGroup(group) {
     this.config.group = group;
   }

package/dist/index.mjs

@@ -3,7 +3,7 @@ import {
   __privateMethod
 } from "./chunk-JKIIIVNW.mjs";
 
-// ../node_modules/non-error/index.js
+// ../../node_modules/non-error/index.js
 var isNonErrorSymbol = /* @__PURE__ */ Symbol("isNonError");
 function defineProperty(object, key, value) {
   Object.defineProperty(object, key, {
@@ -115,7 +115,7 @@ handleCallback_fn = function(callback, arguments_) {
 __privateAdd(_NonError, _NonError_static);
 var NonError = _NonError;
 
-// ../node_modules/serialize-error/error-constructors.js
+// ../../node_modules/serialize-error/error-constructors.js
 var list = [
   // Native ES errors https://262.ecma-international.org/12.0/#sec-well-known-intrinsic-objects
   Error,
@@ -136,7 +136,7 @@ var list = [
 var errorConstructors = new Map(list);
 var errorFactories = /* @__PURE__ */ new Map();
 
-// ../node_modules/serialize-error/index.js
+// ../../node_modules/serialize-error/index.js
 var errorProperties = [
   {
     property: "name",
@@ -319,7 +319,7 @@ var LEVEL_ORDER = {
   FATAL: 4
 };
 var SDK_VERSION = "0.1.4";
-var DEFAULT_BASE_URL = "https://moonwatch.dev";
+var DEFAULT_BASE_URL = "https://ingest.moonwatch.dev";
 var BATCH_SIZE = 50;
 var MAX_BUFFER_SIZE = 1e3;
 var FLUSH_INTERVAL_MS = 1e3;
@@ -488,7 +488,7 @@ ${arg.stack}`;
       message,
       logId: this.config.logId,
       group: options?.group ?? this.config.group,
-      trace_id: options?.traceId ?? this.config.traceId,
+      trace_id: options?.traceId ?? this.traceIdProvider?.() ?? this.config.traceId,
       stack: options?.stack,
       error_type: options?.errorType,
       release_id: RELEASE_ID,
@@ -565,6 +565,11 @@ ${arg.stack}`;
   setTraceId(traceId) {
     this.config.traceId = traceId;
   }
+  /** Register a dynamic trace ID provider. Called on every log to resolve the current trace ID.
+   *  Useful with Node.js AsyncLocalStorage for per-request tracing in concurrent servers. */
+  setTraceIdProvider(fn) {
+    this.traceIdProvider = fn;
+  }
   setGroup(group) {
     this.config.group = group;
   }

package/dist/vite.js

@@ -27,7 +27,7 @@ var import_crypto = require("crypto");
 var import_fs = require("fs");
 var import_path = require("path");
 var import_os = require("os");
-var DEFAULT_ENDPOINT = "https://moonwatch.dev";
+var DEFAULT_ENDPOINT = "https://ingest.moonwatch.dev";
 var RELEASE_FILE = (0, import_path.join)((0, import_os.tmpdir)(), ".moonwatch-release");
 var RELEASE_FILE_MAX_AGE_MS = 5 * 60 * 1e3;
 function collectMapFiles(dir) {

package/dist/vite.mjs

@@ -5,7 +5,7 @@ import { randomUUID } from "crypto";
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "fs";
 import { join, relative } from "path";
 import { tmpdir } from "os";
-var DEFAULT_ENDPOINT = "https://moonwatch.dev";
+var DEFAULT_ENDPOINT = "https://ingest.moonwatch.dev";
 var RELEASE_FILE = join(tmpdir(), ".moonwatch-release");
 var RELEASE_FILE_MAX_AGE_MS = 5 * 60 * 1e3;
 function collectMapFiles(dir) {

package/package.json

@@ -1,53 +1,49 @@
-{
-  "name": "@moonwatch/js",
-  "version": "0.1.10",
-  "description": "JavaScript SDK for Moonwatch",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "require": "./dist/index.js",
-      "import": "./dist/index.mjs"
-    },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "require": "./dist/vite.js",
-      "import": "./dist/vite.mjs"
-    }
-  },
-  "bin": {
-    "moonwatch-init": "dist/init.js"
-  },
-  "files": [
-    "dist",
-    "SKILL.md"
-  ],
-  "scripts": {
-    "build": "tsup src/index.ts src/vite.ts --format cjs,esm --dts && tsup src/init.ts --format cjs --no-dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "tsx test/test.ts"
-  },
-  "devDependencies": {
-    "serialize-error": "^13.0.1",
-    "tsup": "^8.0.0",
-    "tsx": "^4.7.0",
-    "typescript": "^5.3.0",
-    "vite": "^7.3.1"
-  },
-  "peerDependencies": {
-    "vite": ">=5.0.0"
-  },
-  "peerDependenciesMeta": {
-    "vite": {
-      "optional": true
-    }
-  },
-  "keywords": [
-    "logging",
-    "moonwatch",
-    "observability"
-  ],
-  "license": "MIT"
-}
+{
+  "name": "@moonwatch/js",
+  "version": "0.1.12",
+  "description": "JavaScript SDK for Moonwatch",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "require": "./dist/vite.js",
+      "import": "./dist/vite.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/vite.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "tsx test/test.ts"
+  },
+  "devDependencies": {
+    "serialize-error": "^13.0.1",
+    "tsup": "^8.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0",
+    "vite": "^7.3.1"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "logging",
+    "moonwatch",
+    "observability"
+  ],
+  "license": "MIT"
+}

package/SKILL.md

@@ -1,320 +0,0 @@
-# @moonwatch/js — AI Workflow Guide
-
-This project uses Moonwatch to give you persistent runtime insight. You can place log statements freely — they are sent to a central server and you can query them via MCP at any time. This means you don't need to ask the user to copy-paste logs. You place them, the user reproduces the issue, and you query the results yourself.
-
-## The Workflow
-
-1. **Create a watcher** via MCP (`watchers_create`) describing what you're investigating — you get back a UUID
-2. **Place logs liberally** using `logger.debug()` with the watcher ID attached — instrument every code path that could be relevant
-3. **Ask the user to reproduce** the issue (or wait for the next occurrence)
-4. **Query the logs via MCP** using `logs_query` with `WHERE watcher_id = '<uuid>'` — you see exactly the logs you placed, no noise
-5. **Record findings** via `watchers_update` — accumulate your analysis so you don't lose context across conversations
-6. **Iterate** — add more logs, query again, update findings
-7. **Resolve** — once fixed, mark the watcher as resolved via `watchers_update` with `status: "resolved"`
-
-You should default to placing logs early and liberally when investigating runtime issues. Don't spend multiple rounds guessing from static code alone — instrument the code, get the data, then fix the bug. Logs persist across runs, so once placed, they keep providing insight. Use `logger.debug()` freely — the watcher ID lets you filter to only your logs, so volume isn't a concern.
-
-**Be generous with logging.** When investigating an issue, don't just log the one line you suspect — log the inputs, the intermediate state, the branch taken, the output. Five `logger.debug()` calls is better than one if it saves a round-trip of "add more logs, reproduce again."
-
-**Cleanup rule:** Use `logger.debug()` for temporary diagnostic logs placed during investigation. Once the issue is resolved, remove all debug-level logs you added. Permanent logs that provide ongoing operational value (errors, warnings, key events) should use the appropriate level and can stay.
-
-## Watchers
-
-Watchers are your primary tool for structured investigations. Every time you start debugging a runtime issue, **create a watcher first**. This gives you a UUID that tags all your diagnostic logs, so you can query them in isolation.
-
-### Creating and Using a Watcher
-
-```
-1. watchers_create({ description: "Investigating why WebSocket reconnects fail after 5 attempts" })
-   → returns UUID: "a1b2c3d4-..."
-
-2. Place logs in code with that watcher ID:
-```
-
-```ts
-// Scoped logger — all logs from this get the watcher ID automatically
-const dbg = logger.withWatcher("a1b2c3d4-...");
-dbg.debug("ws reconnect attempt", { attempt: this.wsReconnectAttempts, delay });
-dbg.debug("ws state before connect", { state: this.wsState, hasSocket: !!this.ws });
-dbg.debug("ws onclose fired", { code: event.code, reason: event.reason });
-
-// Or inline for one-off logs
-logger.debug({ message: "auth header value", watcherId: "a1b2c3d4-...", metadata: { header } });
-```
-
-```
-3. User reproduces → query YOUR logs only:
-   logs_query({ query: "SELECT timestamp, message, metadata FROM logs.entries WHERE watcher_id = 'a1b2c3d4-...' ORDER BY timestamp" })
-
-4. Record what you learned AND report to the user:
-   watchers_update({ id: "a1b2c3d4-...", findings: "The reconnect fails because wsState is still 'connecting' when onclose fires — race condition between..." })
-   Always tell the user what you found — the watcher records findings for future sessions, but the user needs to hear it now.
-
-5. Fix the bug, verify, then resolve:
-   watchers_update({ id: "a1b2c3d4-...", status: "resolved", findings: "Fixed by checking wsState in onclose handler. Verified reconnect works after 5 attempts." })
-```
-
-### Watcher MCP Tools
-
-- **`watchers_create`** — Start an investigation. Always include a clear description.
-- **`watchers_list`** — See all your watchers and which have new data.
-- **`watchers_get`** — Read full details + findings. Resets the "new data" flag.
-- **`watchers_update`** — Record findings, change status, update description.
-
-### When to Create a Watcher
-
-- **Always** when investigating a runtime bug — even if you think it'll be quick
-- When monitoring a fix to verify it works in production
-- When you need to understand the flow through unfamiliar code at runtime
-- When correlating behavior across multiple components
-
-### Logging Generously with Watchers
-
-Because watcher IDs let you filter to only your logs, don't be stingy. For a typical investigation, you might place 5-15 `logger.debug()` calls across the relevant code path:
-
-```ts
-const dbg = logger.withWatcher("a1b2c3d4-...");
-
-// Log inputs
-dbg.debug("handleRequest called", { method, path, headers: Object.keys(headers) });
-
-// Log branch decisions
-dbg.debug("auth check result", { authenticated, userId, tokenExpiry });
-
-// Log intermediate state
-dbg.debug("query built", { sql: query.substring(0, 200), paramCount: params.length });
-
-// Log the thing you actually suspect
-dbg.debug("response timing", { dbMs, renderMs, totalMs });
-
-// Log the output
-dbg.debug("response sent", { status, bodyLength: body.length });
-```
-
-This is much more effective than placing one log and having to do multiple rounds of "add more logs, reproduce again."
-
-## Example: User Asks You to Analyze Logs
-
-When the user asks you to look into a problem visible in logs (e.g. "why are we getting 500s on the billing endpoint?"), follow this pattern:
-
-1. **Query the logs first** — use `logs_query` to understand the problem
-2. **Report your findings** to the user
-3. **Check for existing watchers** — call `watchers_list` to see if there's already a watcher tracking this issue
-4. **If a related watcher exists** — read it with `watchers_get`, append your new findings via `watchers_update`
-5. **If no watcher exists** — offer to create one:
-
-> "I found the issue — the billing endpoint is throwing a null reference when `subscription.plan` is missing. I can set up a watcher to track this. It'll place debug logs around the billing flow so we automatically capture the full context next time it happens. Want me to do that?"
-
-If the user agrees:
-- `watchers_create({ description: "Tracking null ref in billing endpoint when subscription.plan is missing", logFileId: "..." })`
-- Place `logger.debug()` calls with the watcher ID around the relevant code paths
-- The cron job will flag new matching logs automatically, so next time it happens you'll have full context
-
-**This matters because investigations span multiple conversations.** A watcher persists your findings and keeps collecting data between sessions. Without one, the next conversation starts from scratch. With one, you (or a future Claude) can call `watchers_list`, see there's an active watcher with findings, and pick up where you left off.
-
-### The full flow looks like:
-
-```
-User: "We're seeing intermittent 500s on POST /api/orders"
-
-You:
-  1. logs_query → find the errors, identify the pattern
-  2. Report: "These are timeout errors when the payment gateway takes >10s"
-  3. watchers_list → no existing watcher for this
-  4. Offer: "Want me to set up a watcher? I'll instrument the order flow
-     so we capture timing data automatically next time."
-
-User: "Yes"
-
-You:
-  5. watchers_create({ description: "Intermittent 500s on POST /api/orders — payment gateway timeouts >10s" })
-  6. Place debug logs:
-     - Before the gateway call (log request params, timestamp)
-     - After the gateway call (log response time, status)
-     - In the error handler (log the full error context)
-     - At the retry logic (log attempt count, backoff delay)
-  7. watchers_update({ findings: "Initial analysis: gateway timeouts when response >10s.
-     Placed debug logs in orderService.createOrder(), paymentGateway.charge(),
-     and the retry handler. Will have full timing data on next occurrence." })
-  8. Report back to user with what you placed and what to expect
-
---- later, in a new conversation ---
-
-User: "The 500s happened again"
-
-You:
-  1. watchers_list → see the active watcher with new_data = true
-  2. watchers_get → read previous findings
-  3. logs_query WHERE watcher_id = '...' → see the detailed debug logs
-  4. Now you have full context without starting over
-```
-
-## When to Place Logs
-
-- Debugging a runtime bug that isn't obvious from code alone
-- Investigating timing issues, race conditions, or intermittent failures
-- Understanding the flow through async code, event handlers, or callbacks
-- Correlating behavior across multiple services or processes (use `traceId`)
-- Monitoring a specific code path after a fix to verify it works
-
-## Best Practices
-
-**Use `withGroup()` to categorize logs — don't embed context in the message.**
-
-The `group` field is a queryable column in ClickHouse. When you prefix messages manually, you lose the ability to filter and aggregate by subsystem. Groups should reflect the domain/feature area using slash-separated paths, like a file system:
-
-```ts
-// Bad — context is buried in the message string, not queryable
-logger.info("[StorageService] Getting user");
-
-// Good — group is a structured, queryable field
-const log = logger.withGroup("storage");
-log.info("Getting user");
-
-// Also good — inline object form for one-off logs
-logger.info({ message: "Getting user", group: "storage" });
-```
-
-**Use hierarchical slash-separated groups** so you can filter at any level of granularity:
-
-```ts
-// Specific subsystem groups — lets you zoom in or out when querying
-logger.withGroup("api/billing").debug("charge initiated", { amount, customerId });
-logger.withGroup("api/billing/webhooks").debug("stripe event received", { type, eventId });
-logger.withGroup("api/orders").debug("order created", { orderId, items: items.length });
-logger.withGroup("api/orders/autodispatch").debug("driver assignment", { orderId, driverId, distance });
-logger.withGroup("ws/connections").debug("client connected", { clientId, protocol });
-logger.withGroup("auth/oauth").debug("token refresh", { userId, expiresIn });
-logger.withGroup("cron/cleanup").debug("retention sweep", { partitionsScanned, deleted });
-```
-
-This lets you query at different levels:
-```sql
--- Everything in the billing subsystem
-WHERE group LIKE 'api/billing%'
-
--- Just webhook processing
-WHERE group = 'api/billing/webhooks'
-
--- All API logs
-WHERE group LIKE 'api/%'
-
--- Log volume by subsystem
-SELECT group, count(*) FROM logs.entries GROUP BY group ORDER BY count() DESC
-```
-
-When placing logs across multiple files or modules during an investigation, create a scoped logger per module so logs are naturally organized. Combine `withGroup()` and `withWatcher()` for maximum queryability — the group tells you *where* in the system, the watcher tells you *which investigation*.
-
-```ts
-const dbg = logger.withWatcher("a1b2c3d4-...").withGroup("api/orders/autodispatch");
-dbg.debug("dispatch started", { orderId, availableDrivers: drivers.length });
-dbg.debug("driver scored", { driverId, score, distance, eta });
-dbg.debug("driver assigned", { orderId, driverId, dispatchMs: Date.now() - start });
-```
-
-Use `withTraceId()` to correlate logs across a single request or operation, especially across services.
-
-## SDK Quick Reference
-
-### Setup (already done if the project uses this SDK)
-
-**Important:** Look for an existing logger instance in the project before creating a new one. Projects typically have a shared logger in a file like `logger.ts` or `lib/logger.ts` — import from there instead of calling `createLogger()` again.
-
-```ts
-import { createLogger } from '@moonwatch/js';
-
-const logger = createLogger({
-  logId: 'uuid-from-dashboard',   // required — identifies the log stream
-  apiKey: 'rl_...',               // required — ingestion auth
-  group: 'api',                   // optional: default group for all entries
-  traceId: 'req-123',            // optional: default trace ID
-  level: 'DEBUG',                 // optional: minimum level (default: 'DEBUG')
-  silent: false,                  // optional: suppress console echo (default: false)
-});
-```
-
-### Logging
-
-```ts
-logger.debug("cache hit", { key: "user:42" });
-logger.info("request handled", { method: "GET", path: "/api/users", ms: 12 });
-logger.warn("slow query", { duration: 1200 });
-logger.error(err as Error, { orderId: order.id });  // Error objects extract stack + error_type
-logger.fatal(new Error("database unreachable"));
-```
-
-### Console Interception
-
-```ts
-logger.interceptConsole();        // captures console.debug/log/info/warn + unhandled errors
-logger.interceptConsole("app");   // with a custom group name
-logger.restoreConsole();          // undo
-```
-
-Use this to capture logs from third-party code or existing console.log statements without modifying them.
-
-## Reading Logs via MCP
-
-You have two MCP tools available:
-
-- **`logs_list_log_files`** — Lists all log files with data. Call this first to find the log file ID.
-- **`logs_query`** — Execute SQL (ClickHouse) against a log file. Tenant/log filtering is automatic.
-
-### Common Queries
-
-```sql
--- Recent errors
-SELECT timestamp, level, message, stack FROM logs.entries WHERE level = 'ERROR' ORDER BY timestamp DESC LIMIT 20
-
--- Errors by type
-SELECT error_type, count(*) as cnt FROM logs.entries WHERE error_type IS NOT NULL GROUP BY error_type ORDER BY cnt DESC
-
--- Search for a specific message pattern
-SELECT timestamp, level, group, message FROM logs.entries WHERE message LIKE '%ECONNREFUSED%' ORDER BY timestamp DESC LIMIT 20
-
--- Error rate over time
-SELECT toStartOfMinute(timestamp) as minute, count(*) FROM logs.entries WHERE level = 'ERROR' GROUP BY minute ORDER BY minute
-
--- Logs by group
-SELECT group, count(*) FROM logs.entries GROUP BY group ORDER BY count() DESC
-
--- Trace a specific request across services
-SELECT timestamp, group, level, message FROM logs.entries WHERE trace_id = 'req-abc-123' ORDER BY timestamp
-
--- Recent logs from a specific group
-SELECT timestamp, level, message FROM logs.entries WHERE group = 'auth' ORDER BY timestamp DESC LIMIT 50
-
--- Error with source context (see the original code around the error)
-SELECT timestamp, message, stack, source_context FROM logs.entries WHERE level = 'ERROR' AND source_context IS NOT NULL ORDER BY timestamp DESC LIMIT 5
-
--- All logs for a watcher investigation
-SELECT timestamp, message, metadata FROM logs.entries WHERE watcher_id = 'a1b2c3d4-...' ORDER BY timestamp
-
--- Watcher logs filtered by time window
-SELECT timestamp, message, metadata FROM logs.entries WHERE watcher_id = 'a1b2c3d4-...' AND timestamp >= '2026-02-16 10:00:00' ORDER BY timestamp
-```
-
-**Tip:** When investigating production errors, include `source_context` in your SELECT. It contains the original source code around the error line (resolved from source maps at ingestion time), so you can see exactly what code triggered the error without needing to open the file.
-
-### Table Schema
-
-```
-seq UInt64              -- sequence number
-timestamp DateTime64(3) -- e.g., '2025-01-22 14:30:00.123'
-level String            -- DEBUG, INFO, WARN, ERROR, FATAL
-trace_id String         -- request correlation
-group String            -- categorization (e.g., 'api/billing', 'main', 'renderer')
-message String          -- log content
-stack Nullable(String)  -- stack trace (resolved via source maps if available)
-error_type String       -- exception class name
-release_id String       -- build release ID (for source map resolution)
-source_context String   -- JSON: { file, line, code: { "lineNum": "source line" } } — original source around the error
-watcher_id String       -- watcher UUID (empty string if not tagged)
-metadata JSON           -- arbitrary structured data
-```
-
-## Do NOT
-
-- Do not pass `batchSize`, `flushInterval`, `httpEndpoint`, `wsEndpoint`, or `transport` — these do not exist.
-- Do not call `errorWithStack()` — it does not exist. Use `logger.error(err)` instead.
-- Do not call `logger.shutdown()` unless explicitly tearing down the logger mid-process. It is not required.