Update README.md
Costa Tsaousis committed
Oct 7, 2023 at 15:26 UTC
4c3df630239f682e385c53daa5c5e9b7438b318f
1 file changed
+23
-15
collectors/systemd-journal.plugin/README.md
+23
-15
@@ -47,36 +47,44 @@ The plugin, by default, merges all journal sources together, to provide a unifie
47
48
### `system` journals
49
50
-These are the default journals available on all systems.
50
+`system` journals are the default journals available on all `systemd` based systems.
51
52
`system` journals contain:
53
54
- kernel log messages (via `kmsg`),
55
- audit records, originating from the kernel audit subsystem,
56
-- messages received via `syslog`,
56
+- messages received by `systemd-journald` via `syslog`,
57
- messages received via the standard output and error of service units,
58
- structured messages received via the native journal API.
59
60
### `user` journals
61
62
+Unlike `journalctl`, the Netdata plugin allows viewing, exploring and querying the journal files of **all users**.
63
+
64
By default, each user, with a UID outside the range of system users (0 - 999), dynamic service users,
65
and the nobody user (65534), will get their own set of `user` journal files. For more information about
66
this policy check [Users, Groups, UIDs and GIDs on systemd Systems](https://systemd.io/UIDS-GIDS/).
67
66
-The plugin allows viewing, exploring and querying the journal files of all users.
68
+Keep in mind that `user` journals are merged with the `system` journals when they are propagated to a journal
69
+centralization server. So, at the centralization server, the `remote` journals contain both the `system` and `user`
70
+journals of the sender.
71
72
### `namespaces` journals
73
70
-Journal 'namespaces' are both a mechanism for logically isolating the log stream of projects consisting
71
-of one or more services from the rest of the system and a mechanism for improving performance. `systemd` service
72
-units may be assigned to a specific journal namespace through the `LogNamespace=` unit file setting.
73
-
74
The plugin auto-detects the namespaces available and provides a list of all namespaces at the "sources" list on the UI.
75
76
+Journal namespaces are both a mechanism for logically isolating the log stream of projects consisting
77
+of one or more services from the rest of the system and a mechanism for improving performance.
78
+
79
+`systemd` service units may be assigned to a specific journal namespace through the `LogNamespace=` unit file setting.
80
+
81
+Keep in mind that namespaces require special configuration to be propagated to a journal centralization server.
82
+This makes them a little more difficult to handle, from the administration perspective.
83
+
84
### `remote` journals
85
78
-Remote journals are created by `systemd-journal-remote`. This feature allows creating logs centralization points within
79
-your infrastructure.
86
+Remote journals are created by `systemd-journal-remote`. This `systemd` feature allows creating logs centralization points within
87
+your infrastructure, based exclusively on `systemd`.
88
89
Usually `remote` journals are named by the IP of the server sending these logs. The Netdata plugin automatically
90
extracts these IPs and performs a reverse DNS lookup to find their hostnames. When this is successful,
@@ -93,7 +101,7 @@ The plugin automatically enriches certain fields to make them more user-friendly
101
102
- `_BOOT_ID`: the hex value is annotated with the timestamp of the first message encountered for this boot id.
103
- `PRIORITY`: the numeric value is replaced with the human-readable name of each priority.
96
-- `SYSLOG_FACILITY`: the encoded value is replaced with the human-readable name of each value.
104
+- `SYSLOG_FACILITY`: the encoded value is replaced with the human-readable name of each facility.
105
- `ERRNO`: the numeric value is annotated with the short name of each value.
106
- `_UID` `_AUDIT_LOGINUID` and `_SYSTEMD_OWNER_UID`: the local user database is consulted to annotate them with usernames.
107
- `_GID`: the local group database is consulted to annotate them with group names.
@@ -102,10 +110,10 @@ The plugin automatically enriches certain fields to make them more user-friendly
110
111
The values of all other fields are presented as found in the journals.
112
105
-> IMPORTANT:
113
+> IMPORTANT:
114
> `_UID` `_AUDIT_LOGINUID`, `_SYSTEMD_OWNER_UID` and `_GID` annotations are added during presentation and are taken
115
> from the server running the plugin. For `remote` sources, the names presented may not reflect the actual user and
108
-> group names on the origin server.
116
+> group names on the origin server. The numeric value will still be visible though, as-is on the origin server.
117
118
The annotations are not searchable with full text search. They are only added for the presentation of the fields.
119
@@ -117,8 +125,8 @@ All journal fields available in the journal files are offered as columns on the
125
126
### Journal fields as additional info to each log entry
127
120
-When you click a log line, the sidebar, on the right of the screen, provides the full list of fields related to this
121
-log line. You can close this info sidebar, by selecting the filter icon at its top.
128
+When you click a log line, the `info` sidebar will open on the right of the screen, to provide the full list of fields related to this
129
+log line. You can close this `info` sidebar, by selecting the filter icon at its top.
130
131
132
@@ -143,7 +151,7 @@ When "full data queries" is off, empty values are hidden and cannot be selected.
151
152
When "full data queries" is on, Netdata is applying all filtering to the data (not `libsystemd`), but this means
153
that all the data of the entire time-frame, without any filtering applied, have to be read by the plugin to prepare
146
-the response required.
154
+the response required. So, "full data queries" can be significantly slower over long time-frames.
155
156
### Journal fields as histogram sources
157