Skip to content

Quickstart

Get Kelora running in 5 minutes with three commands.

Installation

Download the latest release from GitHub, extract it and put it on your PATH. 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: 7746 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): 2025-01-15T10:00:00+00:00 to 2025-01-15T10:00:35+00:00 (35s)
Output time span (after filtering): 2025-01-15T10:00:15+00:00 to 2025-01-15T10:00:28+00:00 (13s)
Levels seen: ERROR,INFO,WARN
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 were present in the log.

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":"2025-01-15T10:00:15+00:00","level":"ERROR","msg":"Payment timeout","duration":"5s","gateway":"stripe","order":"1234"}
{"ts":"2025-01-15T10:00:22+00:00","level":"ERROR","msg":"Gateway unreachable","host":"stripe.com"}
{"ts":"2025-01-15T10:00:25+00:00","level":"ERROR","msg":"Rate limit exceeded","endpoint":"/charge","limit":"100","service":"payment-api","window":"60s"}
{"ts":"2025-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.

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