systemd-journal(三)之systemd.journal-fields

写在前面

本文主要是详细介绍了systemd.journal-fields ，主要翻译自英文原文文档(develop版本，截止到文章记录，最新版本是systemd 255)。以及增加了一些使用示例。
主要是以下页面的翻译：
https://www.freedesktop.org/software/systemd/man/latest/systemd.journal-fields.html#
其他相关文档请参考：systemd专栏

概述

systemd.journal-fields ---- 特殊日志字段

日志中的记录（由 systemd-journald.service（8） 编写）在语法上类似于 UNIX 进程环境块，但字段值可能包含二进制数据，并且允许使用非唯一字段名称。

字段值主要是格式化的 UTF-8 文本字符串 —— 二进制编码仅在格式化为 UTF-8 文本字符串没有意义的情况下使用。新字段可以由应用程序自由定义，但少数字段具有特殊含义，如下所示。

通常，每个日志记录的字段可能只出现一次，但也有特殊的例外情况：某些字段可能每个记录出现多次，在这种情况下，下面明确提到这一点。

尽管日志记录子系统对接受非唯一值的字段没有限制，但强烈建议避免对下面列出的字段依赖此值（除非另有说明，如前所述），以避免与其他应用程序不必要的不兼容。

用户日志字段（User Journal Fields）

用户字段是直接从客户端传递并存储在日志中的字段。

MESSAGE=

此记录是人类可读消息字符串。这应该是向用户显示的主要文本。它通常不会被翻译（但在某些情况下可能会翻译），并且不应该被解析为元数据。

为了在单个日志记录中对多行进行编码，请用换行符（ASCII 代码 10）分隔它们，但将它们编码为单个 MESSAGE= 字段。

不要将此字段类型的多个值添加到同一记录（另请参阅上文），因为使用应用程序通常不会期望这样做，并且在这种情况下不太可能显示所有值。

MESSAGE_ID=

用于识别某些消息类型的 128 位消息标识符 ID（如果需要）。

这应该包含一个 128 位 ID，格式为小写十六进制字符串，没有任何分隔破折号或类似内容。

建议将其设置为与 UUID 兼容的 ID，但不会强制执行，并且格式不同。

开发人员可以使用 systemd-id128 new 生成一个新 ID。

PRIORITY=

介于 0 （“ emerg ”） 和 7 （“ debug ”） 之间的优先级值，格式为十进制字符串。此字段与 syslog 的优先级概念兼容。

CODE_FILE=, CODE_LINE=, CODE_FUNC=

生成此消息的代码位置（如果已知）。包含源文件名、行号和函数名称。

ERRNO=

导致此记录的低级 Unix 错误号（如果有）。包含 errno（3） 的数值，格式为十进制字符串。

INVOCATION_ID=, USER_INVOCATION_ID=

一个随机的、唯一的 128 位 ID，用于标识设备的每个运行时周期。这与_SYSTEMD_INVOCATION_ID 不同之处在于，它仅用于来自 systemd 代码的消息（例如，来自系统/用户管理器的日志或来自执行 systemd 相关设置的分叉进程的日志）。

SYSLOG_FACILITY=, SYSLOG_IDENTIFIER=, SYSLOG_PID=, SYSLOG_TIMESTAMP=

Syslog 兼容性字段包含设施（格式为十进制字符串）、标识符字符串（即“标签”）、客户端 PID 和原始数据报中指定的时间戳。 （请注意，该标记通常派生自 glibc 的program_invocation_short_name 变量，请参阅program_invocation_short_name(3)。）

请注意，日志服务不会验证名称未以下划线为前缀的任何结构化日志字段的值，这包括任何与系统日志相关的字段，例如这些字段。因此，提供设施、PID 或日志级别的应用程序应正确格式化，即格式化为十进制字符串的数字整数。

DOCUMENTATION=

包含有关日志消息主题的详细信息的文档 URL。journalctl 等工具将在其输出中包含指向以这种方式指定的 URL 的超链接。应为“ http:// ”， “ https:// ”， “ file:/ ”， “ man: ” 或 “ info: ” URL。

TID=

日志消息源的线程 ID （TID），为数字。

UNIT=, USER_UNIT=

