UI Guide

This guide walks through Cruncher’s interface and explains the main UI components.

Main Layout

The Cruncher window is divided into several key areas:

1. Search Header — Query editor, time range, and controls (top)
2. Histogram — Visual distribution of logs over time (middle)
3. Results View — Tabs for different result types (bottom)
4. Row Details Panel — Inspector for individual records (right side, when open)

Search Header

The search header contains:

• Query Editor: Multi-line input for your QQL query. Press Alt+Q to focus or use keyboard shortcut Shift+Enter to re-evaluate the pipeline. As you type, an autocomplete dropdown appears with fuzzy-matched suggestions — matched characters are highlighted so you can see why each suggestion was chosen. Hover over a token to see a hint tooltip with its description and syntax.
• Time Range Selector: Click to open a date/time picker, or press Alt+T to quickly access it.
• Execute Button: Run your full search.
• Live Button: Toggle real-time incremental log streaming. See Live Mode.
• Share Button: Copy a shareable link to this search.
• Settings: Access theme preferences, live mode interval, and memory limits.
• Data Source Selector: Choose the active search profile. A small status indicator shows the connection state:
  • Spinner — loading / initializing
  • Green ✓ — all connectors loaded successfully
  • Red ✗ — one or more connectors encountered an error
• Connectors button (database icon): Jump directly to the Connectors page in Settings.

See Keyboard Shortcuts for the full reference.

Histogram

The histogram visualizes the distribution of your log results over the selected time range. Each bar represents the count of matching logs in that time bucket.

Histogram Interactions

• Click a bucket: Focus on that time period
• Drag across buckets: Select a time range and zoom in
• Scroll: Adjust bucket size (zoom in/out)
• Hover: See exact timestamp and count for a bucket

The histogram automatically updates when you modify your query or time range.

Results Views

Results are displayed in tabs below the histogram. The available tabs depend on your query:

Logs Tab (Always Available)

Shows individual log records in chronological order. Each row displays:

• Timestamp: When the log was created
• Message: The main content of the log, clamped to 3 lines by default
• Level/Severity: Log level (error, warn, info, etc.), if available

Message Expand / Collapse

Long messages are clamped to 3 lines. A small chevron button appears inline when a message overflows:

• Click ↓ to expand that row and see the full message
• Click ↑ to collapse it back to 3 lines

The Logs Toolbar (just above the log list) lets you change the global default for all rows at once:

• Expand all (⇓): unfold every message by default
• Collapse all (⇑): return to the 3-line clamp

Per-row overrides take priority over the global setting.

Click a row to open the Row Details panel on the right.

Table Tab (After | table or | stats command)

When your query ends with a table or stats command, a Table tab appears showing aggregated results in a tabular format.

• Column headers: Automatically generated from selected fields or aggregation results
• Sortable columns: Click column headers to sort
• Row counts: Shows how many rows are displayed

Example query that produces Table results:

| stats count(), avg(latency_ms) by service

View Tab (After | timechart command)

When your query produces time-series data (via timechart command), a View tab displays a chart visualization.

• Time-series chart: Shows metrics over time
• Grouped by: Color-coded series for different values

Example query that produces View results:

| timechart count() by level

Row Details Panel

When you click on a log record, the Row Details panel opens on the right side, showing all fields in that record.

Field Information

Each field shows:

• Field name: Left side
• Field value: Right side
• Type indicator: A small icon showing the field type (string, number, boolean, etc.)
• Copy button: Hover over a value to see a copy icon
• Append button: Arrow button to quickly add this field to your query

Interactions

• Copy value: Click the copy icon next to any field value
• Append to query: Click the arrow button to add a filter like field="value" to your query
• Close panel: Click the X or click elsewhere in the results

Connectors Page

Open Settings → Connectors (or click the database icon in the header) to see the status of every configured connector.

The page is split into two panels:

Profiles (left panel)

Lists every search profile defined in your config. Each profile shows:

• Its name
• A coloured dot per connector instance indicating current status (green = loaded, yellow = loading, red = error, grey = not yet initialised)
• A Play button to re-initialise the profile’s connectors on demand

Connectors (right panel)

A table of every connector instance across all profiles, with columns:

Column	Description
Status	Coloured dot (hover for tooltip)
Name	Instance name from the config
Plugin	Human-readable adapter type
Param Keys	Which parameter keys were loaded (e.g. index, service)
Last Init	Time the connector was last initialised
Description / Error	Adapter description, or the error message if initialisation failed

A Reload all button in the panel header re-initialises every connector at once.

Settings

Click the Settings icon (gear) in the search header to open the Settings drawer:

• Theme: Choose your preferred color scheme (Midnight, Nord, Dracula, Catppuccin). See Themes.
• Live interval: How often Live Mode fetches new logs (1s / 3s / 5s / 10s).
• Max logs in memory: Hard cap on records kept in memory; oldest are discarded when exceeded.
• Auto-stop live (min, 0=off): Number of minutes before Live Mode turns itself off automatically. Default is 30 minutes; set to 0 to disable.
• Timezone: LOCAL or UTC. Controls how all timestamps are displayed — log rows, histogram x-axis, chart tooltips, and the calendar date input. Both options are fully consistent with each other.

All settings are persisted to the config file. See Live Mode for details on the live-specific options.

Tabs

Create multiple search tabs to organize different investigations:

• Create tab: Press Cmd+T (Mac) or Ctrl+T (Windows)
• Close tab: Press Cmd+W (Mac) or Ctrl+W (Windows)
• Switch tabs: Click on any tab, or use keyboard navigation

Each tab maintains its own:

• Query
• Time range
• Results
• Settings

---

See Keyboard Shortcuts for the full shortcuts reference.