diff options
Diffstat (limited to 'man/journalctl.xml')
| -rw-r--r-- | man/journalctl.xml | 122 |
1 files changed, 66 insertions, 56 deletions
diff --git a/man/journalctl.xml b/man/journalctl.xml index a4f9e2d7ee..58f3aa205a 100644 --- a/man/journalctl.xml +++ b/man/journalctl.xml @@ -148,9 +148,9 @@ <term><option>-a</option></term> <term><option>--all</option></term> - <listitem><para>Show all fields in full, even if they - include unprintable characters or are very - long.</para></listitem> + <listitem><para>Show all fields in full, even if they include unprintable characters or are very long. By + default, fields with unprintable characters are abbreviated as "blob data". (Note that the pager may escape + unprintable characters again.)</para></listitem> </varlistentry> <varlistentry> @@ -316,10 +316,23 @@ <option>json</option> </term> <listitem> - <para>formats entries as JSON data structures, one per - line (see - <ulink url="https://www.freedesktop.org/wiki/Software/systemd/json">Journal JSON Format</ulink> - for more information).</para> + <para>formats entries as JSON objects, separated by newline characters (see <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/json">Journal JSON Format</ulink> for more + information). Field values are generally encoded as JSON strings, with three exceptions: + <orderedlist> + <listitem><para>Fields larger than 4096 bytes are encoded as <constant>null</constant> values. (This + may be turned off by passing <option>--all</option>, but be aware that this may allocate overly long + JSON objects.) </para></listitem> + + <listitem><para>Journal entries permit non-unique fields within the same log entry. JSON does not allow + non-unique fields within objects. Due to this, if a non-unique field is encountered a JSON array is + used as field value, listing all field values as elements.</para></listitem> + + <listitem><para>Fields containing non-printable or non-UTF8 bytes are encoded as arrays containing + the raw bytes individually formatted as unsigned numbers.</para></listitem> + </orderedlist> + + Note that this encoding is reversible (with the exception of the size limit).</para> </listitem> </varlistentry> @@ -348,6 +361,19 @@ <varlistentry> <term> + <option>json-seq</option> + </term> + <listitem> + <para>formats entries as JSON data structures, but prefixes them with an ASCII Record Separator + character (0x1E) and suffixes them with an ASCII Line Feed character (0x0A), in accordance with <ulink + url="https://tools.ietf.org/html/rfc7464">JavaScript Object Notation (JSON) Text Sequences </ulink> + (<literal>application/json-seq</literal>). + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term> <option>cat</option> </term> <listitem> @@ -375,14 +401,11 @@ <varlistentry> <term><option>--output-fields=</option></term> - <listitem><para>A comma separated list of the fields which should - be included in the output. This only has an effect for the output modes - which would normally show all fields (<option>verbose</option>, - <option>export</option>, <option>json</option>, - <option>json-pretty</option>, and <option>json-sse</option>). The - <literal>__CURSOR</literal>, <literal>__REALTIME_TIMESTAMP</literal>, - <literal>__MONOTONIC_TIMESTAMP</literal>, and - <literal>_BOOT_ID</literal> fields are always + <listitem><para>A comma separated list of the fields which should be included in the output. This only has an + effect for the output modes which would normally show all fields (<option>verbose</option>, + <option>export</option>, <option>json</option>, <option>json-pretty</option>, <option>json-sse</option> and + <option>json-seq</option>). The <literal>__CURSOR</literal>, <literal>__REALTIME_TIMESTAMP</literal>, + <literal>__MONOTONIC_TIMESTAMP</literal>, and <literal>_BOOT_ID</literal> fields are always printed.</para></listitem> </varlistentry> @@ -706,18 +729,6 @@ </varlistentry> <varlistentry> - <term><option>--new-id128</option></term> - - <listitem><para>Instead of showing journal contents, generate - a new 128-bit ID suitable for identifying messages. This is - intended for usage by developers who need a new identifier for - a new message they introduce and want to make - recognizable. This will print the new ID in four different - formats which can be copied into source code or similar. - </para></listitem> - </varlistentry> - - <varlistentry> <term><option>--header</option></term> <listitem><para>Instead of showing journal contents, show @@ -738,32 +749,28 @@ <term><option>--vacuum-time=</option></term> <term><option>--vacuum-files=</option></term> - <listitem><para>Removes the oldest archived journal files until the disk - space they use falls below the specified size (specified with - the usual <literal>K</literal>, <literal>M</literal>, - <literal>G</literal> and <literal>T</literal> suffixes), or all - archived journal files contain no data older than the specified - timespan (specified with the usual <literal>s</literal>, - <literal>m</literal>, <literal>h</literal>, - <literal>days</literal>, <literal>months</literal>, - <literal>weeks</literal> and <literal>years</literal> suffixes), - or no more than the specified number of separate journal files - remain. Note that running <option>--vacuum-size=</option> has - only an indirect effect on the output shown by - <option>--disk-usage</option>, as the latter includes active - journal files, while the vacuuming operation only operates - on archived journal files. Similarly, - <option>--vacuum-files=</option> might not actually reduce the - number of journal files to below the specified number, as it - will not remove active journal - files. <option>--vacuum-size=</option>, - <option>--vacuum-time=</option> and - <option>--vacuum-files=</option> may be combined in a single - invocation to enforce any combination of a size, a time and a - number of files limit on the archived journal - files. Specifying any of these three parameters as zero is - equivalent to not enforcing the specific limit, and is thus - redundant.</para></listitem> + <listitem><para>Removes the oldest archived journal files until the disk space they use falls below the + specified size (specified with the usual <literal>K</literal>, <literal>M</literal>, <literal>G</literal> and + <literal>T</literal> suffixes), or all archived journal files contain no data older than the specified timespan + (specified with the usual <literal>s</literal>, <literal>m</literal>, <literal>h</literal>, + <literal>days</literal>, <literal>months</literal>, <literal>weeks</literal> and <literal>years</literal> + suffixes), or no more than the specified number of separate journal files remain. Note that running + <option>--vacuum-size=</option> has only an indirect effect on the output shown by + <option>--disk-usage</option>, as the latter includes active journal files, while the vacuuming operation only + operates on archived journal files. Similarly, <option>--vacuum-files=</option> might not actually reduce the + number of journal files to below the specified number, as it will not remove active journal + files.</para> + + <para><option>--vacuum-size=</option>, <option>--vacuum-time=</option> and <option>--vacuum-files=</option> + may be combined in a single invocation to enforce any combination of a size, a time and a number of files limit + on the archived journal files. Specifying any of these three parameters as zero is equivalent to not enforcing + the specific limit, and is thus redundant.</para> + + <para>These three switches may also be combined with <option>--rotate</option> into one command. If so, all + active files are rotated first, and the requested vacuuming operation is executed right after. The rotation has + the effect that all currently active files are archived (and potentially new, empty journal files opened as + replacement), and hence the vacuuming operation has the greatest effect as it can take all log data written so + far into account.</para></listitem> </varlistentry> <varlistentry> @@ -885,9 +892,12 @@ <varlistentry> <term><option>--rotate</option></term> - <listitem><para>Asks the journal daemon to rotate journal - files. This call does not return until the rotation operation - is complete.</para></listitem> + <listitem><para>Asks the journal daemon to rotate journal files. This call does not return until the rotation + operation is complete. Journal file rotation has the effect that all currently active journal files are marked + as archived and renamed, so that they are never written to in future. New (empty) journal files are then + created in their place. This operation may be combined with <option>--vacuum-size=</option>, + <option>--vacuum-time=</option> and <option>--vacuum-file=</option> into a single command, see + above.</para></listitem> </varlistentry> <xi:include href="standard-options.xml" xpointer="help" /> |