feat: add logging and metrics collection for indexing and search operations

Author: Helweg

README.md

@@ -198,6 +198,14 @@ Checks if the index is ready and healthy.
 ### `index_health_check`
 Maintenance tool to remove stale entries from deleted files and orphaned embeddings/chunks from the database.
 
+### `index_metrics`
+Returns collected metrics about indexing and search performance. Requires `debug.enabled` and `debug.metrics` to be `true`.
+- **Metrics include**: Files indexed, chunks created, cache hit rate, search timing breakdown, GC stats, embedding API call stats.
+
+### `index_logs`
+Returns recent debug logs with optional filtering.
+- **Parameters**: `category` (optional: `search`, `embedding`, `cache`, `gc`, `branch`), `level` (optional: `error`, `warn`, `info`, `debug`), `limit` (default: 50).
+
 ## 🎮 Slash Commands
 
 The plugin automatically registers these slash commands:
@@ -232,6 +240,11 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "minScore": 0.1,
     "hybridWeight": 0.5,
     "contextLines": 0
+  },
+  "debug": {
+    "enabled": false,
+    "logLevel": "info",
+    "metrics": false
   }
 }
 ```
@@ -258,6 +271,15 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 | `minScore` | `0.1` | Minimum similarity score (0-1). Lower = more results |
 | `hybridWeight` | `0.5` | Balance between keyword (1.0) and semantic (0.0) search |
 | `contextLines` | `0` | Extra lines to include before/after each match |
+| **debug** | | |
+| `enabled` | `false` | Enable debug logging and metrics collection |
+| `logLevel` | `"info"` | Log level: `error`, `warn`, `info`, `debug` |
+| `logSearch` | `true` | Log search operations with timing breakdown |
+| `logEmbedding` | `true` | Log embedding API calls (success, error, rate-limit) |
+| `logCache` | `true` | Log cache hits and misses |
+| `logGc` | `true` | Log garbage collection operations |
+| `logBranch` | `true` | Log branch detection and switches |
+| `metrics` | `false` | Enable metrics collection (indexing stats, search timing, cache performance) |
 
 ### Embedding Providers
 The plugin automatically detects available credentials in this order:

src/config/schema.ts

@@ -25,19 +25,34 @@ export interface SearchConfig {
   contextLines: number;
 }
 
+export type LogLevel = "error" | "warn" | "info" | "debug";
+
+export interface DebugConfig {
+  enabled: boolean;
+  logLevel: LogLevel;
+  logSearch: boolean;
+  logEmbedding: boolean;
+  logCache: boolean;
+  logGc: boolean;
+  logBranch: boolean;
+  metrics: boolean;
+}
+
 export interface CodebaseIndexConfig {
   embeddingProvider: EmbeddingProvider;
   embeddingModel: string;
   scope: IndexScope;
   indexing?: Partial<IndexingConfig>;
   search?: Partial<SearchConfig>;
+  debug?: Partial<DebugConfig>;
   include: string[];
   exclude: string[];
 }
 
 export type ParsedCodebaseIndexConfig = CodebaseIndexConfig & {
   indexing: IndexingConfig;
   search: SearchConfig;
+  debug: DebugConfig;
 };
 
 const DEFAULT_INCLUDE = [
@@ -94,8 +109,22 @@ function getDefaultSearchConfig(): SearchConfig {
   };
 }
 
+function getDefaultDebugConfig(): DebugConfig {
+  return {
+    enabled: false,
+    logLevel: "info",
+    logSearch: true,
+    logEmbedding: true,
+    logCache: true,
+    logGc: true,
+    logBranch: true,
+    metrics: true,
+  };
+}
+
 const VALID_PROVIDERS: EmbeddingProvider[] = ["auto", "github-copilot", "openai", "google", "ollama"];
 const VALID_SCOPES: IndexScope[] = ["project", "global"];
+const VALID_LOG_LEVELS: LogLevel[] = ["error", "warn", "info", "debug"];
 
 function isValidProvider(value: unknown): value is EmbeddingProvider {
   return typeof value === "string" && VALID_PROVIDERS.includes(value as EmbeddingProvider);
@@ -109,11 +138,17 @@ function isStringArray(value: unknown): value is string[] {
   return Array.isArray(value) && value.every(item => typeof item === "string");
 }
 
+function isValidLogLevel(value: unknown): value is LogLevel {
+  return typeof value === "string" && VALID_LOG_LEVELS.includes(value as LogLevel);
+}
+
 export function parseConfig(raw: unknown): ParsedCodebaseIndexConfig {
   const input = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
 
   const defaultIndexing = getDefaultIndexingConfig();
   const defaultSearch = getDefaultSearchConfig();
+  const defaultDebug = getDefaultDebugConfig();
+  
   const rawIndexing = (input.indexing && typeof input.indexing === "object" ? input.indexing : {}) as Record<string, unknown>;
   const indexing: IndexingConfig = {
     autoIndex: typeof rawIndexing.autoIndex === "boolean" ? rawIndexing.autoIndex : defaultIndexing.autoIndex,
@@ -137,6 +172,18 @@ export function parseConfig(raw: unknown): ParsedCodebaseIndexConfig {
     contextLines: typeof rawSearch.contextLines === "number" ? Math.min(50, Math.max(0, rawSearch.contextLines)) : defaultSearch.contextLines,
   };
 
+  const rawDebug = (input.debug && typeof input.debug === "object" ? input.debug : {}) as Record<string, unknown>;
+  const debug: DebugConfig = {
+    enabled: typeof rawDebug.enabled === "boolean" ? rawDebug.enabled : defaultDebug.enabled,
+    logLevel: isValidLogLevel(rawDebug.logLevel) ? rawDebug.logLevel : defaultDebug.logLevel,
+    logSearch: typeof rawDebug.logSearch === "boolean" ? rawDebug.logSearch : defaultDebug.logSearch,
+    logEmbedding: typeof rawDebug.logEmbedding === "boolean" ? rawDebug.logEmbedding : defaultDebug.logEmbedding,
+    logCache: typeof rawDebug.logCache === "boolean" ? rawDebug.logCache : defaultDebug.logCache,
+    logGc: typeof rawDebug.logGc === "boolean" ? rawDebug.logGc : defaultDebug.logGc,
+    logBranch: typeof rawDebug.logBranch === "boolean" ? rawDebug.logBranch : defaultDebug.logBranch,
+    metrics: typeof rawDebug.metrics === "boolean" ? rawDebug.metrics : defaultDebug.metrics,
+  };
+  
   return {
     embeddingProvider: isValidProvider(input.embeddingProvider) ? input.embeddingProvider : "auto",
     embeddingModel: typeof input.embeddingModel === "string" ? input.embeddingModel : "auto",
@@ -145,6 +192,7 @@ export function parseConfig(raw: unknown): ParsedCodebaseIndexConfig {
     exclude: isStringArray(input.exclude) ? input.exclude : DEFAULT_EXCLUDE,
     indexing,
     search,
+    debug,
   };
 }
 

src/index.ts

@@ -12,6 +12,8 @@ import {
   index_codebase,
   index_status,
   index_health_check,
+  index_metrics,
+  index_logs,
   initializeTools,
 } from "./tools/index.js";
 import { loadCommandsFromDirectory } from "./commands/loader.js";
@@ -76,6 +78,8 @@ const plugin: Plugin = async ({ directory }) => {
       index_codebase,
       index_status,
       index_health_check,
+      index_metrics,
+      index_logs,
     },
 
     async config(cfg) {