UNIT单元的名称。由系统和用户管理器在记录特定单元时使用。
当 或 --user-unit=name 与 journalctl（1） 一起使用时 --unit=name ， 将生成包含 “ UNIT=name.service ” 或“ USER_UNIT=name.service的匹配模式。

可信日志字段（Trusted Journal Fields）

以下划线为前缀的字段是受信任字段，即由日志隐式添加且无法由客户端代码更改的字段。

_PID=, _UID=, _GID=

日志记录源自的进程的进程、用户和组 ID，格式为十进制字符串。请注意，通过分叉进程的 “ stdout ” 或“ stderr获得的记录将包含对父进程（启动与 systemd-journald 的连接）有效的凭据。

_COMM=, _EXE=, _CMDLINE=

日志记录源自的进程的名称、可执行文件路径和命令行。

_CAP_EFFECTIVE=

日志记录来源的进程的会话和登录 UID，由内核审核子系统维护。

_CAP_EFFECTIVE=

日志记录来源的流程的有效能力（7）

The effective capabilities(7) of the process the journal entry originates from.

_AUDIT_SESSION=, _AUDIT_LOGINUID=

日志记录来源的进程的会话和登录 UID，由内核审核子系统维护。

_SYSTEMD_CGROUP=, _SYSTEMD_SLICE=, _SYSTEMD_UNIT=, _SYSTEMD_USER_UNIT=, _SYSTEMD_USER_SLICE=, _SYSTEMD_SESSION=, _SYSTEMD_OWNER_UID=

systemd 层次结构中的控制组路径、systemd 切片单元名称、systemd 单元名称、systemd 用户管理器中的单元名称（如果有）、systemd 会话 ID（如果有）以及日志记录来源的进程的 systemd 用户单元或 systemd 会话（如果有）的所有者 UID。

_SELINUX_CONTEXT=

日志记录源自的进程的 SELinux 安全上下文（标签）。

_SOURCE_REALTIME_TIMESTAMP=

消息的最早受信任时间戳（如果已知有）与日志的接收时间不同。这是自纪元 UTC 以来以微秒为单位的时间，格式为十进制字符串。

_BOOT_ID=

生成消息的启动的内核启动 ID，格式为 128 位十六进制字符串。

_MACHINE_ID=

原始主机的机器 ID，在 machine-id（5） 中可用。

_SYSTEMD_INVOCATION_ID=

生成消息的单元的运行时周期的调用 ID，可供单元的进程使用 $INVOCATION_ID （参见 systemd.exec（5））。

_HOSTNAME=

原始主机的名称。

_TRANSPORT=

日志服务如何接收日志记录。有效的传输方式包括：

audit

用于那些从内核审计子系统读取的用户

driver

对于内部生成的消息

syslog

对于通过本地 syslog 套接字和 syslog 协议接收的那些

journal

对于通过Native Journal Protocol接收的那些

stdout

对于从服务的标准输出或错误输出读取的用户

kernel

对于那些从内核中读取的人

_STREAM_ID=

仅适用于 “ _TRANSPORT=stdout ” 记录：指定在首次创建流连接时分配给流连接的随机 128 位 ID。此 ID 可用于从日志记录中重建单个日志流：具有相同流 ID 的所有日志记录都源自同一流。

_LINE_BREAK=

仅适用于 “ _TRANSPORT=stdout ” 记录：表示标准输出/错误流中的日志消息未以普通换行符（“ \n ”，即 ASCII 10）结尾。

具体来说，当设置时，此字段是（ nul 如果行以 NUL 字节终止）、line-max（如果达到最大日志行长度，如 journald.conf（5） 中配置）、 LineMax= eof （如果这是流的最后一个日志记录，并且流结束时没有最后一个换行符）或 pid-change （如果生成日志输出的进程在行中间发生更改）之一。

请注意，当使用普通换行符标记日志行结束时，不会生成此记录。

_NAMESPACE=

如果此文件是由管理非默认日志命名空间的 systemd-journald 实例编写的，则此字段包含命名空间标识符。参见 systemd-journald.service（8） 来了解日志命名空间的细节。

_RUNTIME_SCOPE=

一个字符串字段，该字段指定记录消息的运行时范围。如果是“ initrd ”，则当系统在 initrd 中运行时处理日志消息。如果 是 system ”，则日志消息是在系统切换到主机根文件系统执行后生成的。

