Repository navigation
Add opt-in JSON log output - #2702
Open
tmilnthorp wants to merge 1 commit into
Open
tmilnthorp wants to merge 1 commit into
tmilnthorp wants to merge 1 commit into
Conversation
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`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a per-log
output_formatoption.textis the default and nothing changes for existing configs.jsonwrites 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 changesformat.{"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 ofLogging.get_timeintocurrent_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, andstack_infoonly 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:formatis astr.formattemplate, so treating one particular string as a mode would overload it, and a plain template could never mean "json".formatteris already used internally inLogging.configto hold the formatter object, so it's taken.output_formatdoesn't collide with either, and it's validated inAppDaemonLogConfigasLiteral["text", "json"].Implementation:
JSONFormattersubclassesAppNameFormatter, so it setsappname,messageandasctimeon the record the same way. That means it works unchanged withLogSubscriptionHandler. It works for every log type: main, error, diag, access and user logs. Logs that aliasmain_logby default follow its format. The output usesjson.dumpswithensure_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_messagefrom the log's formatter, so withjsonthey 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,appfor 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 bothLoggingand the config model. The tests use themake_loggingfixture intests/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.