Debugging Issues Using the MiniSearch Log Entries System: A Complete Guide

MiniSearch provides an in-browser Pub/Sub logging system via addLogEntry() and LogsModal that enables privacy-safe debugging without exposing sensitive data to external servers.

MiniSearch is an open-source client-side search interface that implements a lightweight logging architecture for troubleshooting. When debugging issues using the provided log entries system, developers can leverage the built-in Pub/Sub logger to capture diagnostic information entirely within the browser, ensuring no sensitive data leaves the user's device.

Understanding the Core Logging Architecture

The logging system centers on three main components defined in client/modules/logEntries.ts. The addLogEntry(message: string) function timestamps incoming strings and pushes them onto a shared array managed by logEntriesPubSub, a Pub/Sub instance that stores an array of {timestamp, message} objects. Any module can import this function to record events, while any component can subscribe to receive live updates.

The LogsModal component in client/components/Logs/LogsModal.tsx provides the user interface for interacting with these logs. It reads from the Pub/Sub store, implements text filtering and pagination, and handles exporting the full log history as a JSON file.

Best Practices for Effective Debugging

Log at Strategic Entry Points and State Changes

Place addLogEntry calls at critical junctions to create a chronological trace of execution. This includes:

• Entry points – Log at the start and end of every asynchronous operation such as search requests, model initialization, or token verification
• State changes – Record when internal module states shift, including search status updates, generation state changes, or cache hits and misses
• Error paths – Capture error objects or messages before re-throwing or handling them to preserve failure context

The search module in client/modules/search.ts demonstrates this pattern:

addLogEntry(`🔍 Starting ${context.logLabel} for query "${query}"`);
// … perform the request …
addLogEntry(`✅ ${context.logLabel} returned ${results.length} results`);

Maintain Consistent Message Conventions

Structure log messages to enable quick scanning and filtering:

• Prefix with emoji or tags (🔍, ⚙️, ❗) to categorize entries visually
• Include identifiers such as query hashes, token IDs, model names, or cache keys rather than raw content
• Avoid personal data – Never log raw user queries or API keys; use hashed representations to maintain privacy

Leverage the LogsModal UI for Real-Time Inspection

Access the Logs modal through the Settings menu to inspect entries without writing code. The interface provides:

• Instant filtering – Type any substring to filter the list via entry.message.toLowerCase().includes(filterText)
• Pagination – Navigate through entries five at a time using the built-in page controls
• Live updates – The modal subscribes to logEntriesPubSub and reflects new entries immediately as modules call addLogEntry

Export Logs for Deep Analysis and Bug Reports

Click Download Logs in the modal to generate a logs.json file containing exact timestamp-message pairs. The downloadLogsAsJson function creates a Blob, generates an object URL, and programmatically triggers a download. Attach this file to GitHub issues—the modal already provides a direct link to the issue template for convenience.

Monitor Performance Metrics in Logs

The search module records cache metrics via cacheMetrics.logPerformance and logs reset events when thresholds trigger. Review these entries to verify that caching behaves as expected and that performance counters remain active rather than silently disabled.

Standardize Log Labels Across Modules

Modules performing similar work (text search versus image search) pass a logLabel property (e.g., "Text search", "Image search") through a shared SearchExecutionConfig. Maintaining consistent labels across client/modules/search.ts and related files makes it trivial to filter by operation type using the UI filter text.

Manage Log Lifecycle and Privacy

Since logs persist only as long as the page remains open, a browser reload automatically clears them. For manual reset during long sessions, implement actions that clear the Pub/Sub array—such as a "Clear cache" button—and log the event via addLogEntry("🧹 Logs cleared").

Implementation Examples

Adding Log Entries in a Module

Import the utility and wrap operations with diagnostic calls:

import { addLogEntry } from "./logEntries";

export async function fetchSearchResults(query: string) {
  addLogEntry(`🔍 Initiating search for hash ${hashQuery(query)}`);
  try {
    const results = await callSearchApi(query);
    addLogEntry(`✅ Search completed: ${results.length} hits`);
    return results;
  } catch (err) {
    addLogEntry(`❗ Search error: ${err}`);
    throw err;
  }
}

Subscribing to Log Updates in Components

Use the React hook to display logs in custom debugging panels:

import { usePubSub } from "create-pubsub/react";
import { logEntriesPubSub } from "@/modules/logEntries";

export default function DebugPanel() {
  const [logs] = usePubSub(logEntriesPubSub);
  return (
    <pre>{logs.map(l => `${l.timestamp} – ${l.message}`).join("\n")}</pre>
  );
}

Key Source Files and Functions

• client/modules/logEntries.ts – Contains addLogEntry and the logEntriesPubSub store
• client/components/Logs/LogsModal.tsx – Implements the UI for viewing, filtering, paginating, and downloading logs
• client/modules/search.ts – Demonstrates extensive logging in search workflows
• client/modules/textGenerationWithWllama.ts – Shows model lifecycle event logging
• client/modules/pubSub.ts – The underlying Pub/Sub utility powering the logger

Summary

• Use addLogEntry from client/modules/logEntries.ts to record timestamps and messages via the Pub/Sub system
• Place logs at entry points, state changes, and error paths to create execution traces
• Format messages consistently with emoji prefixes and identifiers, avoiding raw sensitive data
• Inspect logs via LogsModal for filtering and pagination without additional code
• Export JSON logs using the built-in download function for offline analysis or bug reporting
• Leverage log labels consistently across modules to simplify filtering by operation type

Frequently Asked Questions

How do I access the log entries in MiniSearch?

Open the Settings menu and select the Logs option to launch LogsModal. The modal subscribes to logEntriesPubSub and displays all entries recorded via addLogEntry. You can filter entries by typing in the search box or navigate through pages using the pagination controls.

Is the MiniSearch logging system secure for sensitive data?

Yes. The logs never leave the browser—they are stored in memory via the Pub/Sub array and cleared automatically on page reload. Always hash or obfuscate identifiers rather than logging raw user queries or API keys to maintain privacy even in local debugging.

How can I export logs to share with developers?

Click the Download Logs button in LogsModal to generate a logs.json file. This exports the exact {timestamp, message} pairs stored in logEntriesPubSub. Attach this file to GitHub issues to provide developers with precise diagnostic timelines.

Where are the log entries stored?

Log entries reside in the logEntriesPubSub array defined in client/modules/logEntries.ts. This is an in-memory store that persists only for the duration of the browser session, ensuring no server-side storage or network transmission of diagnostic data occurs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}