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¶

1. Parse and display structured logs¶

CommandLog Data

kelora -j examples/simple_json.jsonl --take 5

timestamp='2024-01-15T10:00:00Z' level='INFO' message='Application started' service='api'
  version='1.2.3'
timestamp='2024-01-15T10:00:05Z' level='DEBUG' message='Loading configuration' service='api'
  config_file='/etc/app/config.yml'
timestamp='2024-01-15T10:00:10Z' level='INFO' message='Connection pool initialized'
  service='database' max_connections=50
timestamp='2024-01-15T10:01:00Z' level='WARN' message='High memory usage detected' service='api'
  memory_percent=85
timestamp='2024-01-15T10:01:30Z' level='ERROR' message='Query timeout' service='database'
  query='SELECT * FROM users' duration_ms=5000

{"timestamp":"2024-01-15T10:00:00Z","level":"INFO","service":"api","message":"Application started","version":"1.2.3"}
{"timestamp":"2024-01-15T10:00:05Z","level":"DEBUG","service":"api","message":"Loading configuration","config_file":"/etc/app/config.yml"}
{"timestamp":"2024-01-15T10:00:10Z","level":"INFO","service":"database","message":"Connection pool initialized","max_connections":50}
{"timestamp":"2024-01-15T10:01:00Z","level":"WARN","service":"api","message":"High memory usage detected","memory_percent":85}
{"timestamp":"2024-01-15T10:01:30Z","level":"ERROR","service":"database","message":"Query timeout","query":"SELECT * FROM users","duration_ms":5000}
{"timestamp":"2024-01-15T10:02:00Z","level":"INFO","service":"api","message":"Request received","method":"GET","path":"/api/users","user_id":123}
{"timestamp":"2024-01-15T10:02:15Z","level":"DEBUG","service":"cache","message":"Cache hit","key":"user:123","ttl":3600}
{"timestamp":"2024-01-15T10:02:30Z","level":"INFO","service":"api","message":"Response sent","status":200,"duration_ms":45}
{"timestamp":"2024-01-15T10:03:00Z","level":"WARN","service":"auth","message":"Failed login attempt","username":"admin","ip":"192.168.1.100"}
{"timestamp":"2024-01-15T10:03:30Z","level":"ERROR","service":"auth","message":"Account locked","username":"admin","attempts":5}
{"timestamp":"2024-01-15T10:04:00Z","level":"INFO","service":"scheduler","message":"Cron job started","job":"backup","schedule":"0 2 * * *"}
{"timestamp":"2024-01-15T10:05:00Z","level":"DEBUG","service":"scheduler","message":"Running backup script","script":"/usr/local/bin/backup.sh"}
{"timestamp":"2024-01-15T10:10:00Z","level":"INFO","service":"scheduler","message":"Backup completed","size_mb":1024,"duration_ms":300000}
{"timestamp":"2024-01-15T10:15:00Z","level":"CRITICAL","service":"disk","message":"Disk space critical","partition":"/var","free_gb":0.5}
{"timestamp":"2024-01-15T10:16:00Z","level":"ERROR","service":"api","message":"Service unavailable","reason":"disk space"}
{"timestamp":"2024-01-15T10:17:00Z","level":"WARN","service":"monitoring","message":"Alert sent","channel":"slack","severity":"high"}
{"timestamp":"2024-01-15T10:20:00Z","level":"INFO","service":"admin","message":"Disk cleanup initiated","target":"/var/log"}
{"timestamp":"2024-01-15T10:25:00Z","level":"INFO","service":"admin","message":"Cleanup completed","freed_gb":10}
{"timestamp":"2024-01-15T10:26:00Z","level":"INFO","service":"api","message":"Service resumed","downtime_seconds":600}
{"timestamp":"2024-01-15T10:30:00Z","level":"DEBUG","service":"health","message":"Health check passed","endpoints":["api","database","cache"]}

Parse JSON logs and display them in a readable format.

2. Filter events and select fields¶

CommandLog Data

kelora -j examples/simple_json.jsonl -l error -k timestamp,service,message

