Skip to content

Add opt-in JSON log output - #2702

Open
tmilnthorp wants to merge 1 commit into
AppDaemon:devfrom
tmilnthorp:json-log-format
Open

tmilnthorp wants to merge 1 commit into
AppDaemon:devfrom
tmilnthorp:json-log-format

Conversation

@tmilnthorp

@tmilnthorp tmilnthorp commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Adds a per-log output_format option. text is the default and nothing changes for existing configs. json writes one JSON object per line, which log collectors (Loki/Promtail, Vector, Fluent Bit, journald + a JSON parser, etc.) can read without a regex that breaks whenever someone changes format.

logs:
  main_log:
    output_format: json
{"timestamp": "2025-06-20T08:30:15.123456-04:00", "level": "INFO", "app": "hello_world", "logger": "AppDaemon.hello_world", "message": "Hello from AppDaemon"}

Fields:

  • timestamp: ISO 8601 with a UTC offset. It comes from the same clock as {asctime}, so it follows the configured time zone and time travel. I split the body of Logging.get_time into current_time() so the text and JSON paths share that logic; get_time's output is unchanged.
  • level, logger (the Python logger name), app (the same value as {appname}), message (with %-args applied).
  • exception (the formatted traceback) only when there is exc_info, and stack_info only when one was requested. A traceback therefore stays inside a single line instead of spilling across several.

Why a new key instead of format: json: format is a str.format template, so treating one particular string as a mode would overload it, and a plain template could never mean "json". formatter is already used internally in Logging.config to hold the formatter object, so it's taken. output_format doesn't collide with either, and it's validated in AppDaemonLogConfig as Literal["text", "json"].

Implementation: JSONFormatter subclasses AppNameFormatter, so it sets appname, message and asctime on the record the same way. That means it works unchanged with LogSubscriptionHandler. It works for every log type: main, error, diag, access and user logs. Logs that alias main_log by default follow its format. The output uses json.dumps with ensure_ascii=False (no new dependency), so non-ASCII text stays readable, just as it does in text mode.

One thing I'd like a view on: log callbacks and the admin UI's live log view get formatted_message from the log's formatter, so with json they see the JSON line. It matches what the log writes, and file-based logs that the admin page reads back would be JSON anyway. If you'd prefer the admin view to stay human-readable, I can give the subscription handler a text formatter instead.

Tests are in tests/unit/test_logging_json.py: one valid JSON object per line, the fields, app for both apps and AppDaemon modules, a traceback kept in one line, stack_info, non-ASCII round-tripping, the timestamp following the AppDaemon clock and time zone (time travel), an offset present without a time zone, every log type, the default text output unchanged, the log-subscription payload, and invalid values rejected by both Logging and the config model. The tests use the make_logging fixture in tests/unit/conftest.py, which is identical to the one in the STDERR fix PR.

Docs: CONFIGURE.rst (logs section) and HISTORY.md.

Part of #2700.

A log configured with `output_format: json` writes one JSON object per
line (timestamp, level, app, logger, message, plus exception/stack_info
when present) so log collectors can parse it without a regex. The
timestamp comes from the same clock as {asctime}, so it follows
AppDaemon's time zone and time travel. The default stays `text`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant