TabalystPRODUCTAvailable
Tabalyst Report
The product behind the four formats: demo, outputs, batches and Python.
Tabalyst Report · JSONLAvailable
A log is never clean. Tabalyst tells you which lines broke.
Tabalyst Report is an open-source tool that turns a data file into an interactive HTML report and a JSON profile, on your machine. Given a JSONL log with a few broken lines, it reports the valid records and tells you exactly which lines it left out, or stops if you prefer.
tabalyst report web-events.jsonl
Analyzed 300 records and 14 fields in 1 dataset.
Report: web-events.report.html
In the report: excluded records, lines 121, 201, 251
tabalyst report web-events.jsonl --config strict.json
Record 121 (line 121) of web-events.jsonl is not valid JSON (Expecting value at column 41).
strict.json: {"scan": {"errors": {"policy": "strict"}}}
Real output of tabalyst 0.6.0, paths shortened.
One clear chain · three steps
From log file to a view you can use.
One record per line. Tabalyst Report parses each line on its own, reports the valid ones and lists the lines it left out.
JSONL FILE
Your log
A few lines are cut short or are not records at all. The file is read locally, as a stream.
LINE CHECK
Tabalyst Report
Each line is parsed on its own. A line that is not a valid JSON object is excluded and counted. Blank lines are ignored.
TWO DELIVERABLES
Human + machine
An interactive report for people, a structured profile for your tools. The report says it is partial and lists the lines left out.
By default broken lines are excluded and listed. Set the error policy to strict and the run stops at the first one, naming it.
Schematic view of the example log web-events.jsonl. Counts and line numbers come from its real report.
Format
Where logs get tricky
- 01 / BROKEN LINES
Lines that are not records
A truncated write, a stray message, an array instead of an object, a repeated key, a line that is too long. Each is excluded and counted. Blank lines are ignored.
- 02 / NESTING
Records inside records
The lines form one dataset, $[]. Nested objects and arrays become columns named by their path, as for JSON: user.country, tags[].
- 03 / PARTIAL
A report that must say so
When lines were left out, the report is partial. It lists them with their physical line numbers, so you know how far to trust the counts.
The idea
Simple. Clear. Smart.
Simple. Clear. Smart.
Simple
One command for a .jsonl or .ndjson file: tabalyst report file.jsonl. No setting is needed to get a report of the valid lines.
Clear
Every excluded line is listed in the report with its line number, in an issue called excluded records. Nothing is dropped silently.
Smart
The default is tolerant, which suits real logs. Set the error policy to strict and the run stops at the first broken line, naming it.
JSONL in the docs ↗
Outputs
What you get
Tabalyst Report writes three files beside the source: events.report.html, an interactive report for people; events.report.json, a structured profile for code; and executions.json, the history of successful runs.
When lines were excluded, the report says it is partial and lists them with their physical line numbers in its excluded records issue.
Proof
See a real JSONL report
A synthetic web event log of 300 valid records and three broken lines: an event cut short, an array and a line of plain text. The report analyzes the 300 records and lists lines 121, 201 and 251.
- Source
- JSONL
- Records
- 300
- Fields
- 14
- Excluded lines
- 3
Run it
Run it on your file
Tabalyst Report is open source and runs on your machine. It needs Python 3.11 or later.
- 1 · Install
pip install tabalyst# Also updates it: Tabalyst changes often
- 2 · Report the valid lines
tabalyst report events.jsonl# Broken lines are excluded and listed in the report
- 3 · Or stop at the first broken line
tabalyst report events.jsonl --config strict.json# strict.json: {"scan": {"errors": {"policy": "strict"}}}
import tabalyst # Report the valid lines; broken ones are listed in the reportbatch = tabalyst.generate_reports(["events.jsonl"], output_dir="reports") # Stop at the first broken line: batch.failures names it.# strict.json: {"scan": {"errors": {"policy": "strict"}}}batch = tabalyst.generate_reports( ["events.jsonl"], output_dir="reports", config_path="strict.json",)print(batch.succeeded)
The documentation covers JSONL in the JSON guide ↗, since both formats share their settings.
Scope, not hype
What to know before you start
- A file without any record line is an error.
- A line is read as UTF-8 and parsed as a whole, up to a configurable length. Compressed or non-UTF-8 files are not read.
- Reports read files as a stream, with memory bounded by configurable limits. No throughput is promised, and no benchmark of Tabalyst Report is published.
- A report with excluded lines is partial: read its excluded records issue before relying on counts.
The known limitations ↗ list the rest.
Your next log file
Know which lines broke.
Install Tabalyst, point it at a JSONL file and open the report.