timestamp='2024-01-15T10:01:30Z' service='database' message='Query timeout'
timestamp='2024-01-15T10:03:30Z' service='auth' message='Account locked'
timestamp='2024-01-15T10:16:00Z' service='api' message='Service unavailable'

{"timestamp":"2024-01-15T10:00:00Z","level":"INFO","service":"api","message":"Application started","version":"1.2.3"}
{"timestamp":"2024-01-15T10:00:05Z","level":"DEBUG","service":"api","message":"Loading configuration","config_file":"/etc/app/config.yml"}
{"timestamp":"2024-01-15T10:00:10Z","level":"INFO","service":"database","message":"Connection pool initialized","max_connections":50}
{"timestamp":"2024-01-15T10:01:00Z","level":"WARN","service":"api","message":"High memory usage detected","memory_percent":85}
{"timestamp":"2024-01-15T10:01:30Z","level":"ERROR","service":"database","message":"Query timeout","query":"SELECT * FROM users","duration_ms":5000}
{"timestamp":"2024-01-15T10:02:00Z","level":"INFO","service":"api","message":"Request received","method":"GET","path":"/api/users","user_id":123}
{"timestamp":"2024-01-15T10:02:15Z","level":"DEBUG","service":"cache","message":"Cache hit","key":"user:123","ttl":3600}
{"timestamp":"2024-01-15T10:02:30Z","level":"INFO","service":"api","message":"Response sent","status":200,"duration_ms":45}
{"timestamp":"2024-01-15T10:03:00Z","level":"WARN","service":"auth","message":"Failed login attempt","username":"admin","ip":"192.168.1.100"}
{"timestamp":"2024-01-15T10:03:30Z","level":"ERROR","service":"auth","message":"Account locked","username":"admin","attempts":5}
{"timestamp":"2024-01-15T10:04:00Z","level":"INFO","service":"scheduler","message":"Cron job started","job":"backup","schedule":"0 2 * * *"}
{"timestamp":"2024-01-15T10:05:00Z","level":"DEBUG","service":"scheduler","message":"Running backup script","script":"/usr/local/bin/backup.sh"}
{"timestamp":"2024-01-15T10:10:00Z","level":"INFO","service":"scheduler","message":"Backup completed","size_mb":1024,"duration_ms":300000}
{"timestamp":"2024-01-15T10:15:00Z","level":"CRITICAL","service":"disk","message":"Disk space critical","partition":"/var","free_gb":0.5}
{"timestamp":"2024-01-15T10:16:00Z","level":"ERROR","service":"api","message":"Service unavailable","reason":"disk space"}
{"timestamp":"2024-01-15T10:17:00Z","level":"WARN","service":"monitoring","message":"Alert sent","channel":"slack","severity":"high"}
{"timestamp":"2024-01-15T10:20:00Z","level":"INFO","service":"admin","message":"Disk cleanup initiated","target":"/var/log"}
{"timestamp":"2024-01-15T10:25:00Z","level":"INFO","service":"admin","message":"Cleanup completed","freed_gb":10}
{"timestamp":"2024-01-15T10:26:00Z","level":"INFO","service":"api","message":"Service resumed","downtime_seconds":600}
{"timestamp":"2024-01-15T10:30:00Z","level":"DEBUG","service":"health","message":"Health check passed","endpoints":["api","database","cache"]}

Show only errors with specific fields.

3. Track metrics across events¶

CommandLog Data

kelora -j examples/simple_json.jsonl \
  -e 'track_count(e.level)' \
  --stats-only --metrics

kelora: Tracked metrics:
CRITICAL     = 1
DEBUG        = 4
ERROR        = 3
INFO         = 9
WARN         = 3