内核日志字段 （Kernel Journal Fields）

内核字段是由源自内核并存储在日志中的信息使用的字段。

_KERNEL_DEVICE=

内核设备名称。

如果记录与块设备相关联，则包含设备节点的主要和次要编号，以“ : ” 分隔，并以“ b ” 为前缀。与字符设备类似，但以“ c ” 为前缀。

对于网络设备，这是以“ n ” 为前缀的接口索引。

对于所有其他设备，这是以 “ + ” 为前缀的子系统名称，后跟 “ : ” ，后跟内核设备名称。

_KERNEL_SUBSYSTEM=

内核子系统名称。

_UDEV_SYSNAME=

内核设备名称，显示在下面/sys/的设备树中。

_UDEV_DEVNODE=

此设备在 中的 /dev/ 设备节点路径。

_UDEV_DEVLINK=

指向 中 /dev/ 设备节点的其他符号链接名称。每个记录通常设置此字段不止一次。

代表其他程序登录的字段（Fields to log on behalf of a different program）

程序使用本节中的字段来指定它们代表另一个程序或单元进行日志记录。

systemd-coredump ，coredump 内核帮助程序使用的字段：

COREDUMP_UNIT=

用于注释包含来自系统和会话单元的核心转储的消息。参见 coredumpctl（1）。
Used to annotate messages containing coredumps from system and session units. See coredumpctl(1).

特权程序（当前为 UID 0）可能会附加 OBJECT_PID= 到消息。这将指示 systemd-journald 代表调用方附加其他字段：

OBJECT_PID=PID

此消息所属程序的 PID。

OBJECT_UID=, OBJECT_GID=, OBJECT_COMM=, OBJECT_EXE=, OBJECT_CMDLINE=, OBJECT_AUDIT_SESSION=, OBJECT_AUDIT_LOGINUID=, OBJECT_SYSTEMD_CGROUP=, OBJECT_SYSTEMD_SESSION=, OBJECT_SYSTEMD_OWNER_UID=, OBJECT_SYSTEMD_UNIT=, OBJECT_SYSTEMD_USER_UNIT=

这些是 systemd-journald 自动添加的附加字段。它们的含义与_UID= 、 _GID= 、 _COMM= _EXE= _CMDLINE= _AUDIT_SESSION= _AUDIT_LOGINUID= _SYSTEMD_CGROUP= _SYSTEMD_SESSION= _SYSTEMD_UNIT= _SYSTEMD_USER_UNIT= _SYSTEMD_OWNER_UID=和 如上所述 相同，只是描述的是 标识的 PID 进程，而不是记录消息的进程。

地址字段 （Address Fields）

在序列化为外部格式（如日志导出格式或日志 JSON 格式）期间，日志记录的地址将序列化为以双下划线为前缀的字段。请注意，当存储在日志中时，这些字段不是正确的字段，而是用于处理记录的元数据。它们不能通过调用（如 sd_journal_send（3）作为结构化日志记录的一部分写入。它们也不能用作sd_journal_add_match（3） 的匹配项。

__CURSOR=

__CURSOR=   #前面是两个下划线

记录的光标。游标是一个不透明的文本字符串，它唯一地描述了记录在日志中的位置，并且可以跨计算机、平台和日志文件进行移植。

__REALTIME_TIMESTAMP=

__REALTIME_TIMESTAMP=  #前面是两个下划线

日志收到记录时的挂钟时间 （ CLOCK_REALTIME ），自 UTC 纪元以来的微秒数，格式为十进制字符串。这与“ _SOURCE_REALTIME_TIMESTAMP= ” 具有不同的属性，因为它通常稍晚一些，但更有可能是单调的。

__MONOTONIC_TIMESTAMP=

__MONOTONIC_TIMESTAMP=  #前面是两个下划线

日志接收记录的时间点的单调时间 CLOCK_MONOTONIC 以微秒为单位，格式为十进制字符串。为了用作日志记录的地址，应将其与“ _BOOT_ID= ” 中的引导 ID 结合使用。

__SEQNUM=, __SEQNUM_ID=

__SEQNUM=, __SEQNUM_ID=  #前面是两个下划线

此日志记录源自的日志文件中的序列号（和关联的序列号 ID）。详见sd_journal_get_seqnum（3）。