Skip to content

Add opt-in syslog priority prefix for stream logs - #2703

Open
tmilnthorp wants to merge 1 commit into
AppDaemon:devfrom
tmilnthorp:syslog-level-prefix
Open

tmilnthorp wants to merge 1 commit into
AppDaemon:devfrom
tmilnthorp:syslog-level-prefix

Conversation

@tmilnthorp

@tmilnthorp tmilnthorp commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

When AppDaemon runs as a systemd service writing to stdout/stderr, journald records every line at the unit's default priority (info). Errors and warnings can't be filtered with journalctl -p, and anything downstream of the journal can't tell them apart either. journald already understands the sd-daemon <N> prefix (SyslogLevelPrefix=, on by default), so AppDaemon just needs to emit it.

logs:
  main_log:
    level_prefix: syslog
<6>2025-06-20 08:30:15.123456 INFO hello_world: Hello from AppDaemon
<3>2025-06-20 08:30:16.000001 ERROR hello_world: Something failed

Mapping: CRITICAL→2, ERROR→3, WARNING→4, INFO→6, DEBUG/NOTSET→7. A custom level uses the nearest standard level below it, so 25 maps to 6 and 45 maps to 3. Anything above CRITICAL maps to 2. Python has no notice level, so 5 is never used.

Details:

  • Every line of a multi-line record (e.g. a traceback) is prefixed. journald splits stdout on newlines and parses the prefix per line, so without this the traceback lines would be logged as info.
  • Only allowed when filename is STDOUT or STDERR. A file log with level_prefix fails at startup with a clear error. The prefix is a stream protocol, and putting <3> into files that people read or rotate seemed more surprising than useful. Validation happens before the handler is created, so the file isn't opened.
  • The prefix is added by a small wrapper formatter (SyslogLevelPrefixFormatter) set only on the stream handler. The log's own formatter in Logging.config is unchanged, so log callbacks and the admin UI still get the unprefixed line.
  • The default is no prefix, so existing configs produce byte-identical output.

How it composes with the JSON output PR: the wrapper prefixes whatever the log's formatter produces, so with both output_format: json and level_prefix: syslog each line becomes <3>{"timestamp": ..., "level": "ERROR", ...}. journald strips the prefix and stores the JSON as MESSAGE. The two branches are independent and both based on dev. I trial-merged them together with the STDERR fix: the only conflict is the adjacent Features bullet in HISTORY.md, and the combined test suite passes, including that JSON+prefix case.

Tests are in tests/unit/test_logging_level_prefix.py: the level mapping (including custom levels and NOTSET), prefixes on STDOUT and STDERR logs, every traceback line prefixed, no prefix by default, log subscriptions unprefixed, file logs refused without creating the file, and invalid values rejected by both Logging and the config model. The tests use the shared make_logging fixture in tests/unit/conftest.py, identical to the one in the other two PRs.

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

Part of #2700.

A log written to STDOUT or STDERR with `level_prefix: syslog` starts each
line with its syslog priority (<2> CRITICAL ... <7> DEBUG), so
systemd-journald's SyslogLevelPrefix and similar collectors record the
real level instead of treating everything as info. Every line of a
multi-line record is prefixed. File logs refuse the option, and log
subscriptions still receive the unprefixed line.
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