kelora: Stats:
Lines processed: 20 total, 0 filtered (0.0%), 0 errors (0.0%)
Events created: 20 total, 20 output, 0 filtered (0.0%)
Throughput: 9708 lines/s in 2ms
Timestamp: timestamp (auto-detected) - 20/20 parsed (100.0%).
Time span: 2024-01-15T10:00:00+00:00 to 2024-01-15T10:30:00+00:00 (30m)
Levels seen: CRITICAL,DEBUG,ERROR,INFO,WARN
Keys seen: attempts,channel,config_file,downtime_seconds,duration_ms,endpoints,free_gb,freed_gb,ip,job,key,level,max_connections,memory_percent,message,method,partition,path,query,reason,schedule,script,service,severity,size_mb,status,target,timestamp,ttl,user_id,username,version

{"timestamp":"2024-01-15T10:00:00Z","level":"INFO","service":"api","message":"Application started","version":"1.2.3"}
{"timestamp":"2024-01-15T10:00:05Z","level":"DEBUG","service":"api","message":"Loading configuration","config_file":"/etc/app/config.yml"}
{"timestamp":"2024-01-15T10:00:10Z","level":"INFO","service":"database","message":"Connection pool initialized","max_connections":50}
{"timestamp":"2024-01-15T10:01:00Z","level":"WARN","service":"api","message":"High memory usage detected","memory_percent":85}
{"timestamp":"2024-01-15T10:01:30Z","level":"ERROR","service":"database","message":"Query timeout","query":"SELECT * FROM users","duration_ms":5000}
{"timestamp":"2024-01-15T10:02:00Z","level":"INFO","service":"api","message":"Request received","method":"GET","path":"/api/users","user_id":123}
{"timestamp":"2024-01-15T10:02:15Z","level":"DEBUG","service":"cache","message":"Cache hit","key":"user:123","ttl":3600}
{"timestamp":"2024-01-15T10:02:30Z","level":"INFO","service":"api","message":"Response sent","status":200,"duration_ms":45}
{"timestamp":"2024-01-15T10:03:00Z","level":"WARN","service":"auth","message":"Failed login attempt","username":"admin","ip":"192.168.1.100"}
{"timestamp":"2024-01-15T10:03:30Z","level":"ERROR","service":"auth","message":"Account locked","username":"admin","attempts":5}
{"timestamp":"2024-01-15T10:04:00Z","level":"INFO","service":"scheduler","message":"Cron job started","job":"backup","schedule":"0 2 * * *"}
{"timestamp":"2024-01-15T10:05:00Z","level":"DEBUG","service":"scheduler","message":"Running backup script","script":"/usr/local/bin/backup.sh"}
{"timestamp":"2024-01-15T10:10:00Z","level":"INFO","service":"scheduler","message":"Backup completed","size_mb":1024,"duration_ms":300000}
{"timestamp":"2024-01-15T10:15:00Z","level":"CRITICAL","service":"disk","message":"Disk space critical","partition":"/var","free_gb":0.5}
{"timestamp":"2024-01-15T10:16:00Z","level":"ERROR","service":"api","message":"Service unavailable","reason":"disk space"}
{"timestamp":"2024-01-15T10:17:00Z","level":"WARN","service":"monitoring","message":"Alert sent","channel":"slack","severity":"high"}
{"timestamp":"2024-01-15T10:20:00Z","level":"INFO","service":"admin","message":"Disk cleanup initiated","target":"/var/log"}
{"timestamp":"2024-01-15T10:25:00Z","level":"INFO","service":"admin","message":"Cleanup completed","freed_gb":10}
{"timestamp":"2024-01-15T10:26:00Z","level":"INFO","service":"api","message":"Service resumed","downtime_seconds":600}
{"timestamp":"2024-01-15T10:30:00Z","level":"DEBUG","service":"health","message":"Health check passed","endpoints":["api","database","cache"]}

Count events by log level.

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

Next Steps¶

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

Tutorial: Basics - Comprehensive 30-minute guide explaining input formats (-f, -j), display options (-k, -b, -c), level filtering (-l, -L), output formats (-F, -J), and common workflows
Tutorial: Scripting Transforms - Write custom filters and transformations with Rhai
How-To Guides - Solve specific problems like finding errors, parsing custom formats, and tracking metrics

For format conversion, time filtering, metrics tracking, and more advanced features, start with the Tutorial: Basics.