From 0a8830c30bc24d220439db5ff4e5796116e51df7 Mon Sep 17 00:00:00 2001
From: Ivan Shapovalov <intelfx@intelfx.name>
Date: Fri, 29 Mar 2024 02:41:13 +0100
Subject: [PATCH] admin: logging-documentation: document journald support

As of forgejo/forgejo#2869, console logging implements three adaptations
for running forgejo under systemd/journald:

- forgejo learned to emit printk-style log level prefixes that are
  picked up by journald and saved as the severity level of this line
  (e.g., `<3>some text\n` means that "some text" will be saved as an
   error entry);
- forgejo learned a new pseudo-flag "journaldflags" which is supposed to
  replace "stdflags" when running under journald to reduce log clutter
  (specifically, it removes date/time from log entries since the
   time information is automatically saved by journald and displayed by
   journalctl, and replaces the textual log level by the above-described
   machine-parsable log level prefix);
- finally, forgejo will try to automatically detect whether it is
  running under journald by parsing `$JOURNAL_STREAM` environment
  variable and use "journalflags" as default flags if that is the case).

Document those.

Signed-off-by: Ivan Shapovalov <intelfx@intelfx.name>
---
 docs/admin/logging-documentation.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/docs/admin/logging-documentation.md b/docs/admin/logging-documentation.md
index 02e50dd6..f71372dc 100644
--- a/docs/admin/logging-documentation.md
+++ b/docs/admin/logging-documentation.md
@@ -142,9 +142,11 @@ Possible values are:
 - `utc` - if date or time is set, use UTC rather than the local time zone.
 - `levelinitial` - initial character of the provided level in brackets eg. `[I]` for info.
 - `level` - level in brackets `[INFO]`.
+- `levelprefix` - journald-style log level prefix, such as `<5>` for "info".
 - `gopid` - the Goroutine-PID of the context.
 - `medfile` - last 20 characters of the filename - equivalent to `shortfile,longfile`.
 - `stdflags` - equivalent to `date,time,medfile,shortfuncname,levelinitial`.
+- `journaldflags` - equivalent to `levelprefix`.
 
 ### Console mode
 
@@ -161,6 +163,26 @@ Settings:
 
 - `STDERR`: **false**: Whether the logger should print to `stderr` instead of `stdout`.
 
+### journald mode
+
+As an extension to the console mode, if Forgejo detects that stdout and/or stderr
+are connected to systemd-journald (which will happen automatically when Forgejo
+is running under systemd), the defaults will change:
+
+- `STDERR` will default to **true** if stderr is connected to systemd-journald;
+- `FLAGS` will default to `journaldflags` if the chosen stream is connected to
+  systemd-journald.
+
+When `FLAGS = journaldflags` is used, instead of decorating log entries with
+color or a textual representation of severity (e.g. `[INFO]` or `[ERROR]`),
+Forgejo will annotate each log entry with a machine-readable log level prefix
+that is captured by journald, enabling native filtering capabilities
+(e.g. run `journalctl -u forgejo -p err` to only show errors or worse).
+
+In short, if Forgejo is running under systemd, it is recommended to leave the
+logging configuration at their defaults, which will use `MODE = console` and
+adjust formatting to reduce clutter and enable native log level filtering.
+
 ### File mode
 
 In this mode the logger will save log messages to a file.