Getting Started: Input, Display & Filtering¶
Master the essential commands for reading logs, controlling display output, and filtering by log level. This tutorial covers the foundation you'll use in every Kelora workflow.
What You'll Learn¶
- Specify input formats with
-fand-j - Control what fields are displayed with
-b,-c,-k, and-K - Filter events by log level with
-land-L - Export data in different formats with
-Fand-J - Combine options for common workflows
About This Tutorial¶
In the Quickstart, you ran three commands to see Kelora in action. Now we'll teach you what each flag means, how they combine, and when to use them. By the end, you'll understand the building blocks for any Kelora workflow.
Prerequisites¶
- Kelora installed and in your PATH
- Basic command-line familiarity
Sample Data¶
Commands below use example files from the repository:
examples/simple_json.jsonl— JSON-formatted application logs with multiple services
If you cloned the project, run commands from the repository root.
Part 1: Input Formats (-f, -j)¶
Explicit Format Selection Required¶
You've seen -j in the Quickstart to read JSON logs. Let's understand what this flag really means and what other formats Kelora supports.
Important: Kelora does NOT auto-detect format based on filename. The default is -f line (plain text). You must specify the format explicitly.
Let's see what happens without specifying the format:
Notice it treats the entire JSON line as plain text (line='...'). Now with -j:
Three ways to read JSON logs:
kelora -f json examples/simple_json.jsonl # Explicit format
kelora -j examples/simple_json.jsonl # -j is shortcut for -f json
kelora -f auto examples/simple_json.jsonl # Auto-detect by examining content
Key Points:
- ✅
-f autodetects format by examining the content (not filename) - ❌ Kelora does NOT look at file extensions (
.jsonl,.log,.csv) - ✅ Default is always
-f lineunless you specify otherwise - ✅ Best practice: Be explicit with
-jfor JSON
Common Input Formats¶
-f json # JSON lines (or use -j shortcut)
-f logfmt # key=value format
-f combined # Apache/Nginx access logs
-f syslog # Syslog format (RFC3164/RFC5424)
-f csv # CSV with header
-f tsv # Tab-separated values
-f line # Plain text (default)
-f auto # Auto-detect by content
Part 2: Understanding the Default Display¶
Let's examine what Kelora shows by default:
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
The default output format shows:
- ✅ Field names and values in
key='value'format - ✅ Automatic wrapping - long events wrap with indentation
- ✅ Colors (when terminal supports it)
- ✅ Smart ordering - timestamp, level, message first, then others alphabetically
Key observations:
- Strings are quoted (
'Application started') - Numbers are not quoted (
max_connections=50) - Fields wrap to next line when too long
- Each event is separated by a blank line
- Field names are highlighted in color for better readability
Part 3: Display Modifiers (-b, -c, -k, -K)¶
Brief Mode (-b) - Values Only¶
Omit field names, show only values for compact output:
Use -b when: You want compact, grep-friendly output.
Core Fields (-c) - Essentials Only¶
Show only timestamp, level, and message:
Use -c when: You want to focus on the essentials, hiding extra metadata.
Select Fields (-k) - Choose What to Show¶
Choose exactly which fields to show (and in what order):
Pro tip: Fields appear in the order you specify!
Exclude Fields (-K) - Hide Sensitive Data¶
Remove specific fields (like passwords, tokens, or verbose metadata):
Use -K when: Hiding sensitive data (passwords, API keys) or reducing noise.
Part 4: Level Filtering (-l, -L)¶
Include Levels (-l) - Show Only Specific Log Levels¶
Filter to show only errors and warnings:
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:03:00Z' level='WARN' message='Failed login attempt' service='auth'
username='admin' ip='192.168.1.100'
timestamp='2024-01-15T10:03:30Z' level='ERROR' message='Account locked' service='auth'
username='admin' attempts=5
timestamp='2024-01-15T10:16:00Z' level='ERROR' message='Service unavailable' service='api'
reason='disk space'
timestamp='2024-01-15T10:17:00Z' level='WARN' severity='high' message='Alert sent'
service='monitoring' channel='slack'
Common patterns:
kelora -j app.log -l error # Errors only
kelora -j app.log -l error,warn,critical # Problems only (case-insensitive)
kelora -j app.log -l info # Application flow (skip debug noise)
Exclude Levels (-L) - Hide Debug Noise¶
Remove verbose log levels:
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:03:00Z' level='WARN' message='Failed login attempt' service='auth'
username='admin' ip='192.168.1.100'
timestamp='2024-01-15T10:03:30Z' level='ERROR' message='Account locked' service='auth'
username='admin' attempts=5
timestamp='2024-01-15T10:15:00Z' level='CRITICAL' message='Disk space critical' service='disk'
partition='/var' free_gb=0.5
Use -L when: You want to exclude chatty debug/trace output.
Part 5: Output Formats (-F, -J)¶
The default key='value' format is great for reading, but sometimes you need machine-readable output.
JSON Output (-F json or -J)¶
Use JSON when: Piping to jq, saving to file, or integrating with other tools.
CSV Output (-F csv)¶
Perfect for spreadsheet export:
Use CSV when: Exporting to Excel, Google Sheets, or data analysis tools.
Logfmt Output (-F logfmt)¶
Use logfmt when: You want parseable output that's also human-readable.
Inspect Output (-F inspect) - Debug with Types¶
Use inspect when: Debugging type mismatches or understanding field types.
No Output (-F none) - Stats Only¶
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: 11441 lines/s in 1ms
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
Use -F none --stats when: You want to analyze log structure without seeing the events.
Part 6: Practical Combinations¶
Exercise 1: Find Errors, Show Essentials¶
Show only errors with just timestamp, service, and message:
Exercise 2: Export Problems to CSV¶
Export warnings and errors to CSV for Excel analysis:
timestamp,level,service,message
2024-01-15T10:01:00Z,WARN,api,High memory usage detected
2024-01-15T10:01:30Z,ERROR,database,Query timeout
2024-01-15T10:03:00Z,WARN,auth,Failed login attempt
2024-01-15T10:03:30Z,ERROR,auth,Account locked
2024-01-15T10:16:00Z,ERROR,api,Service unavailable
2024-01-15T10:17:00Z,WARN,monitoring,Alert sent
Exercise 3: Compact View Without Debug¶
Brief output excluding debug noise:
2024-01-15T10:00:00Z INFO Application started api 1.2.3
2024-01-15T10:00:10Z INFO Connection pool initialized database 50
2024-01-15T10:01:00Z WARN High memory usage detected api 85
2024-01-15T10:01:30Z ERROR Query timeout database SELECT * FROM users 5000
2024-01-15T10:02:00Z INFO Request received api GET /api/users 123
Real-World Patterns¶
Here are some patterns you'll use frequently in practice:
# Stream processing (tail -f, kubectl logs, etc.)
kubectl logs -f deployment/api | kelora -f json -l error
# Multiple files - track which files have errors
kelora -f json logs/*.log --metrics \
--exec 'if e.level == "ERROR" { track_count(meta.filename) }'
# Time-based filtering
kelora -f combined access.log --since "1 hour ago" --until "10 minutes ago"
# Extract prefixes (Docker Compose, systemd, etc.)
docker compose logs | kelora --extract-prefix container -f json
# Auto-detect format and output brief values only
kelora -f auto mixed.log -k timestamp,level,message -b
# Custom timestamp formats
kelora -f line app.log --ts-format "%d/%b/%Y:%H:%M:%S" --ts-field timestamp
Quick Reference Cheat Sheet¶
Input Formats¶
-f json # JSON lines (or use -j shortcut)
-f logfmt # key=value format
-f combined # Apache/Nginx access logs
-f syslog # Syslog format
-f csv # CSV with header
-f line # Plain text (default)
-f auto # Auto-detect by content
Display Modifiers¶
-b # Brief: values only, no field names
-c # Core: timestamp + level + message only
-k level,msg # Keys: show only these fields (in this order)
-K password,ip # Exclude: hide these fields
Level Filtering¶
Output Formats¶
-F default # Pretty key='value' with colors (default)
-F json # JSON lines (or use -J shortcut)
-F csv # CSV with header
-F logfmt # Logfmt key=value
-F inspect # Debug with types
-F none # No output (use with --stats)
Understanding the Pipeline Order¶
Kelora processes your options in this order:
1. Read file (-f json, -j)
2. Filter levels (-l error, -L debug)
3. Select fields (-k, -K, -c)
4. Format output (-F csv, -J, -b)
5. Write output (stdout or -o file)
This means:
-lfilters happen before-k(you can filter on fields you won't see in output)-baffects display, not what gets filtered-F none --statsstill processes everything, just doesn't show events
Common Workflows¶
Error Analysis Pipeline¶
kelora -j app.log -l error -k timestamp,service,message -F csv -o errors.csv
# Filter → Select fields → Export to CSV → Save to file
Quick Scan (Hide Noise)¶
kelora -j app.log -L debug,trace -b --take 20
# Exclude verbose levels → Brief output → First 20 events
Investigation Mode (Full Detail)¶
kelora -j app.log -l warn,error,critical -K password,token
# Show problems → Hide sensitive data → Keep all other fields
Stats-Only Analysis¶
When to Use What¶
| Goal | Use | Example |
|---|---|---|
| Find errors fast | -l error |
kelora -j app.log -l error -c |
| Hide debug spam | -L debug,trace |
kelora -j app.log -L debug |
| Export to Excel | -F csv |
kelora -j app.log -F csv -o report.csv |
| Pipe to jq | -J |
kelora -j app.log -J \| jq '.level' |
| Quick scan | -b --take 20 |
kelora -j app.log -b --take 20 |
| Hide secrets | -K password,token |
kelora -j app.log -K password,apikey |
| See types | -F inspect |
kelora -j app.log -F inspect |
Next Steps¶
Once you're comfortable with these basics, continue to:
- Working with Time - Time filtering with
--sinceand--until - Scripting Transforms - Custom filters and transformations with Rhai
- Metrics and Tracking - Aggregate data with
track_*()functions - Parsing Custom Formats - Handle non-standard log formats