Implement richer, fully customizable logging; customizable timestamps #1

2026-08-07T16:07:59Z

LeoVasanko commented

2026-08-07 16:07:59 +00:00

@kanta.logemit handler for completely customizable logging output, with LogEvent structure and kanta.tty.Line helper to create colorized text and fixed width fields
configure_logging(diff=False) to disable diff display globally (supplementing per-transaction logdiff=False)
transaction(extra: Any = ...) for passing extra strings or custom metadata to logs
@kanta.clock to provide user controlled clock for deterministic database outputs
Added a demo script that shows basic functions, migrations, logfmt etc.

- `@kanta.logemit` handler for completely customizable logging output, with `LogEvent` structure and `kanta.tty.Line` helper to create colorized text and fixed width fields - `configure_logging(diff=False)` to disable diff display globally (supplementing per-transaction `logdiff=False`) - `transaction(extra: Any = ...)` for passing extra strings or custom metadata to logs - `@kanta.clock` to provide user controlled clock for deterministic database outputs - Added a demo script that shows basic functions, migrations, logfmt etc.

LeoVasanko added 24 commits 2026-08-07 16:07:59 +00:00

Add rich transaction log headers: extra metadata, logheader callback, header/diff toggles, green add paths 1e9f83c800

Tests for rich logging, apply ruff formatting f4e0c66907

Document transaction log headers: extra, logheader, toggles 450952cd64

Add feature demo app under demo/ 5b0d676175

Add @kanta.clock hook replacing the UTC clock for all record and snapshot timestamps 123e910873

Demo: deterministic clock, # section banners, .kantadb extension, raw record dump 8d9e948d27

Lazy clock reads; demo: auto-advancing +1h clock, module-level setup 5d66d423da

Demo: resolve user names from database state, kanta instances at top with stacked decorators 72944c9410

Demo: use the script itself as the migrations module ec08c185aa

Kanta colors log header parts: extra is a plain string, logheader callbacks receive pre-colored parts e0725c5738

Demo: plain-text custom header colored by Kanta, rename migration, str extras 1cd99aef01

Remove logheader callback feature; keep Kanta-colored extra string in default header 9e19a1bf21

Replace log dict toggles with logdiff kwarg and kanta.transaction.diff logger e42f81f44f

Per-transaction logdiff=False skips building and printing the diff body,
logging only the header. Globally, configure_logging(diff=False) disables
the kanta.transaction.diff child logger, which now carries all diff lines,
so applications can route or silence diffs separately from headers.

Add logemit event callbacks and kanta.tty terminal formatting 6eb9087863

All change-related output (transactions, bootstrap, migrations) is now
described by a mutable LogEvent carrying full state plus the preferred
logger and level, and dispatched through emit_event. @kanta.logemit
callbacks receive the event and decide what is logged where: falsy return
marks it handled, truthy passes it (possibly modified) down the chain,
with default_emit - Kanta's own formatting, now just another emitter - as
the fallback. Pretty header and diff lines are lazy event properties.

New kanta.tty module: Line builder (call to append content, .colorname
arms a palette color for the next call with automatic folded reset,
width/align padding), a mutable Colors palette storing bare SGR params
(0 clears, sequential last-wins stacking), and strip_ansi/displaywidth/pad
helpers that count wide chars and emoji correctly.

Fortify logging: no logging failure may break functionality 54d01f1e74

emit_event now swallows and reports any failure, including crashes in the
built-in default_emit formatting itself; log_change routes through it.
logfmt chain callbacks that raise are logged and treated as fall-through,
and logmigr callbacks get on_error reporting like fatal_error handlers,
so a broken logging callback can no longer abort a transaction or open.

Demo: raw user ids in v0 logs, logfmt-resolved names in v1 logs.

Demo: simplify resolve_user to a plain previous-state lookup f131f72749

Route transaction aborts through logemit as 'aborted' events 79faa220df

The rollback warning is now a LogEvent (kind='aborted', WARNING level,
carrying the exception) dispatched via emit_event so logemit callbacks can
handle or restyle it. Default rendering: action in transaction color
without quotes, followed by ' transaction aborted: {exc}' in default
color.

Include 'by user' in abort messages cc319ce065

The aborted event now carries the transaction user, resolved through the
logfmt chain against the pre-transaction state so it matches change
headers. Default rendering: '<action> by <user> transaction aborted: <e>'.
User resolution factored into _build_logfmt/_resolve_user helpers shared
by the change and abort paths.

Unify default emitter around universal LogEvent.header c90db530fd

All event kinds now share one shape: a one-line header plus an optional
diff body for changes. LogEvent.header is a lazy property covering every
kind (change, aborted, created, migrated), and default_emit reduces to
logging the header plus routing diff_lines to the .diff child logger.
Custom emitters can tap the same blocks - header, diff_lines, Line,
format_diff - instead of reimplementing formatting per message type.

Add kanta instance to LogEvent and make header settable 799b2438be

Every emitted event now carries the originating Kanta instance so logemit
callbacks can reach application state attached to it. The header property
gains a setter, formalizing restyle-then-delegate: assign ev.header and
return truthy to keep the default diff routing with a custom header.

Document kanta.ctx as the app-context channel for logemit ecd146f72c

kanta.ctx already existed as a user-writable namespace for migrations;
since LogEvent carries the kanta instance, ev.kanta.ctx is also the way
for applications to pass per-connection metadata to their logemit
callbacks, including for creation/bootstrap events. No API change needed.

Final cleanup: lazy logfmt build, docstring and example fixes 47f38f4a71

- transaction.py only builds the logfmt chain when logging is enabled
- callbacks.py module docstring documents the logemit special case
- docs logemit example uses the settable header instead of a user lookup
  that would break when logfmt resolution is registered

Include extra also on transaction abort messages. f63f6e74c6

Give extra its proper Any typing, handle None vs. 0 vs. empty string gracefully in default formatter. 810f379e87

LeoVasanko merged commit 3074f8d8b0 into main

2026-08-07 16:08:28 +00:00

LeoVasanko deleted branch rich-logging

2026-08-07 16:08:28 +00:00

LeoVasanko referenced this issue from a commit

2026-08-15 05:29:03 +00:00

Implement richer, fully customizable logging; customizable timestamps (#1)

Sign in to join this conversation.