Skip to content

Quickstart

Get Kelora running in 5 minutes with three commands.

Installation

macOS (Homebrew): 

brew tap dloss/kelora
brew install kelora

Other platforms: Download pre-built binaries or install via Cargo:

cargo install kelora

Three Essential Commands

Here's a typical log file with unstructured text and key-value pairs buried in the messages:

Jan 15 10:00:00 INFO Application started on :8080
Jan 15 10:00:05 INFO Connected to database db-primary
Jan 15 10:00:12 WARN Slow query detected: 450ms (threshold: 200ms)
Jan 15 10:00:15 ERROR Payment timeout order=1234 gateway=stripe duration=5s
Jan 15 10:00:18 INFO Payment retry successful order=1234
Jan 15 10:00:22 ERROR Gateway unreachable host=stripe.com
Jan 15 10:00:25 ERROR Rate limit exceeded service=payment-api endpoint=/charge limit=100 window=60s
Jan 15 10:00:27 WARN Cache miss key=user:5678 fetch_time=120ms
Jan 15 10:00:28 ERROR Authentication failed user=admin ip=192.168.1.50 reason=invalid_token
Jan 15 10:00:30 WARN Pool exhausted: 20/20 used, 15 waiting
Jan 15 10:00:35 INFO Shutting down connections=3

1. Parse with Kelora

kelora examples/quickstart.log -f 'cols:ts(3) level *msg'

ts='Jan 15 10:00:00' level='INFO' msg='Application started on :8080'
ts='Jan 15 10:00:05' level='INFO' msg='Connected to database db-primary'
ts='Jan 15 10:00:12' level='WARN' msg='Slow query detected: 450ms (threshold: 200ms)'
ts='Jan 15 10:00:15' level='ERROR' msg='Payment timeout order=1234 gateway=stripe duration=5s'
ts='Jan 15 10:00:18' level='INFO' msg='Payment retry successful order=1234'
ts='Jan 15 10:00:22' level='ERROR' msg='Gateway unreachable host=stripe.com'
ts='Jan 15 10:00:25' level='ERROR'
  msg='Rate limit exceeded service=payment-api endpoint=/charge limit=100 window=60s'
ts='Jan 15 10:00:27' level='WARN' msg='Cache miss key=user:5678 fetch_time=120ms'
ts='Jan 15 10:00:28' level='ERROR'
  msg='Authentication failed user=admin ip=192.168.1.50 reason=invalid_token'
ts='Jan 15 10:00:30' level='WARN' msg='Pool exhausted: 20/20 used, 15 waiting'
ts='Jan 15 10:00:35' level='INFO' msg='Shutting down connections=3'

Kelora parses the custom format into structured fields. The format spec cols:ts(3) level *msg tells Kelora that each line has a 3-token timestamp, followed by a level field, and then the rest is the message. Notice how timestamps are formatted, levels are color-coded, and messages are cleanly separated.

2. Filter and analyze

kelora examples/quickstart.log -f 'cols:ts(3) level *msg' -l error --stats

Detected format: cols
Lines processed: 11 total, 0 filtered (0.0%), 0 errors (0.0%)
Events created: 11 total, 4 output, 7 filtered (63.6%)
Throughput: 6871 lines/s in 1ms
Timestamp: ts (auto-detected) - 11/11 parsed (100.0%).
kelora warning: Year-less timestamp format detected (15 parses)
Format lacks year (e.g., "Dec 31 23:59:59")
Year inferred using heuristic (±1 year from current date)
Timestamps >18 months old may be incorrect
Input time span (before filtering): 2026-01-15T10:00:00+00:00 to 2026-01-15T10:00:35+00:00 (35s)
Output time span (after filtering): 2026-01-15T10:00:15+00:00 to 2026-01-15T10:00:28+00:00 (13s)
Levels seen: ERROR,INFO,WARN
Levels output: ERROR
Keys seen: level,msg,ts

Filter to show only ERROR level events and display statistics. The stats show processing metrics: 11 lines parsed, 4 errors output (7 filtered out), time span covered, and which levels and keys were present in both the input and output (when they differ due to filtering or transformations).

3. Extract hidden data

kelora examples/quickstart.log -f 'cols:ts(3) level *msg' -l error \
  -e 'e.absorb_kv("msg")' --normalize-ts -J

{"ts":"2026-01-15T10:00:15+00:00","level":"ERROR","msg":"Payment timeout","duration":"5s","gateway":"stripe","order":"1234"}
{"ts":"2026-01-15T10:00:22+00:00","level":"ERROR","msg":"Gateway unreachable","host":"stripe.com"}
{"ts":"2026-01-15T10:00:25+00:00","level":"ERROR","msg":"Rate limit exceeded","endpoint":"/charge","limit":"100","service":"payment-api","window":"60s"}
{"ts":"2026-01-15T10:00:28+00:00","level":"ERROR","msg":"Authentication failed","ip":"192.168.1.50","reason":"invalid_token","user":"admin"}

Extract key-value pairs from error messages into structured JSON fields. Notice how order=1234, gateway=stripe, user=admin, and other embedded data are now proper JSON fields. The --normalize-ts flag also converts the syslog timestamp (Jan 15 10:00:00) into full ISO 8601 format, ready for analysis or ingestion into other tools.

Interactive Mode

Run kelora without any arguments to enter interactive mode—a readline-based REPL where you can type commands without worrying about shell quoting:

kelora

This is especially helpful on Windows where command-line quoting is notoriously difficult. Features include:

  • Shell-like parsing - Handles quotes properly without shell escaping issues
  • Automatic glob expansion - *.log and test?.json patterns work automatically
  • Command history - Press Up/Down arrows to recall previous commands
  • Easy cancellation - Ctrl-C returns to the prompt instead of exiting
  • Built-in help - Type :help for a quick reference
  • REPL commands - Commands like :help, :exit, :quit are prefixed with : to avoid conflicts with filenames

Example interactive session: 

Kelora Interactive Mode — :quit to exit, :help for help

kelora> -j examples/audit.jsonl -l error
{"timestamp":"2025-01-15T10:02:30Z","level":"ERROR","user_id":103,"email":"***","ms":45}
kelora> -f logfmt examples/*.log --stats
...
kelora> :exit

Get Help

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

Having trouble? See Debug Issues Systematically or the Common Errors Reference.

Next Steps

You've seen Kelora in action. Now learn how it actually works:

Follow this sequence to build your Kelora skills systematically:

  1. Tutorial: Basics (30 min) - Master input formats (-f, -j), display options (-k, -b, -c), level filtering (-l, -L), and output formats (-F, -J). Learn what events are and how to work with them.

  2. Tutorial: Introduction to Rhai (20 min) - Learn to write filter expressions and simple transforms. Understand how to access event fields, use conditionals, and convert types safely.

  3. Tutorial: Working with Time (15 min) - Handle timestamps, filter by time ranges, and work with timezones.

  4. Tutorial: Advanced Scripting (30 min) - Master complex transformations, window operations, and advanced patterns.

Jump to Solutions

Already know what you need? Check the How-To Guides for specific solutions like triaging errors, parsing custom formats, and tracking metrics.

Reference