Kelora¶
Turn messy logs into structured data.
Kelora is a scriptable log processor for the command line. Parse structured or semi-structured logs, filter with complex logic, and analyze streams using embedded Rhai scripting—all in a single binary.
Kelora is AI-generated; see Development Approach.
Installation¶
Or download a signed binary: Apple Silicon | Intel
Binary:
curl -LO https://github.com/dloss/kelora/releases/latest/download/kelora-x86_64-unknown-linux-musl.tar.gz
tar xzf kelora-x86_64-unknown-linux-musl.tar.gz
sudo mv kelora /usr/local/bin/
Debian/Ubuntu: download .deb, then:
Fedora/RHEL: download .rpm, then:
ARM: see releases for aarch64 binaries.
Download kelora-x86_64-pc-windows-msvc.zip, extract, and add to PATH.
See all releases for ARM Linux, FreeBSD, OpenBSD, and more.
When to Use Kelora¶
Reach for Kelora when:
- You're chaining tools - Replace
grep | awk | jq | custom-script.pywith one command - You're parsing custom formats - Use simple one-liners for non-standard logs (no regex required!) and output clean JSON
- Logs have embedded structure - Extract JSON or key-value pairs buried in text lines
- You need stateful logic - Count errors per service, tracking sessions, windowed metrics
- Fields are inconsistent - Let missing data or errors be handled gracefully, with summary reports at the end
Kelora prioritizes flexibility over raw speed. It shines for exploratory analysis on small to medium log files. For larger files, pre-filter with jq, ripgrep, or qsv -- Kelora plays well with all of them.
Examples¶
1. Filter & Convert (The Basics)¶
Scenario: Filter a Logfmt file for slow requests and output clean JSON.
ts=2024-07-17T11:59:40Z level=INFO method=GET path=/docs status=200 latency_ms=280
ts=2024-07-17T11:59:55Z level=INFO method=POST path=/checkout status=200 latency_ms=950
ts=2024-07-17T12:00:01Z level=INFO method=GET path=/docs status=200 latency_ms=320
ts=2024-07-17T12:00:04Z level=INFO method=POST path=/checkout status=200 latency_ms=1450
ts=2024-07-17T12:00:05Z level=ERROR method=POST path=/checkout status=502 latency_ms=2100
ts=2024-07-17T12:00:07Z level=WARN method=GET path=/billing status=200 latency_ms=900
2. Modify & Anonymize (Scripting)¶
Scenario: Mask user emails for privacy and convert milliseconds to seconds before printing.
kelora -j examples/audit.jsonl \
--exec 'e.email = "***"; e.duration_sec = e.ms / 1000.0;' \
--keys timestamp,user_id,email,duration_sec
timestamp='2024-01-15T10:00:00Z' user_id='usr_123' email='***' duration_sec=1.25
timestamp='2024-01-15T10:05:00Z' user_id='usr_456' email='***' duration_sec=0.34
timestamp='2024-01-15T10:10:00Z' user_id='usr_789' email='***' duration_sec=2.1
timestamp='2024-01-15T10:15:00Z' user_id='usr_234' email='***' duration_sec=0.89
{"timestamp":"2024-01-15T10:00:00Z","user_id":"usr_123","email":"alice@example.com","action":"login","ms":1250}
{"timestamp":"2024-01-15T10:05:00Z","user_id":"usr_456","email":"bob@company.org","action":"view_document","ms":340}
{"timestamp":"2024-01-15T10:10:00Z","user_id":"usr_789","email":"charlie@domain.net","action":"update_profile","ms":2100}
{"timestamp":"2024-01-15T10:15:00Z","user_id":"usr_234","email":"diana@email.com","action":"download_report","ms":890}
3. Pattern Discovery (Template Mining)¶
Scenario: You have thousands of error messages that differ only in IPs, emails, and UUIDs. Find the underlying patterns automatically.
{"message":"Failed to connect to 192.168.1.10","service":"api","level":"ERROR"}
{"message":"Failed to connect to 10.0.5.23","service":"web","level":"ERROR"}
{"message":"Failed to connect to 172.16.88.5","service":"worker","level":"ERROR"}
{"message":"User alice@example.com sent invalid request","service":"api","level":"WARN"}
{"message":"User bob@test.org sent invalid request","service":"web","level":"WARN"}
{"message":"Timeout on request a1b2c3d4-e5f6-7890-1234-567890abcdef","service":"api","level":"ERROR"}
{"message":"Timeout on request f1e2d3c4-b5a6-9807-5432-098765fedcba","service":"worker","level":"ERROR"}
{"message":"Failed to connect to 203.0.113.42","service":"api","level":"ERROR"}
{"message":"User charlie@example.net sent invalid request","service":"api","level":"WARN"}
{"message":"Timeout on request 11111111-2222-3333-4444-555555555555","service":"web","level":"ERROR"}
The Drain algorithm clusters similar messages and replaces variable parts with placeholders like <ipv4>, <email>, <uuid>. No regex required.
Advanced Features¶
Beyond basic filtering and conversion, Kelora includes specialized functions that solve problems you'd otherwise need multiple tools or custom scripts for:
-
Extract JSON from text - Pull structured data from unstructured lines
e.data = e.line.extract_json() -
Deep flattening - Fan out nested arrays to flat records
emit_each(e.get_path("data.orders", [])) -
Pattern normalization - Group errors by replacing IPs, UUIDs, emails with placeholders
e.error_pattern = e.message.normalized() -
Deterministic sampling - Consistent sampling across log rotations
--filter 'e.request_id.bucket() % 10 == 0' -
JWT parsing - Extract claims without verification
e.token.parse_jwt().claims.sub -
Cryptographic pseudonymization - Privacy-preserving anonymization with HMAC
e.anon_user = pseudonym(e.email, "users")
See Power-User Techniques for real-world examples.
Get Started¶
→ Quickstart (5 minutes) - Install and run your first commands
→ Tutorial: Basics (30 minutes) - Learn input formats, filtering, and output
→ How-To Guides - Solve specific problems (including debugging)
For deeper understanding, see Concepts. For complete reference, see Glossary, Functions, Formats, and CLI options.
On-call?
Jump to Incident Response Playbooks for copy-paste commands covering latency spikes, error surges, auth failures, and more.
License¶
Kelora is open source software licensed under the MIT License.
Development Approach¶
Kelora is an experiment in agentic AI development using vibe-coding. AI agents generate all implementation and tests; I steer requirements but do not write or review code. Validation relies on a large automated test suite plus Rust security tools (cargo audit and cargo deny). Review the Security Policy before production use.
This is a spare-time, single-developer project, so support and updates are best-effort.