Skip to content

Debug Issues Systematically

Learn how to diagnose and fix problems when Kelora isn't working as expected.

Quick Debugging Workflow

When something isn't working, follow this process:

  1. Check field names and types - Use -F inspect to see actual field structure
  2. Enable error output - Use --verbose to see detailed error messages
  3. Check statistics - Use --stats to see how many events were filtered/errored
  4. Test with small sample - Use --take 10 for fast iteration
  5. Use strict mode - Use --strict to fail-fast on errors during debugging

Example debugging session:

# 1. What fields are actually present?
kelora -j app.log -F inspect --take 3

# 2. Why is my filter not matching?
kelora -j app.log --filter 'e.status >= 500' --verbose --stats

# 3. Test quickly with a small sample
kelora -j app.log --filter 'e.status >= 500' --take 10

Debugging Tools Reference

-F inspect - See Field Structure

Shows field names, types, and values for debugging:

kelora -j app.log -F inspect --take 3

Output example: 

🔹 {"timestamp": String("2024-01-15T10:00:00Z"), "level": String("ERROR"), "status": Integer(500)}

Use when:

  • Need to see actual field types
  • Unsure what fields are present
  • Debugging type comparison errors

--verbose - Detailed Error Output

Shows detailed error messages for parse, filter, and exec errors:

kelora -j app.log --verbose

Use multiple times for more detail:

  • -v - Show error messages as they occur
  • -vv - Show error messages plus original line content for parse errors
  • -vvv - Show error messages, lines, plus detailed line analysis (character counts, encoding issues)

Use when:

  • Filters aren't working
  • Parse errors occurring
  • Scripts failing

--stats - Processing Summary

Shows statistics at end of processing:

kelora -j app.log --stats

Output example: 

🔹 Processed 1000 lines, 850 events output, 150 filtered, 0 errors
🔹 Time range: 2024-01-15T10:00:00Z to 2024-01-15T11:00:00Z
🔹 Levels: ERROR(150), WARN(300), INFO(550)

Use when:

  • Need to understand filtering results
  • Checking error counts
  • Verifying time ranges
  • Understanding level distribution

--take N - Limit Output

Process only first N events (after filtering):

kelora -j app.log --take 10

Use when:

  • Testing filters quickly
  • Debugging with large files
  • Iterating on scripts
  • Checking output format

Tip: Combine with --stats to see total counts while limiting output:

kelora -j large.log --filter 'e.level == "ERROR"' --take 10 --stats

--strict - Fail-Fast Mode

Abort immediately on first error:

kelora -j --strict app.log

Use when:

  • Debugging parse errors
  • Validating log format
  • Testing scripts
  • CI/CD validation

Difference from default:

  • Default (resilient): Continue on errors, show count at end
  • Strict: Abort immediately on first error

--keep-lines / --ignore-lines - Pre-filter

Filter at line level before parsing (faster than post-parse filtering):

# Only process lines containing ERROR
kelora -j app.log --keep-lines 'ERROR'

# Skip debug lines
kelora -j app.log --ignore-lines 'DEBUG|TRACE'

Use when:

  • Processing very large files
  • Most lines can be skipped early
  • Performance is critical

Getting More Help

Built-in Help

kelora --help              # Complete CLI reference
kelora --help-examples     # Common usage patterns
kelora --help-rhai         # Rhai scripting guide
kelora --help-functions    # All built-in functions
kelora --help-time         # Timestamp format reference
kelora --help-multiline    # Multiline strategies

Documentation

Tips for Asking Questions

When asking for help, include:

  1. Command you ran - Full command with all flags
  2. Sample input - A few lines of log data
  3. Expected output - What you expected to see
  4. Actual output - What actually happened
  5. Error messages - Complete error output with --verbose
  6. Field structure - Output of -F inspect --take 3

Example:

Command:
  kelora -j app.log --filter 'e.status >= 500'

Sample input:
  {"timestamp": "2024-01-15T10:00:00Z", "status": "500"}

Error:
  Type mismatch: cannot compare String with Integer

Field structure (kelora -j app.log -F inspect --take 1):
  {"status": String("500")}

Expected: Filter events with status >= 500
Actual: Error on type comparison

Quick Reference

Start here when debugging:

  1. kelora -j app.log -F inspect --take 5 - See field structure
  2. kelora -j app.log --verbose --stats - See errors and statistics
  3. kelora -j app.log --take 10 - Test with small sample
  4. kelora -j --strict app.log - Fail-fast mode for debugging

Common fixes:

  • Field not found → Use e.has("field") or e.get("field", default)
  • Type error → Use .to_int_or(0) or .to_string()
  • Empty output → Check with --stats
  • Parse error → Check format with -f auto or use --verbose
  • Stage order → Create fields before filtering on them
  • Slow processing → Use --parallel for large files