From ffa16db02673ffa155ffb2649e72a935a1ff70f5 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Tue, 3 Apr 2012 22:31:48 +0200 Subject: [PATCH] man: document special journal fields --- Makefile.am | 1 + man/journalctl.xml | 5 +- man/journald.conf.xml | 1 + man/systemd.journal-fields.xml | 330 +++++++++++++++++++++++++++++++++ src/logs-show.c | 8 +- 5 files changed, 340 insertions(+), 5 deletions(-) create mode 100644 man/systemd.journal-fields.xml diff --git a/Makefile.am b/Makefile.am index 219d8ded..75f5c94c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -667,6 +667,7 @@ MANPAGES = \ man/systemd.snapshot.5 \ man/systemd.exec.5 \ man/systemd.special.7 \ + man/systemd.journal-fields.7 \ man/daemon.7 \ man/runlevel.8 \ man/telinit.8 \ diff --git a/man/journalctl.xml b/man/journalctl.xml index f6e46cfb..4728d36e 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -68,7 +68,9 @@ If a match argument is passed the output is filtered accordingly. A match is in the format FIELD=VALUE, - e.g. _SYSTEMD_UNIT=httpd.service. + e.g. _SYSTEMD_UNIT=httpd.service. See + systemd.journal-fields7 + for a list of well-known fields. Output is interleaved from all accessible journal files, whether they are rotated or currently @@ -253,6 +255,7 @@ systemd1, systemctl1, + systemd.journal-fields7, journald.conf5 diff --git a/man/journald.conf.xml b/man/journald.conf.xml index a9b0f66d..eb596eb3 100644 --- a/man/journald.conf.xml +++ b/man/journald.conf.xml @@ -247,6 +247,7 @@ systemd1, journalctl1, + systemd.journal-fields7, systemd.conf5 diff --git a/man/systemd.journal-fields.xml b/man/systemd.journal-fields.xml new file mode 100644 index 00000000..5f2a32cb --- /dev/null +++ b/man/systemd.journal-fields.xml @@ -0,0 +1,330 @@ + + + + + + + + + systemd.journal-fields + systemd + + + + Developer + Lennart + Poettering + lennart@poettering.net + + + + + + systemd.journal-fields + 7 + + + + systemd.journal-fields + Special journal fields + + + + Description + + Entries in the journal resemble an environment + block in their syntax, however with fields that can + include binary data. Primarily, fields are formatted + ASCII strings, and binary formatting is used only + where formatting as ASCII makes little sense. New + fields may be freely defined by applications, but a + few fields have special meaning. All fields with + special meaning are optional. + + + + User Journal Fields + + User fields are fields that are directly passed + from clients and stored in the journal. + + + + MESSAGE= + + The human readable + message string for this + entry. This is supposed to be + the primary text shown to the + user. It is not translated, + and is not supposed to be + parsed for meta data. + + + + + MESSAGE_ID= + + A 128bit message + identifier ID for recognizing + certain message types, if this + is desirable. This should + contain a 128bit id formatted + as lower-case hexadecimal + string, without any separating + dashes or suchlike. This is + recommended to be a UUID + compatible ID, but this is not + enforced, and formatted + differently. Developers can + generate a new ID for this + purpose with + journalctl + --new-id. + + + + + PRIORITY= + + A priority value between + 0 (emerg) + and 7 + (debug) + formatted as decimal + string. This field is + compatible with syslog's + priority concept. + + + + + CODE_FILE= + CODE_LINE= + CODE_FUNC= + + The code location + generating this message, if + known. Contains the source + file name, the line number and + the function name. + + + + + SYSLOG_FACILITY= + SYSLOG_IDENTIFIER= + SYSLOG_PID= + + Syslog compatibility + fields containing the facility + (formatted as decimal string), + the identifier string + (i.e. "tag"), and the client + PID. + + + + + + + + Trusted Journal Fields + + Fields prefixed with an underscore are trusted + fields, i.e. fields that are implicitly added by the + journal and cannot be altered by client code. + + + + _PID= + _UID= + _GID= + + The process, user and + group ID of the process the + journal entry originates from + formatted as decimal + string. + + + + + _COMM= + _EXE= + _CMDLINE= + + The name, the executable + path and the command line of + the process the journal entry + originates from. + + + + + _AUDIT_SESSION= + _AUDIT_LOGINUID= + + The session and login + UID of the process the journal + entry originates from, as + maintained by the kernel audit + subsystem. + + + + + _SYSTEMD_CGROUP= + _SYSTEMD_SESSION= + _SYSTEMD_UNIT= + _SYSTEMD_OWNER_UID= + + + The contol group path in + the systemd hierarchy, the + systemd session ID (if any), + the systemd unit name (if any) + and the owner UID of the + systemd session (if any) of + the process the journal entry + originates from. + + + + + _SELINUX_CONTEXT= + + The SELinux security + context of the process the + journal entry originates + from. + + + + + _SOURCE_REALTIME_TIMESTAMP= + + The earliest trusted + timestamp of the message, if + any is known that is different + from the reception time of the + journal. The time in usec + since the epoch formatted as + decimal string. + + + + + _BOOT_ID= + + The kernel boot ID for + the boot the message was + generated in, formatted as + 128bit hexadecimal + string. + + + + + _MACHINE_ID= + + The machine ID of the + originating host, as available + in + machine-id5. + + + + + _HOSTNAME= + + The name of the + originating host. + + + + + + + Address Fields + + During serialization into external formats the + addresses of journal entries are serialized into + fields prefixed with double underscores. Note that + these aren't proper fields when stored in the journal, + but addressing meta data of entries. + + + + __CURSOR= + + The cursor for the + entry. A cursor is an opaque + text string that uniquely + describes the position of an + entry in the journal and is + portable across machines, + platforms and journal + files. + + + + + __REALTIME_TIMESTAMP= + + The wallclock time + (CLOCK_REALTIME) at the point + in time the entry was received + by the journal. This has + different properties from + _SOURCE_REALTIME_TIMESTAMP= + as it is usually a bit later + but more likely to be + monotonic. + + + + + __MONOTONIC_TIMESTAMP= + + The monotonic time + (CLOCK_MONOTONIC) at the point + in time the entry was received + by the journal. To be useful + as an address for the entry + this should be combined with + with boot ID in + _BOOT_ID=. + + + + + + + See Also + + systemd1, + journalctl1, + journald.conf5 + + + + diff --git a/src/logs-show.c b/src/logs-show.c index 0a07a77b..158223fc 100644 --- a/src/logs-show.c +++ b/src/logs-show.c @@ -348,8 +348,8 @@ static int output_export(sd_journal *j, unsigned line, unsigned n_columns, bool } printf("__CURSOR=%s\n" - "__REALTIME=%llu\n" - "__MONOTONIC=%llu\n" + "__REALTIME_TIMESTAMP=%llu\n" + "__MONOTONIC_TIMESTAMP=%llu\n" "__BOOT_ID=%s\n", cursor, (unsigned long long) realtime, @@ -460,8 +460,8 @@ static int output_json(sd_journal *j, unsigned line, unsigned n_columns, bool sh printf("{\n" "\t\"__CURSOR\" : \"%s\",\n" - "\t\"__REALTIME\" : \"%llu\",\n" - "\t\"__MONOTONIC\" : \"%llu\",\n" + "\t\"__REALTIME_TIMESTAMP\" : \"%llu\",\n" + "\t\"__MONOTONIC_TIMESTAMP\" : \"%llu\",\n" "\t\"__BOOT_ID\" : \"%s\"", cursor, (unsigned long long) realtime, -- 2.39.5