Skip to content

Logging

This guide explains where Hamr logs are stored, how to adjust verbosity, and privacy considerations.

Log File Locations

Hamr components write logs to /tmp/ with timestamped filenames:

Component Log File Pattern Symlink (Latest)
Daemon /tmp/hamr-daemon-YYYYMMDD_HHMMSS.log /tmp/hamr-daemon.log
TUI /tmp/hamr-tui-YYYYMMDD_HHMMSS.log /tmp/hamr-tui.log

The symlinks always point to the most recent log file for easy access.

Debug vs Release Builds

Build Type Default Level Output Location
Debug debug (verbose) Timestamped files in /tmp/
Release info stderr only

Debug builds include file/line numbers in log output for easier debugging.

Environment Variables

RUST_LOG

Controls Rust component logging verbosity using the standard tracing crate:

# Most verbose - all trace messages
RUST_LOG=trace hamr daemon

# Debug level - detailed diagnostic info
RUST_LOG=debug hamr daemon

# Info level (default for release)
RUST_LOG=info hamr daemon

# Warnings and errors only
RUST_LOG=warn hamr daemon

# Errors only
RUST_LOG=error hamr daemon

Filter to specific crates:

# Debug only for hamr crates (reduces noise from dependencies)
RUST_LOG=hamr=debug hamr daemon

# Combine filters
RUST_LOG=hamr=debug,tokio=warn hamr daemon

HAMR_PLUGIN_DEBUG

Enables verbose debug output in the Python plugin SDK:

# Enable plugin SDK debug logging
HAMR_PLUGIN_DEBUG=1 hamr daemon

When enabled, plugins using the SDK will output additional diagnostic information including: - Incoming JSON-RPC requests - Outgoing responses - Internal state transitions

Accepted values: 1, true, yes (case-insensitive)

Reading Logs

Follow logs in real-time

# Daemon logs
tail -f /tmp/hamr-daemon.log

# TUI logs (in separate terminal)
tail -f /tmp/hamr-tui.log

# Both simultaneously
tail -f /tmp/hamr-daemon.log /tmp/hamr-tui.log

Search for specific patterns

# Find errors and warnings
grep -i "error\|warn" /tmp/hamr-daemon.log

# Plugin-related messages
grep "plugin" /tmp/hamr-daemon.log | tail -30

# Action handling
grep "handle_action\|Forwarding" /tmp/hamr-daemon.log

# Form/settings changes
grep -i "form\|slider\|switch" /tmp/hamr-daemon.log

View historical logs

# List recent daemon logs (newest first)
ls -lt /tmp/hamr-daemon-*.log | head -5

# List recent TUI logs
ls -lt /tmp/hamr-tui-*.log | head -5

Common Debugging Scenarios

Plugin not responding

# Check if plugin is connected
grep "plugin" /tmp/hamr-daemon.log | tail -20

# Look for action forwarding
grep "handle_item_selected\|Forwarding action" /tmp/hamr-daemon.log

JSON deserialization errors

# TUI logs show parsing failures
grep -i "deserialization\|error" /tmp/hamr-tui.log

Configuration issues

# Search for config-related messages
grep -i "config" /tmp/hamr-daemon.log

Privacy Statement

No telemetry: Hamr does not send any data to external servers. All logging is local to your machine.

What logs contain

Logs may include: - Search queries you type - Plugin IDs and names - File paths on your system - Application names from your index - Error messages and stack traces

Before sharing logs

When reporting issues or sharing logs publicly:

  1. Review log content for sensitive information
  2. Redact personal file paths (e.g., /home/username/ -> /home/<user>/)
  3. Remove any queries that reveal private information
  4. Consider using only relevant excerpts rather than full logs

Example redaction:

# Create redacted log excerpt
tail -200 /tmp/hamr-daemon.log | \
  sed "s|/home/$USER|/home/<user>|g" > hamr-debug-redacted.log

Log Retention

tmpfs behavior

Logs in /tmp/ are typically stored on a tmpfs (RAM disk) on most Linux distributions:

  • Logs are cleared on reboot
  • Fast write performance
  • No disk wear

Archiving logs

To preserve logs across reboots:

# Archive current session
cp /tmp/hamr-daemon.log ~/hamr-logs/daemon-$(date +%Y%m%d).log

# Archive with compression
gzip -c /tmp/hamr-daemon.log > ~/hamr-logs/daemon-$(date +%Y%m%d).log.gz

Cleaning old logs

Timestamped logs accumulate during long sessions:

# Remove logs older than 7 days
find /tmp -name "hamr-*.log" -mtime +7 -delete

# Keep only the 5 most recent of each type
ls -t /tmp/hamr-daemon-*.log | tail -n +6 | xargs rm -f
ls -t /tmp/hamr-tui-*.log | tail -n +6 | xargs rm -f

See Also