Changes from second round of reviews

elastic · Nov 8, 2018 · fb2877b · fb2877b
1 parent 12149dc
commit fb2877b
Show file tree

Hide file tree

Showing 2 changed files with 96 additions and 28 deletions.
diff --git a/journalbeat/docs/config-options.asciidoc b/journalbeat/docs/config-options.asciidoc
@@ -57,9 +57,9 @@ journal.
 
 [[filter-using-translated-names]]
 .Example 3: Fetch log events for Redis running on Docker (uses translated field names)
-This example also configures {beatname_uc} to fetch log events for Redis running in a
-Docker container. However, in this example the fields are matched using the
-translated field names provided by {beatname_uc}.
+This example also configures {beatname_uc} to fetch log events for Redis running
+in a Docker container. However, in this example the fields are matched using the
+<<translated-fields,translated field names>> provided by {beatname_uc}.
 ["source","sh",subs="attributes"]
 ----
 {beatname_lc}.inputs:
@@ -86,15 +86,34 @@ into a single journal and reads them.
 
 If no paths are specified, {beatname_uc} reads from the default journal.
 
+[float]
+[id="{beatname_lc}-backoff"]
+==== `backoff`
+
+The number of seconds to wait before trying to read again from journals. The
+default is 1s.
+
+[float]
+[id="{beatname_lc}-max-backoff"]
+==== `max_backoff`
+
+The maximum number of seconds to wait before attempting to read again from
+journals. The default is 60s.
+
 [float]
 [id="{beatname_lc}-seek"]
 ==== `seek`
 
 The position to start reading the journal from. Valid settings are:
 
-* `head`: Starts reading at the beginning of the file, even after a reload or
-restart.
-* `tail`: Starts reading at the end of the file, even after a reload or restart.
+// REVIEWERS: Not sure if I've gotten this quite right. 
+
+* `head`: Starts reading at the beginning of the file. After a restart,
+{beatname_uc} resends all log messages in the journal.
+* `tail`: Starts reading at the end of the file. After a restart, 
+{beatname_uc} resends the last message, which might result in duplicates. If
+multiple log messages are written to a journal while {beatname_uc} is down,
+only the last log message is sent on restart. 
 * `cursor`: On first read, starts reading at the beginning of the file. After a
 reload or restart, continues reading at the last known position.
 
@@ -118,8 +137,8 @@ To reference fields, use one of the following:
 
 * The field name used by the systemd journal. For example,
 `CONTAINER_TAG=redis` (<<filter-using-field-names,see a full example>>).
-* The translated field name used by {beatname_uc}. For example,
-`container.image.tag=redis`
+* The <<translated-fields,translated field name>> used by
+{beatname_uc}. For example, `container.image.tag=redis`
 (<<filter-using-translated-names,see a full example>>). {beatname_uc}
 does not translate all fields from the journal. For custom fields, use the name
 specified in the systemd journal.
@@ -129,3 +148,72 @@ journals under the configured paths. When specified directly under the
 +{beatname_lc}+ namespace, the setting applies to all journals read by
 {beatname_uc}.
 
