shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-12-22 17:35:35 +03:00
Code

docs: import the Journal JSON Format description as subsection

Browse Source 
I don't think we need a separate page for this, so both "export" formats share
a page.  We can just link to the approprate section when necessary.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2022-01-12 11:19:02 +01:00
parent 5e3ab38e70
commit d9044a43f6
1 changed files with 38 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/JOURNAL_EXPORT_FORMAT.md → docs/JOURNAL_EXPORT_FORMATS.md
View File

@ -8,7 +8,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
# Journal Export Format
_Note that this document describes the binary serialization format of journals only, as used for transfer across the network.
For interfacing with web technologies there's the [Journal JSON Format](http://www.freedesktop.org/wiki/Software/systemd/json).
For interfacing with web technologies there's the Journal JSON Format, described below.
The binary format on disk is documented as the [Journal File Format](https://systemd.io/JOURNAL_FILE_FORMAT/)._
_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)._
@ -117,3 +117,40 @@ _PID=16853
_CMDLINE=python3 -c from systemd import journal; journal.send("foo\nbar")
_SOURCE_REALTIME_TIMESTAMP=1423944916372858
```
# Journal JSON Format
_Note that this section describes the JSON serialization format of the journal only, as used for interfacing with web technologies.
For binary transfer of journal data across the network there's the Journal Export Format described above.
The binary format on disk is documented as [Journal File Format](https://systemd.io/JOURNAL_FILE_FORMAT)._
_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)._
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:
* A field that contains non-printable or non-UTF8 is serialized as a number array instead. This is necessary to handle binary data in a safe way without losing data, since JSON cannot embed binary data natively. Each byte of the binary field will be mapped to its numeric value in the range 0…255.
* The JSON serializer can optionally skip huge (as in larger than a specific threshold) data fields from the JSON object. If that is enabled and a data field is too large, the field name is still included in the JSON object but assigned _null_.
* Within the same entry, Journal fields may have multiple values assigned. This is not allowed in JSON. The serializer will hence create a single JSON field only for these cases, and assign it an array of values (which the can be strings, _null_ or number arrays, see above).
* If the JSON data originates from a journal file it may include the special addressing fields `__CURSOR`, `__REALTIME_TIMESTAMP`, `__MONOTONIC_TIMESTAMP`, which contain the cursor string of this entry as string, and the realtime/monotonic timestamps of this entry as formatted numeric string of usec since the respective epoch.
Here's an example, illustrating all cases mentioned above. Consider this entry:
```
MESSAGE=Hello World
_UDEV_DEVNODE=/dev/waldo
_UDEV_DEVLINK=/dev/alias1
_UDEV_DEVLINK=/dev/alias2
BINARY=this is a binary value \a
LARGE=this is a super large value (let's pretend at least, for the sake of this example)
```
This translates into the following JSON Object:
```json
{
"MESSAGE" : "Hello World",
"_UDEV_DEVNODE" : "/dev/waldo",
"_UDEV_DEVLINK" : [ "/dev/alias1", "/dev/alias2" ],
"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 ],
"LARGE" : null
}
```