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

> Master debugging with MiniSearch's in-browser log entries system. Learn best practices for privacy-safe debugging without external servers. A complete guide for felladrin/minisearch.

- Repository: [Victor Nogueira/minisearch](https://github.com/felladrin/minisearch)
- Tags: how-to-guide
- Published: 2026-03-01

---

**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`](https://github.com/felladrin/minisearch/blob/main/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`](https://github.com/felladrin/minisearch/blob/main/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`](https://github.com/felladrin/minisearch/blob/main/client/modules/search.ts) demonstrates this pattern:

```typescript
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`](https://github.com/felladrin/minisearch/blob/main/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`](https://github.com/felladrin/minisearch/blob/main/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:

```typescript
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:

```tsx
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`](https://github.com/felladrin/minisearch/blob/main/client/modules/logEntries.ts)** – Contains `addLogEntry` and the `logEntriesPubSub` store
- **[`client/components/Logs/LogsModal.tsx`](https://github.com/felladrin/minisearch/blob/main/client/components/Logs/LogsModal.tsx)** – Implements the UI for viewing, filtering, paginating, and downloading logs
- **[`client/modules/search.ts`](https://github.com/felladrin/minisearch/blob/main/client/modules/search.ts)** – Demonstrates extensive logging in search workflows
- **[`client/modules/textGenerationWithWllama.ts`](https://github.com/felladrin/minisearch/blob/main/client/modules/textGenerationWithWllama.ts)** – Shows model lifecycle event logging
- **[`client/modules/pubSub.ts`](https://github.com/felladrin/minisearch/blob/main/client/modules/pubSub.ts)** – The underlying Pub/Sub utility powering the logger

## Summary

- **Use `addLogEntry`** from [`client/modules/logEntries.ts`](https://github.com/felladrin/minisearch/blob/main/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`](https://github.com/felladrin/minisearch/blob/main/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`](https://github.com/felladrin/minisearch/blob/main/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.