observability-toolkit 1.1.0 → 1.4.0

package/README.md

@@ -21,10 +21,11 @@ claude mcp add observability-toolkit -- node ~/.claude/mcp-servers/observability
 | `obs_query_traces` | Query traces from local JSONL or SigNoz |
 | `obs_query_metrics` | Query metrics with aggregation support |
 | `obs_query_logs` | Query logs by severity, search text, trace ID |
+| `obs_query_llm_events` | Query LLM events with token usage and duration metrics |
 | `obs_health_check` | Check telemetry system health |
 | `obs_context_stats` | Get context window utilization stats |
 | `obs_get_trace_url` | Get SigNoz trace viewer URL (requires SigNoz) |
-| `obs_setup_claudeignore` | Add telemetry/ to .claudeignore |
+| `obs_setup_claudeignore` | Add entries to .claudeignore (telemetry, test files, coverage) |
 
 ## Configuration
 
@@ -44,8 +45,26 @@ The server works standalone with local JSONL files. SigNoz integration is option
 obs_query_traces({ backend: "local", limit: 10 })
 obs_query_traces({ traceId: "abc123..." })
 obs_query_traces({ serviceName: "claude-code", minDurationMs: 100 })
+obs_query_traces({ attributeFilter: { "agent.source_type": "lazy" } })
 ```
 
+### Filterable Attributes
+
+Use `attributeFilter` to query by span attributes:
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `agent.type` | string | Agent name (e.g., "Explore", "auto-error-resolver") |
+| `agent.source_type` | `active`, `lazy`, `builtin`, `settings` | Where agent is defined |
+| `agent.category` | string | Agent category (e.g., "error-handling", "code") |
+| `plugin.name` | string | Skill/plugin name |
+| `plugin.source_type` | `active`, `lazy`, `settings` | Where skill is defined |
+| `plugin.category` | string | Skill category |
+| `mcp.server` | string | MCP server name |
+| `mcp.tool` | string | MCP tool name |
+| `builtin.tool` | string | Built-in tool name (Read, Write, Bash, etc.) |
+| `hook.type` | `agent`, `plugin`, `mcp`, `builtin` | Hook handler type |
+
 ### Query logs
 
 ```
@@ -61,6 +80,14 @@ obs_query_metrics({ metricName: "session.context.size" })
 obs_query_metrics({ metricName: "gen_ai.client.token.usage", aggregation: "sum" })
 ```
 
+### Query LLM events
+
+```
+obs_query_llm_events({})
+obs_query_llm_events({ model: "claude-opus-4-5", limit: 10 })
+obs_query_llm_events({ provider: "anthropic", startDate: "2026-01-28" })
+```
+
 ### Health check
 
 ```
@@ -85,17 +112,31 @@ obs_get_trace_url({ traceId: "abc123..." })
 ```
 obs_setup_claudeignore({})
 obs_setup_claudeignore({ dryRun: true })
-obs_setup_claudeignore({ entry: "telemetry/", path: "/path/to/.claudeignore" })
+obs_setup_claudeignore({ includeDefaults: false, entry: "custom/" })
+obs_setup_claudeignore({ entries: ["logs/", "tmp/", "*.bak"] })
 ```
 
+Default entries added when `includeDefaults: true` (default):
+- `telemetry/` - telemetry data
+- `*.test.ts` - TypeScript test files
+- `*.test.js` - JavaScript test files
+- `coverage/` - coverage reports
+
 ## Data Sources
 
 ### Local JSONL (Default)
 
-Reads telemetry data from `~/.claude/telemetry/`:
+Automatically scans multiple telemetry directories:
+- **Global**: `~/.claude/telemetry/` (always checked)
+- **Project-local**: `.claude/telemetry/`, `telemetry/`, `.telemetry/` (checked if they exist in cwd)
+
+This allows querying both global Claude Code telemetry and project-specific telemetry.
+
+File patterns:
 - `traces-YYYY-MM-DD.jsonl` - Trace spans
 - `logs-YYYY-MM-DD.jsonl` - Log records
 - `metrics-YYYY-MM-DD.jsonl` - Metric data points
+- `llm-events-YYYY-MM-DD.jsonl` - LLM events
 
 ### SigNoz Cloud (Optional)
 
@@ -112,7 +153,15 @@ Use `backend: "signoz"` in queries to explicitly use SigNoz, or `backend: "auto"
 cd ~/.claude/mcp-servers/observability-toolkit
 npm install
 npm run build
+npm test     # 617 tests
 npm run start
 ```
 