+[float]
+[[translated-fields]]
+=== Translated field names
+
+You can use the following translated names in filter expressions to reference
+journald fields:
+
+[horizontal]
+*Journald field name*:: *Translated name*
+`COREDUMP_UNIT`::             `journald.coredump.unit`
+`COREDUMP_USER_UNIT`::        `journald.coredump.user_unit`
+`OBJECT_AUDIT_LOGINUID`::     `journald.object.audit.login_uid`
+`OBJECT_AUDIT_SESSION`::      `journald.object.audit.session`
+`OBJECT_CMDLINE`::            `journald.object.cmd`
+`OBJECT_COMM`::               `journald.object.name`
+`OBJECT_EXE`::                `journald.object.executable`
+`OBJECT_GID`::                `journald.object.gid`
+`OBJECT_PID`::                `journald.object.pid`
+`OBJECT_SYSTEMD_OWNER_UID`::  `journald.object.systemd.owner_uid`
+`OBJECT_SYSTEMD_SESSION`::    `journald.object.systemd.session`
+`OBJECT_SYSTEMD_UNIT`::       `journald.object.systemd.unit`
+`OBJECT_SYSTEMD_USER_UNIT`::  `journald.object.systemd.user_unit`
+`OBJECT_UID`::                `journald.object.uid`
+`_AUDIT_LOGINUID`::            `process.audit.login_uid`
+`_AUDIT_SESSION`::             `process.audit.session`
+`_BOOT_ID`::                   `host.boot_id`
+`_CAP_EFFECTIVE`::             `process.capabilites`
+`_CMDLINE`::                   `process.cmd`
+`_CODE_FILE`::                 `journald.code.file`
+`_CODE_FUNC`::                 `journald.code.func`
+`_CODE_LINE`::                 `journald.code.line`
+`_COMM`::                      `process.name`
+`_EXE`::                       `process.executable`
+`_GID`::                       `process.uid`
+`_HOSTNAME`::                  `host.name`
+`_KERNEL_DEVICE`::            `journald.kernel.device`
+`_KERNEL_SUBSYSTEM`::         `journald.kernel.subsystem`
+`_MACHINE_ID`::                `host.id`
+`_MESSAGE`::                   `message`
+`_PID`::                       `process.pid`
+`_PRIORITY`::                  `syslog.priority`
+`_SYSLOG_FACILITY`::           `syslog.facility`
+`_SYSLOG_IDENTIFIER`::         `syslog.identifier`
+`_SYSLOG_PID`::                `syslog.pid`
+`_SYSTEMD_CGROUP`::            `systemd.cgroup`
+`_SYSTEMD_INVOCATION_ID`::    `systemd.invocation_id`
+`_SYSTEMD_OWNER_UID`::         `systemd.owner_uid`
+`_SYSTEMD_SESSION`::           `systemd.session`
+`_SYSTEMD_SLICE`::             `systemd.slice`
+`_SYSTEMD_UNIT`::              `systemd.unit`
+`_SYSTEMD_USER_SLICE`::       `systemd.user_slice`
+`_SYSTEMD_USER_UNIT`::         `systemd.user_unit`
+`_TRANSPORT`::                 `systemd.transport`
+`_UDEV_DEVLINK`::             `journald.kernel.device_symlinks`
+`_UDEV_DEVNODE`::             `journald.kernel.device_node_path`
+`_UDEV_SYSNAME`::             `journald.kernel.device_name`
+`_UID`::                       `process.uid`
+
+
+The following translated fields for
+https://docs.docker.com/config/containers/logging/journald/[Docker] are also
+available: 
+
+[horizontal]
+`CONTAINER_ID`::              `conatiner.id_truncated`
+`CONTAINER_ID_FULL`::         `container.id`
+`CONTAINER_NAME`::            `container.name`
+`CONTAINER_PARTIAL_MESSAGE`:: `container.partial`
+`CONTAINER_TAG`::             `container.image.tag`
diff --git a/journalbeat/docs/general-options.asciidoc b/journalbeat/docs/general-options.asciidoc
@@ -28,26 +28,6 @@ data path. See the <<directory-layout>> section for details. The default is `${p
 {beatname_lc}.registry_file: registry
 ----
 
-[float]
-[id="{beatname_lc}-backoff"]
-==== `backoff`
-
-The number of seconds to wait before trying to read again from journals. The
-default is 1s.
-
-[float]
-[id="{beatname_lc}-backoff-factor"]
-==== `backoff_factor`
-
-Multiplier of the backoff value. The default is 1s.
-
-[float]
-[id="{beatname_lc}-max-backoff"]
-==== `max_backoff`
-
-The maximum number of seconds to wait before attempting to read again from
-journals. The default is 60s.
-
 [float]
 ==== `seek`