docs/JOURNAL_EXPORT_FORMATS.md

   1 ---
   2 title: Journal Export Formats
   3 category: Interfaces
   4 layout: default
   5 SPDX-License-Identifier: LGPL-2.1-or-later
   6 ---
   7
   8 # Journal Export Formats
   9
  10 ## Journal Export Format
  11
  12 _Note that this document describes the binary serialization format of journals only, as used for transfer across the network.
  13 For interfacing with web technologies there's the Journal JSON Format, described below.
  14 The binary format on disk is documented as the [Journal File Format](/JOURNAL_FILE_FORMAT)._
  15
  16 _Before reading on, please make sure you are aware of the [basic properties of journal entries](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html), in particular realize that they may include binary non-text data (though usually don't), and the same field might have multiple values assigned within the same entry (though usually hasn't)._
  17
  18 When exporting journal data for other uses or transferring it via the network/local IPC the _journal export format_ is used.
  19 It's a simple serialization of journal entries, that is easy to read without any special tools, but still binary safe where necessary.
  20 The format is like this:
  21
  22 * Two journal entries that follow each other are separated by a double newline.
  23 * Journal fields consisting only of valid non-control UTF-8 codepoints are serialized as they are
  24   (i.e. the field name, followed by '=', followed by field data), followed by a newline as separator to the next field.
  25   Note that fields containing newlines cannot be formatted like this.
  26   Non-control UTF-8 codepoints are the codepoints with value at or above 32 (' '), or equal to 9 (TAB).
  27 * Other journal fields are serialized in a special binary safe way:
  28   field name, followed by newline, followed by a binary 64-bit little endian size value, followed by the binary field data, followed by a newline as separator to the next field.
  29 * Entry metadata that is not actually a field is serialized like it was a field, but beginning with two underscores.
  30   More specifically, `__CURSOR=`, `__REALTIME_TIMESTAMP=`, `__MONOTONIC_TIMESTAMP=`, `__SEQNUM=`, `__SEQNUM_ID` are introduced this way.
  31   Note that these meta-fields are only generated when actual journal files are serialized.
  32   They are omitted for entries that do not originate from a journal file (for example because they are transferred for the first time to be stored in one).
  33   Or in other words: if you are generating this format you shouldn't care about these special double-underscore fields.
  34   But you might find them usable when you deserialize the format generated by us.
  35   Additional fields prefixed with two underscores might be added later on, your parser should skip over the fields it does not know.
  36 * The order in which fields appear in an entry is undefined and might be different for each entry that is serialized.
  37 And that's already it.
  38
  39 This format can be generated via `journalctl -o export`.
  40
  41 Here's an example for two serialized entries which consist only of text data:
  42
  43 ```
  44 __CURSOR=s=739ad463348b4ceca5a9e69c95a3c93f;i=4ece7;b=6c7c6013a26343b29e964691ff25d04c;m=4fc72436e;t=4c508a72423d9;x=d3e5610681098c10;p=system.journal
  45 __REALTIME_TIMESTAMP=1342540861416409
  46 __MONOTONIC_TIMESTAMP=21415215982
  47 _BOOT_ID=6c7c6013a26343b29e964691ff25d04c
  48 _TRANSPORT=syslog
  49 PRIORITY=4
  50 SYSLOG_FACILITY=3
  51 SYSLOG_IDENTIFIER=gdm-password]
  52 SYSLOG_PID=587
  53 MESSAGE=AccountsService-DEBUG(+): ActUserManager: ignoring unspecified session '8' since it's not graphical: Success
  54 _PID=587
  55 _UID=0
  56 _GID=500
  57 _COMM=gdm-session-wor
  58 _EXE=/usr/libexec/gdm-session-worker
  59 _CMDLINE=gdm-session-worker [pam/gdm-password]
  60 _AUDIT_SESSION=2
  61 _AUDIT_LOGINUID=500
  62 _SYSTEMD_CGROUP=/user/lennart/2
  63 _SYSTEMD_SESSION=2
  64 _SELINUX_CONTEXT=system_u:system_r:xdm_t:s0-s0:c0.c1023
  65 _SOURCE_REALTIME_TIMESTAMP=1342540861413961
  66 _MACHINE_ID=a91663387a90b89f185d4e860000001a
  67 _HOSTNAME=epsilon
  68
  69 __CURSOR=s=739ad463348b4ceca5a9e69c95a3c93f;i=4ece8;b=6c7c6013a26343b29e964691ff25d04c;m=4fc72572f;t=4c508a7243799;x=68597058a89b7246;p=system.journal
  70 __REALTIME_TIMESTAMP=1342540861421465
  71 __MONOTONIC_TIMESTAMP=21415221039
  72 _BOOT_ID=6c7c6013a26343b29e964691ff25d04c
  73 _TRANSPORT=syslog
  74 PRIORITY=6
  75 SYSLOG_FACILITY=9
  76 SYSLOG_IDENTIFIER=/USR/SBIN/CROND
  77 SYSLOG_PID=8278
  78 MESSAGE=(root) CMD (run-parts /etc/cron.hourly)
  79 _PID=8278
  80 _UID=0
  81 _GID=0
  82 _COMM=run-parts
  83 _EXE=/usr/bin/bash
  84 _CMDLINE=/bin/bash /bin/run-parts /etc/cron.hourly
  85 _AUDIT_SESSION=8
  86 _AUDIT_LOGINUID=0
  87 _SYSTEMD_CGROUP=/user/root/8
  88 _SYSTEMD_SESSION=8
  89 _SELINUX_CONTEXT=system_u:system_r:crond_t:s0-s0:c0.c1023
  90 _SOURCE_REALTIME_TIMESTAMP=1342540861416351
  91 _MACHINE_ID=a91663387a90b89f185d4e860000001a
  92 _HOSTNAME=epsilon
  93
  94 ```
  95
  96 A message with a binary field produced by
  97 ```bash
  98 python3 -c 'from systemd import journal; journal.send("foo\nbar")'
  99 journalctl -n1 -o export
 100 ```
 101
 102 ```
 103 __CURSOR=s=bcce4fb8ffcb40e9a6e05eee8b7831bf;i=5ef603;b=ec25d6795f0645619ddac9afdef453ee;m=545242e7049;t=50f1202
 104 __REALTIME_TIMESTAMP=1423944916375353
 105 __MONOTONIC_TIMESTAMP=5794517905481
 106 _BOOT_ID=ec25d6795f0645619ddac9afdef453ee
 107 _TRANSPORT=journal
 108 _UID=1001
 109 _GID=1001
 110 _CAP_EFFECTIVE=0
 111 _SYSTEMD_OWNER_UID=1001
 112 _SYSTEMD_SLICE=user-1001.slice
 113 _MACHINE_ID=5833158886a8445e801d437313d25eff
 114 _HOSTNAME=bupkis
 115 _AUDIT_LOGINUID=1001
 116 _SELINUX_CONTEXT=unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
 117 CODE_LINE=1
 118 CODE_FUNC=<module>
 119 SYSLOG_IDENTIFIER=python3
 120 _COMM=python3
 121 _EXE=/usr/bin/python3.4
 122 _AUDIT_SESSION=35898
 123 _SYSTEMD_CGROUP=/user.slice/user-1001.slice/session-35898.scope
 124 _SYSTEMD_SESSION=35898
 125 _SYSTEMD_UNIT=session-35898.scope
 126 MESSAGE
 127 ^G^@^@^@^@^@^@^@foo
 128 bar
 129 CODE_FILE=<string>
 130 _PID=16853
 131 _CMDLINE=python3 -c from systemd import journal; journal.send("foo\nbar")
 132 _SOURCE_REALTIME_TIMESTAMP=1423944916372858
 133 ```
 134
 135 ## Journal JSON Format
 136
 137 _Note that this section describes the JSON serialization format of the journal only, as used for interfacing with web technologies.
 138 For binary transfer of journal data across the network there's the Journal Export Format described above.
 139 The binary format on disk is documented as [Journal File Format](/JOURNAL_FILE_FORMAT)._
 140
 141 _Before reading on, please make sure you are aware of the [basic properties of journal entries](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html), in particular realize that they may include binary non-text data (though usually don't), and the same field might have multiple values assigned within the same entry (though usually hasn't)._
 142
 143 In most cases the Journal JSON serialization is the obvious mapping of the entry field names (as JSON strings) to the entry field values (also as JSON strings) encapsulated in one JSON object. However, there are a few special cases to handle:
 144
 145 * A field that contains non-printable or non-UTF8 is serialized as a number array instead.
 146   This is necessary to handle binary data in a safe way without losing data, since JSON cannot embed binary data natively.
 147   Each byte of the binary field will be mapped to its numeric value in the range 0…255.
 148 * The JSON serializer can optionally skip huge (as in larger than a specific threshold) data fields from the JSON object.
 149   If that is enabled and a data field is too large, the field name is still included in the JSON object but assigned _null_.
 150 * Within the same entry, Journal fields may have multiple values assigned. This is not allowed in JSON.
 151   The serializer will hence create a single JSON field only for these cases, and assign it an array of values
 152   (which the can be strings, _null_ or number arrays, see above).
 153 * If the JSON data originates from a journal file it may include the special addressing fields
 154   `__CURSOR`, `__REALTIME_TIMESTAMP`, `__MONOTONIC_TIMESTAMP`, `__SEQNUM`, `__SEQNUM_ID`, which contain the cursor string of this entry as string,
 155   the realtime/monotonic timestamps of this entry as formatted numeric string of usec since the respective epoch,
 156   and the sequence number and associated sequence number ID, both formatted as strings.
 157
 158 Here's an example, illustrating all cases mentioned above. Consider this entry:
 159
 160 ```
 161 MESSAGE=Hello World
 162 _UDEV_DEVNODE=/dev/waldo
 163 _UDEV_DEVLINK=/dev/alias1
 164 _UDEV_DEVLINK=/dev/alias2
 165 BINARY=this is a binary value \a
 166 LARGE=this is a super large value (let's pretend at least, for the sake of this example)
 167 ```
 168
 169 This translates into the following JSON Object:
 170 ```json
 171 {
 172   "MESSAGE" : "Hello World",
 173   "_UDEV_DEVNODE" : "/dev/waldo",
 174   "_UDEV_DEVLINK" : [ "/dev/alias1", "/dev/alias2" ],
 175   "BINARY" : [ 116, 104, 105, 115, 32, 105, 115, 32, 97, 32, 98, 105, 110, 97, 114, 121, 32, 118, 97, 108, 117, 101, 32, 7 ],
 176   "LARGE" : null
 177 }
 178 ```