+## Documentation
+
+- [ROADMAP.md](docs/ROADMAP.md) - Improvement roadmap with priorities
+- [code-review.md](docs/code-review.md) - Code review findings
+- [security-audit.md](docs/security-audit.md) - Security audit report
+- [observability-audit.md](docs/observability-audit.md) - Observability best practices audit
+
 

package/dist/backends/index.d.ts

@@ -14,6 +14,8 @@ export interface TraceSpan {
         code: number;
         message?: string;
     };
+    /** Human-readable status code: 'UNSET' (0), 'OK' (1), 'ERROR' (2) */
+    statusCode?: 'UNSET' | 'OK' | 'ERROR';
     attributes?: Record<string, unknown>;
     events?: Array<{
         name: string;
@@ -24,6 +26,7 @@ export interface TraceSpan {
 export interface LogRecord {
     timestamp: string;
     severity: string;
+    severityNumber?: number;
     body: string;
     traceId?: string;
     spanId?: string;
@@ -48,22 +51,47 @@ export interface TraceQueryOptions extends QueryOptions {
     spanName?: string;
     minDurationMs?: number;
     maxDurationMs?: number;
+    attributeFilter?: Record<string, string | number | boolean>;
+    /** Exclude spans matching this name (substring match) */
+    excludeSpanName?: string;
+    /** Only include spans where these attributes exist */
+    attributeExists?: string[];
+    /** Exclude spans where these attributes exist */
+    attributeNotExists?: string[];
 }
 export interface LogQueryOptions extends QueryOptions {
     severity?: string;
     search?: string;
     traceId?: string;
+    /** Exclude logs containing this text (case-insensitive) */
+    excludeSearch?: string;
+    /** Only include logs where these attributes exist */
+    attributeExists?: string[];
+    /** Exclude logs where these attributes exist */
+    attributeNotExists?: string[];
 }
 export interface MetricQueryOptions extends QueryOptions {
     metricName?: string;
     aggregation?: 'sum' | 'avg' | 'min' | 'max' | 'count';
     groupBy?: string[];
 }
+export interface LLMEvent {
+    timestamp: string;
+    name: string;
+    attributes: Record<string, unknown>;
+}
+export interface LLMEventQueryOptions extends QueryOptions {
+    eventName?: string;
+    model?: string;
+    provider?: string;
+    search?: string;
+}
 export interface TelemetryBackend {
     name: string;
     queryTraces(options: TraceQueryOptions): Promise<TraceSpan[]>;
     queryLogs(options: LogQueryOptions): Promise<LogRecord[]>;
     queryMetrics(options: MetricQueryOptions): Promise<MetricDataPoint[]>;
+    queryLLMEvents?(options: LLMEventQueryOptions): Promise<LLMEvent[]>;
     healthCheck(): Promise<{
         status: 'ok' | 'error';
         message?: string;

package/dist/backends/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC3F;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAmB,SAAQ,YAAY;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IAEb,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC9D,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IAC1D,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;IACtE,WAAW,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backends/index.ts"],"names":[],"mappings":"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"}

package/dist/backends/local-jsonl.d.ts

@@ -4,7 +4,7 @@
  * The local telemetry files use a flat JSONL format where each line is a complete
  * span or log record, not the batched OpenTelemetry export format.
  */
-import { TelemetryBackend, TraceSpan, LogRecord, MetricDataPoint, TraceQueryOptions, LogQueryOptions, MetricQueryOptions } from './index.js';
+import { TelemetryBackend, TraceSpan, LogRecord, MetricDataPoint, LLMEvent, TraceQueryOptions, LogQueryOptions, MetricQueryOptions, LLMEventQueryOptions } from './index.js';
 export declare class LocalJsonlBackend implements TelemetryBackend {
     name: string;
     private telemetryDir;
@@ -13,9 +13,37 @@ export declare class LocalJsonlBackend implements TelemetryBackend {
     queryLogs(options: LogQueryOptions): Promise<LogRecord[]>;
     queryMetrics(options: MetricQueryOptions): Promise<MetricDataPoint[]>;
     private aggregate;
+    queryLLMEvents(options: LLMEventQueryOptions): Promise<LLMEvent[]>;
     healthCheck(): Promise<{
         status: 'ok' | 'error';
         message?: string;
     }>;
 }
+/**
+ * Multi-directory backend that queries all telemetry directories
+ * (global ~/.claude/telemetry + local project directories)
+ */
+export declare class MultiDirectoryBackend implements TelemetryBackend {
+    name: string;
+    private backends;
+    private directories;
+    constructor(cwd?: string);
+    getDirectories(): Array<{
+        path: string;
+        source: 'global' | 'local';
+    }>;
+    queryTraces(options: TraceQueryOptions): Promise<TraceSpan[]>;
+    queryLogs(options: LogQueryOptions): Promise<LogRecord[]>;
+    queryMetrics(options: MetricQueryOptions): Promise<MetricDataPoint[]>;
+    queryLLMEvents(options: LLMEventQueryOptions): Promise<LLMEvent[]>;
+    healthCheck(): Promise<{
+        status: 'ok' | 'error';
+        message?: string;
+        directories?: Array<{
+            path: string;
+            source: string;
+            status: string;
+        }>;
+    }>;
+}
 //# sourceMappingURL=local-jsonl.d.ts.map

package/dist/backends/local-jsonl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-jsonl.d.ts","sourceRoot":"","sources":["../../src/backends/local-jsonl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,eAAe,EACf,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAwKpB,qBAAa,iBAAkB,YAAW,gBAAgB;IACxD,IAAI,SAAiB;IACrB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAyC7D,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAoCzD,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAyC3E,OAAO,CAAC,SAAS;IAyDX,WAAW,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAqB3E"}
+{"version":3,"file":"local-jsonl.d.ts","sourceRoot":"","sources":["../../src/backends/local-jsonl.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,SAAS,EACT,eAAe,EACf,QAAQ,EACR,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAsOpB,qBAAa,iBAAkB,YAAW,gBAAgB;IACxD,IAAI,SAAiB;IACrB,OAAO,CAAC,YAAY,CAAS;gBAEjB,YAAY,CAAC,EAAE,MAAM;IAI3B,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAyE7D,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAyDzD,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAqC3E,OAAO,CAAC,SAAS;IAyDX,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAgDlE,WAAW,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CA6B3E;AAED;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,gBAAgB;IAC5D,IAAI,SAAqB;IACzB,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,WAAW,CAAsD;gBAE7D,GAAG,CAAC,EAAE,MAAM;IAKxB,cAAc,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAA;KAAE,CAAC;IAI/D,WAAW,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAwB7D,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAwBzD,YAAY,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAarE,cAAc,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAwBlE,WAAW,IAAI,OAAO,CAAC;QAAE,MAAM,EAAE,IAAI,GAAG,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAwBlJ"}

package/dist/backends/local-jsonl.js

@@ -5,9 +5,49 @@
  * span or log record, not the batched OpenTelemetry export format.
  */
 import { join } from 'path';
-import { TELEMETRY_DIR } from '../lib/constants.js';
-import { listFiles, readJsonlSync, parseDateFromFilename, getDateString, } from '../lib/file-utils.js';
+import { TELEMETRY_DIR, getTelemetryDirectories, getSpanKind, getStatusCodeName } from '../lib/constants.js';
+import { listFiles, streamJsonl, parseDateFromFilename, getDateString, paginateResults, hasReachedLimit, } from '../lib/file-utils.js';
 import { existsSync } from 'fs';
+/**
+ * Insert item into a sorted array, maintaining sort order and max size.
+ * More efficient than sort+slice for top-K selection (O(n) vs O(n log n)).
+ */
+function insertSortedBounded(arr, item, maxSize, compareFn) {
+    // Find insertion point using binary search
+    let low = 0;
+    let high = arr.length;
+    while (low < high) {
+        const mid = (low + high) >>> 1;
+        if (compareFn(arr[mid], item) <= 0) {
+            low = mid + 1;
+        }
+        else {
+            high = mid;
+        }
+    }
+    // If array is full and item would go at end, skip it
+    if (arr.length >= maxSize && low >= maxSize) {
+        return;
+    }
+    // Insert at the correct position
+    arr.splice(low, 0, item);
+    // Remove excess element if over max size
+    if (arr.length > maxSize) {
+        arr.pop();
+    }
+}
+/**
+ * OTel-compliant severity number mapping
+ * https://opentelemetry.io/docs/specs/otel/logs/data-model/#field-severitynumber
+ */
+const SEVERITY_MAP = {
+    TRACE: 1,
+    DEBUG: 5,
+    INFO: 9,
+    WARN: 13,
+    ERROR: 17,
+    FATAL: 21,
+};
 /**
  * Convert flat span to normalized TraceSpan
  */
@@ -42,11 +82,12 @@ function normalizeSpan(raw) {
         spanId: raw.spanId,
         parentSpanId: raw.parentSpanId,
         name: raw.name,
-        kind: raw.kind !== undefined ? ['INTERNAL', 'SERVER', 'CLIENT', 'PRODUCER', 'CONSUMER'][raw.kind] : undefined,
+        kind: getSpanKind(raw.kind),
         startTimeUnixNano,
         endTimeUnixNano,
         durationMs,
         status: raw.status?.code !== undefined ? { code: raw.status.code, message: raw.status.message } : undefined,
+        statusCode: getStatusCodeName(raw.status?.code),
         attributes,
     };
 }
@@ -67,9 +108,12 @@ function normalizeLog(raw) {
     else {
         timestamp = raw.timestamp;
     }
+    const severity = raw.severityText || raw.severity || 'INFO';
+    const severityNumber = SEVERITY_MAP[severity.toUpperCase()];
     return {
         timestamp,
-        severity: raw.severityText || raw.severity || 'INFO',
+        severity,
+        severityNumber,
         body: raw.body || '',
         traceId: raw.traceId,
         spanId: raw.spanId,
@@ -128,9 +172,8 @@ export class LocalJsonlBackend {
         const limit = options.limit || 100;
         const offset = options.offset || 0;
         for (const file of files) {
-            // Read flat span records (one per line)
-            const spans = readJsonlSync(file);
-            for (const raw of spans) {
+            // Stream flat span records (one per line) to avoid loading entire file into memory
+            for await (const raw of streamJsonl(file)) {
                 const span = normalizeSpan(raw);
                 if (!span)
                     continue;
@@ -139,6 +182,8 @@ export class LocalJsonlBackend {
                     continue;
                 if (options.spanName && !span.name.includes(options.spanName))
                     continue;
+                if (options.excludeSpanName && span.name.includes(options.excludeSpanName))
+                    continue;
                 if (options.minDurationMs && (span.durationMs || 0) < options.minDurationMs)
                     continue;
                 if (options.maxDurationMs && (span.durationMs || Infinity) > options.maxDurationMs)
@@ -148,13 +193,49 @@ export class LocalJsonlBackend {
                     if (svc !== options.serviceName)
                         continue;
                 }
+                // Apply attribute filter
+                if (options.attributeFilter) {
+                    let matches = true;
+                    for (const [key, value] of Object.entries(options.attributeFilter)) {
+                        if (span.attributes?.[key] !== value) {
+                            matches = false;
+                            break;
+                        }
+                    }
+                    if (!matches)
+                        continue;
+                }
+                // Apply attributeExists filter - all specified attributes must exist
+                if (options.attributeExists) {
+                    let allExist = true;
+                    for (const key of options.attributeExists) {
+                        if (span.attributes?.[key] === undefined) {
+                            allExist = false;
+                            break;
+                        }
+                    }
+                    if (!allExist)
+                        continue;
+                }
+                // Apply attributeNotExists filter - exclude if any specified attribute exists
+                if (options.attributeNotExists) {
+                    let anyExist = false;
+                    for (const key of options.attributeNotExists) {
+                        if (span.attributes?.[key] !== undefined) {
+                            anyExist = true;
+                            break;
+                        }
+                    }
+                    if (anyExist)
+                        continue;
+                }
                 results.push(span);
-                if (results.length >= offset + limit) {
-                    return results.slice(offset, offset + limit);
+                if (hasReachedLimit(results.length, offset, limit)) {
+                    return paginateResults(results, offset, limit);
                 }
             }
         }
-        return results.slice(offset, offset + limit);
+        return paginateResults(results, offset, limit);
     }
     async queryLogs(options) {
         const files = getFilesInRange(this.telemetryDir, /logs-\d{4}-\d{2}-\d{2}\.jsonl$/, options.startDate, options.endDate);
@@ -162,9 +243,8 @@ export class LocalJsonlBackend {
         const limit = options.limit || 100;
         const offset = options.offset || 0;
         for (const file of files) {
-            // Read flat log records (one per line)
-            const logs = readJsonlSync(file);
-            for (const raw of logs) {
+            // Stream flat log records (one per line) to avoid loading entire file into memory
+            for await (const raw of streamJsonl(file)) {
                 const log = normalizeLog(raw);
                 if (!log)
                     continue;
@@ -175,23 +255,48 @@ export class LocalJsonlBackend {
                     continue;
                 if (options.search && !log.body.toLowerCase().includes(options.search.toLowerCase()))
                     continue;
+                if (options.excludeSearch && log.body.toLowerCase().includes(options.excludeSearch.toLowerCase()))
+                    continue;
+                // Apply attributeExists filter - all specified attributes must exist
+                if (options.attributeExists) {
+                    let allExist = true;
+                    for (const key of options.attributeExists) {
+                        if (log.attributes?.[key] === undefined) {
+                            allExist = false;
+                            break;
+                        }
+                    }
+                    if (!allExist)
+                        continue;
+                }
+                // Apply attributeNotExists filter - exclude if any specified attribute exists
+                if (options.attributeNotExists) {
+                    let anyExist = false;
+                    for (const key of options.attributeNotExists) {
+                        if (log.attributes?.[key] !== undefined) {
+                            anyExist = true;
+                            break;
+                        }
+                    }
+                    if (anyExist)
+                        continue;
+                }
                 results.push(log);
-                if (results.length >= offset + limit) {
-                    return results.slice(offset, offset + limit);
+                if (hasReachedLimit(results.length, offset, limit)) {
+                    return paginateResults(results, offset, limit);
                 }
             }
         }
-        return results.slice(offset, offset + limit);
+        return paginateResults(results, offset, limit);
     }
     async queryMetrics(options) {
         const files = getFilesInRange(this.telemetryDir, /metrics-\d{4}-\d{2}-\d{2}\.jsonl$/, options.startDate, options.endDate);
         const results = [];
         const limit = options.limit || 100;
         const offset = options.offset || 0;
-        for (const file of files) {
-            // Read flat metric records (one per line)
-            const metrics = readJsonlSync(file);
-            for (const raw of metrics) {
+        outer: for (const file of files) {
+            // Stream flat metric records (one per line) to avoid loading entire file into memory
+            for await (const raw of streamJsonl(file)) {
                 const point = normalizeMetric(raw);
                 if (!point)
                     continue;
@@ -199,18 +304,16 @@ export class LocalJsonlBackend {
                 if (options.metricName && !point.name.includes(options.metricName))
                     continue;
                 results.push(point);
-                if (results.length >= offset + limit) {
-                    break;
+                if (hasReachedLimit(results.length, offset, limit)) {
+                    break outer;
                 }
             }
-            if (results.length >= offset + limit)
-                break;
         }
         // Apply aggregation if requested
         if (options.aggregation && results.length > 0) {
             return this.aggregate(results, options.aggregation, options.groupBy);
         }
-        return results.slice(offset, offset + limit);
+        return paginateResults(results, offset, limit);
     }
     aggregate(points, aggregation, groupBy) {
         // Group by metric name and optional attributes
@@ -260,6 +363,47 @@ export class LocalJsonlBackend {
         }
         return results;
     }
+    async queryLLMEvents(options) {
+        const files = getFilesInRange(this.telemetryDir, /llm-events-\d{4}-\d{2}-\d{2}\.jsonl$/, options.startDate, options.endDate);
+        const results = [];
+        const limit = options.limit || 100;
+        const offset = options.offset || 0;
+        for (const file of files) {
+            // Stream LLM event records (one per line) to avoid loading entire file into memory
+            for await (const event of streamJsonl(file)) {
+                if (!event.timestamp || !event.name)
+                    continue;
+                // Apply filters
+                if (options.eventName && !event.name.includes(options.eventName))
+                    continue;
+                if (options.model) {
+                    const model = event.attributes?.['gen_ai.request.model'] || event.attributes?.['model'];
+                    if (model !== options.model)
+                        continue;
+                }
+                if (options.provider) {
+                    const provider = event.attributes?.['gen_ai.system'] || event.attributes?.['provider'];
+                    if (provider !== options.provider)
+                        continue;
+                }
+                if (options.search) {
+                    const searchLower = options.search.toLowerCase();
+                    const attrStr = JSON.stringify(event.attributes).toLowerCase();
+                    if (!attrStr.includes(searchLower) && !event.name.toLowerCase().includes(searchLower))
+                        continue;
+                }
+                results.push({
+                    timestamp: event.timestamp,
+                    name: event.name,
+                    attributes: event.attributes,
+                });
+                if (hasReachedLimit(results.length, offset, limit)) {
+                    return paginateResults(results, offset, limit);
+                }
+            }
+        }
+        return paginateResults(results, offset, limit);
+    }
     async healthCheck() {
         if (!existsSync(this.telemetryDir)) {
             return { status: 'error', message: `Telemetry directory not found: ${this.telemetryDir}` };
@@ -267,14 +411,102 @@ export class LocalJsonlBackend {
         const today = getDateString();
         const tracesFile = join(this.telemetryDir, `traces-${today}.jsonl`);
         const logsFile = join(this.telemetryDir, `logs-${today}.jsonl`);
+        const llmEventsFile = join(this.telemetryDir, `llm-events-${today}.jsonl`);
         const hasTraces = existsSync(tracesFile);
         const hasLogs = existsSync(logsFile);
-        if (!hasTraces && !hasLogs) {
+        const hasLLMEvents = existsSync(llmEventsFile);
+        const found = [
+            hasTraces ? 'traces' : '',
+            hasLogs ? 'logs' : '',
+            hasLLMEvents ? 'llm-events' : '',
+        ].filter(Boolean).join(', ');
+        if (!found) {
             return { status: 'ok', message: `No telemetry files for today (${today})` };
         }
         return {
             status: 'ok',
-            message: `Found: ${hasTraces ? 'traces' : ''}${hasTraces && hasLogs ? ', ' : ''}${hasLogs ? 'logs' : ''} for ${today}`,
+            message: `Found: ${found} for ${today}`,
+        };
+    }
+}
+/**
+ * Multi-directory backend that queries all telemetry directories
+ * (global ~/.claude/telemetry + local project directories)
+ */
+export class MultiDirectoryBackend {
+    name = 'multi-directory';
+    backends;
+    directories;
+    constructor(cwd) {
+        this.directories = getTelemetryDirectories(cwd);
+        this.backends = this.directories.map(d => new LocalJsonlBackend(d.path));
+    }
+    getDirectories() {
+        return this.directories;
+    }
+    async queryTraces(options) {
+        const limit = options.limit || 100;
+        // Query all backends in parallel
+        const allBackendResults = await Promise.all(this.backends.map(b => b.queryTraces({ ...options, limit })));
+        // Merge results using bounded insertion for efficient top-K selection
+        const topResults = [];
+        for (const results of allBackendResults) {
+            for (const span of results) {
+                insertSortedBounded(topResults, span, limit, (a, b) => (b.startTimeUnixNano || 0) - (a.startTimeUnixNano || 0));
+            }
+        }
+        return topResults;
+    }
+    async queryLogs(options) {
+        const limit = options.limit || 100;
+        // Query all backends in parallel
+        const allBackendResults = await Promise.all(this.backends.map(b => b.queryLogs({ ...options, limit })));
+        // Merge results using bounded insertion for efficient top-K selection
+        const topResults = [];
+        for (const results of allBackendResults) {
+            for (const log of results) {
+                insertSortedBounded(topResults, log, limit, (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+            }
+        }
+        return topResults;
+    }
+    async queryMetrics(options) {
+        const limit = options.limit || 100;
+        // Query all backends in parallel
+        const allBackendResults = await Promise.all(this.backends.map(b => b.queryMetrics({ ...options, limit })));
+        // Flatten and limit results
+        const allResults = allBackendResults.flat();
+        return allResults.slice(0, limit);
+    }
+    async queryLLMEvents(options) {
+        const limit = options.limit || 100;
+        // Query all backends in parallel
+        const allBackendResults = await Promise.all(this.backends.map(b => b.queryLLMEvents({ ...options, limit })));
+        // Merge results using bounded insertion for efficient top-K selection
+        const topResults = [];
+        for (const results of allBackendResults) {
+            for (const event of results) {
+                insertSortedBounded(topResults, event, limit, (a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+            }
+        }
+        return topResults;
+    }
+    async healthCheck() {
+        if (this.backends.length === 0) {
+            return { status: 'error', message: 'No telemetry directories found' };
+        }
+        // Check all backends in parallel
+        const healthResults = await Promise.all(this.backends.map(b => b.healthCheck()));
+        const dirStatuses = healthResults.map((result, i) => ({
+            path: this.directories[i].path,
+            source: this.directories[i].source,
+            status: result.message || result.status,
+        }));
+        const hasOk = healthResults.some(r => r.status === 'ok');
+        return {
+            status: hasOk ? 'ok' : 'error',
+            message: `Found ${this.directories.length} telemetry director${this.directories.length === 1 ? 'y' : 'ies'}`,
+            directories: dirStatuses,
         };
     }
 }