Skip to content

Diagnostics

The SDK records privacy-safe structured diagnostics: event names, ids, counters, durations and error codes, never RPC parameters or results, document text, form values, file paths, titles or credentials. Recording never raises into your code and never blocks the transport.

from nativehtmlkit import diagnostics_session_id, export_support_bundle

Levels

Set with NATIVEHTMLKIT_DIAGNOSTICS (or uv run nativehtmlkit-python --diagnostics LEVEL ...):

Level Recorded Written to disk
off nothing no
normal (default) ERROR and WARN records, kept in memory (last 256) no
debug also INFO/DEBUG yes, JSON Lines
trace also TRACE (every RPC, notification, callback and dispatch) yes

The same variable controls the host's own records, which it writes to its standard error. The launcher relays the backend's output at every level and summarises host warnings and errors; informational host records are shown with NATIVEHTMLKIT_VERBOSE=1 (set automatically by --diagnostics trace).

Files

At debug/trace each process writes python-<session>-<pid>.jsonl (mode 0600, at most 16 MiB) into the diagnostics directory:

Platform Directory
any NATIVEHTMLKIT_DIAGNOSTICS_DIR if set
Windows %LOCALAPPDATA%\NativeHTMLKit\diagnostics
Linux ~/.local/state/nativehtmlkit/diagnostics

Each line is one record:

{"schema_version": 1, "timestamp": "2026-11-16T09:12:03.120511+00:00", "session_id": "py-3f…",
 "component": "python-sdk", "pid": 41872, "level": "TRACE", "event": "rpc.completed",
 "context": {"request_id": "py-12", "method": "document.command", "duration_ms": 1, "failed": false, "error_code": null}}

Context values that are not short identifiers are replaced by "[REDACTED]"; method and op names outside the published Core contract become "unknown-method"/"unknown-op".

Useful record names:

Event Meaning
host.authenticated Connected with protocol v1
rpc.started, rpc.completed, rpc.timeout, rpc.cancel_requested Requests (method, op, duration_ms, error_code, cause_seq: the event whose callback made the call)
host.notification A notification arrived (method, event_type, element, event_seq)
document.dispatch An event reached a document: handlers registered, matched for this event. matched: 0 explains "my handler never ran".
callback.started, callback.completed, callback.failed Your callbacks (exception_type on failure)
rpc.notification_dropped, host.notifications_dropped, callback.queue_overflow Events lost because callbacks were too slow
transport.disconnected, transport.closed Connection ended by the host / by close()
document.error, application.shutdown_received Document failures and orderly shutdown

Session id

diagnostics_session_id (also nativehtmlkit.diagnostics.SESSION_ID) identifies this run. It is taken from NATIVEHTMLKIT_DIAGNOSTIC_SESSION_ID if that holds 1–128 characters of A-Z a-z 0-9 . _ : -, else generated (py-<hex>), and exported again in the environment, so the launcher, the host and the backend share one id. Every NativeHTMLKitError carries it as session_id.

Support bundles

export_support_bundle(path, *, capture_environment=False, session=None, directory=None, overwrite=False) -> Path

Write a local ZIP with manifest.json (counts, losses, SDK version, optionally OS/architecture/ Python version) and timeline.jsonl (the re-sanitised records of one session; default: this process's session, from its files or, without files, its in-memory history). Raises FileExistsError unless overwrite=True, ValueError for an invalid session id. Never included: RPC payloads, form values, credentials, environment variables, raw host output, screenshots.

From the command line (uses the most recently recorded session unless --session is given):

NATIVEHTMLKIT_DIAGNOSTICS=trace uv run app.py          # reproduce the problem
uv run nativehtmlkit-python support bundle.zip                # then export it

Host counters

app.host_diagnostics() returns the host's view (phase, windows, pending_jobs, dropped_notifications, logging counters); app.host_dropped_notifications holds the final count after run(). document.diagnostics() lists render/layout diagnostics of a document (unsupported CSS, pending resources).

In-process access

nativehtmlkit.diagnostics.recorder() returns the process recorder: summary() (level, record count, drops, file name) and history() (the in-memory records). nativehtmlkit.diagnostics.record(event, level=..., **fields) adds a record with the same sanitisation.

See diagnostics and troubleshooting.


Source: nativehtmlkit-python/docs/reference/diagnostics.md · edit the page there.