Record view: make structured logs as readable as hl

[plaffitt]

Thanks again for the record view (#800) and json_view (#804): we now use it as our default for all our clusters. After a few days on it, we compared it with hl on the same logs: a controller-runtime operator logging zap JSON. hl is still noticeably easier to read. Below is everything we found, ordered by how much it would help. Every item keeps one display row per source line, so follow, search, markers and the warn/error filter are unaffected.

Same 20 lines, hl first, then Sofka 0.31.5 in record view:

(screenshot: hl)

(screenshot: Sofka record view)

1. Keep the fields in the order the application wrote them

Sofka sorts the fields alphabetically. serde_json is built without its preserve_order feature, so as_object() iterates a BTreeMap (render_record, src/app/logs.rs). The order a developer chose is usually meaningful: the most identifying field comes first.

hl:    Starting manager › process=reconciler version=3.0.0-alpha.3 revision=3ceaed3 built=...
sofka: Starting manager built=... goarch=amd64 goos=linux goversion=go1.27.1 logger=setup process=reconciler revision=3ceaed3 version=3.0.0-a

On a narrow terminal, the fields that matter (process, version) end up cut off at the right edge. Enabling preserve_order would fix it (and the pretty view would also show the keys in their original order).

2. Separate the message from the fields

The message is free text with spaces, so nothing tells where it ends and the fields begin:

sofka: Attempting to acquire leader lease... lock=kuik-system/reconciler.kuik.enix.io logger=leaderelection
hl:    leaderelection: Attempting to acquire leader lease... › lock=kuik-system/reconciler.kuik.enix.io

hl puts a dim › between them. Any distinct separator would do.

3. Show the logger name before the message

zap writes the logger name under logger (setup, leaderelection, controller-runtime.metrics, events). hl shows it as a prefix in its own color (setup: Loaded global config). Sofka prints it as an ordinary field, among the others (logger=setup), often at the end of the line. Promoting it next to the message, like the time, level and message keys already are, makes it easy to scan which component logged a line. Candidate keys: logger (zap, logr), name (pino, bunyan), component.

4. Style each part of the row instead of coloring the whole row

render_record returns a plain String, and the row gets one color from its severity. hl styles each part:

• the message in bright or bold text, so it stands out;
• the keys dimmed, the values in normal text;
• the time dimmed;
• the separators (=, ›) dimmed.

This needs render_record to return styled spans instead of a String, so it is the largest change here. It is also the one that makes the biggest difference.

5. Color the level, not the whole row

A DEBUG row is entirely dimmed gray (the became leader line in the screenshot), which makes its content the hardest to read on screen. hl colors only the level badge ([DBG], [INF], [WRN], [ERR]) and leaves the message readable. Coloring the level token, plus the whole row only for WARN and ERROR (or making the row tint optional), would keep severities visible without hurting the text.

6. Color values by type

hl gives booleans, numbers, null and quoted strings their own colors: secure=false stands out at once. In Sofka every value has the color of the row.

7. Flatten nested objects

A nested object is printed as compact JSON, which is long and noisy:

sofka: object={"apiVersion":"coordination.k8s.io/v1","kind":"Lease","name":"reconciler.kuik.enix.io",...
hl:    object.kind=Lease object.namespace=kuik-system object.name=reconciler.kuik.enix.io

Flattening objects into dotted keys keeps them on the row and readable. Arrays can stay compact JSON.

8. A shorter time

2026-10-08T15:00:20.444Z takes 24 columns on every row; hl's Oct 08 15:00:20.444 takes 19, and the date is rarely needed in a live tail. t already hides the time entirely; a format option would sit between the two, for example:

[logs]
record_time_format = "%b %d %H:%M:%S%.3f"  # strftime; the default keeps the RFC 3339 text
record_time_zone = "local"                 # or "utc"

The time is kept as the application wrote it when it is a string, so this would apply only when it parses as RFC 3339.

9. Quote keys that contain spaces

controller-runtime logs a key with a space: worker count. record_value quotes ambiguous values, but keys are written as is, so worker count=1 reads as a bare word worker followed by count=1. Quoting a key that contains whitespace, = or " ("worker count"=1) would remove the ambiguity. hl does not do it either; it would be an easy improvement over both.

Smaller points

• Fixed-width short level names (INF, DBG, WRN, ERR) would save 2 columns per row and align the messages. This is a matter of taste: a config option or the current names are both fine.

Implementation options

Two ways to get there:

• Improve Sofka's own renderer, item by item. Each item above is small on its own, except styled spans (4).
• Reuse hl's formatter in-process. hl is written in Rust (MIT) and its lib.rs exports Parser, RecordFormatter::format_record and Theme. The formatter writes one line with ANSI styles, which the log view already maps. Running in-process avoids most of the problems you listed for an external formatter: no child process, no buffering, one output line per input line (with hl's multi-line expansion turned off). The blockers:
  • hl is not on crates.io (the hl name belongs to another, older crate), and a crates.io package cannot depend on a git repository. hl would first need to publish a library crate.
  • The crate pulls in the CLI's dependencies (clap, capnp, pager, notify, config...): about 80 in total.
  • The library API serves hl's own binary and is not documented as stable.

We lean towards the first option, but you know the codebase better. If the second one appeals to you, we can ask hl's maintainer about a lighter library crate.

If some of these are welcome, we're happy to help: test builds, or a PR on the easy ones (1, 2, 9).

[nklmilojevic]

Thanks for this, really thorough writeup and the side-by-side made it easy to check! Most of it is in. I'll go with the first option and improve the renderer here.

In as proposed

• 2, the › separator between message and fields.
• 9, quote keys that contain whitespace, = or ".
• 5, color the level token, keep the whole-row tint only for WARN and ERROR. DEBUG rows being the hardest to read is a bug, not a style choice.
• 6, values colored by type. This falls out of 4.
• 8, as an opt-in config. The default stays RFC 3339.

In, with changes

• 1, keep field order, but not through serde_json's preserve_order. Cargo features unify across the whole build, so that flips key order for every JSON map sofka touches (plugin and catalog JSON, columns, Argo/Flux handling, the pretty view) and makes every Value heavier. Parse log records into an order-preserving map locally instead (indexmap with its serde feature, or a small visitor). Nested objects need to keep order too, since 7 builds on it.
• 3, promote logger only. name can't be a logger key - controller-runtime logs "namespace":...,"name":... for the reconciled object, so promoting it would hide exactly what you want to see in operator logs. component is too often a plain field, so I'd skip it too.
• 4, render_record returns segments tagged by kind (time, level, logger, message, key, value by type, separator) and the theme maps them to styles. No ANSI baked into the cached string. Search highlighting and the warn/error filter keep working on the plain text.
• 7, flatten into dotted keys with a depth/length cap so one huge object can't eat the row. Arrays stay compact JSON.

Not doing

• hl in-process. Not on crates.io, ~80 extra deps and an unstable API. Agree with your lean.
• Short level names. The padded 5-wide names already align the messages, 2 columns doesn't justify a config option.

Order I'd like: (1, 2, 3, 9) -> (4, 5, 6) -> 7 -> 8, one PR each. Happy to take your PR on 1, 2 and 9 - just go the local ordered map route for 1, not preserve_order :)

[nklmilojevic]

Tracking the agreed scope in #845.

[nklmilojevic]

I started working on others, are you taking 1, 2 and 9?