journalctl: port JSON output mode to new JSON API

Also, while we are at it, beef it up, by adding json-seq support (i.e.
https://tools.ietf.org/html/rfc7464). This is particularly useful in
conjunction with jq's --seq switch.

1 files changed, 35 insertions, 12 deletions

diff --git a/man/journalctl.xml b/man/journalctl.xml
index 91461a7732..5102dcdd39 100644
--- a/man/journalctl.xml
+++ b/man/journalctl.xml
@@ -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>