Aggregating Container Logs

Overview

As an OpenShift Origin cluster administrator, you can deploy the EFK stack to aggregate logs for a range of OpenShift Origin services. Application developers can view the logs of the projects for which they have view access. The EFK stack aggregates logs from hosts and applications, whether coming from multiple containers or even deleted pods.

The EFK stack is a modified version of the ELK stack and is comprised of:

Elasticsearch (ES): An object store where all logs are stored.
Fluentd: Gathers logs from nodes and feeds them to Elasticsearch.
Kibana: A web UI for Elasticsearch.
Curator: Removes old logs from Elasticsearch.

Once deployed in a cluster, the stack aggregates logs from all nodes and projects into Elasticsearch, and provides a Kibana UI to view any logs. Cluster administrators can view all logs, but application developers can only view logs for projects they have permission to view. The stack components communicate securely.

Aggregated logging is supported using the json-file or journald driver in Docker. The Docker log driver is set to journald as the default for all nodes. See Updating Fluentd’s Log Source After a Docker Log Driver Update for more information about switching between json-file and journald. Fluentd automatically determines which log driver (journald or json-file) the container runtime is using.

When the log driver is set to journald, Fluentd reads journald logs. When set to json-file Fluentd reads from /var/log/containers.

See Managing Docker Container Logs for information on json-file logging driver options to manage container logs and prevent filling node disks.

If Docker log-driver is set to journald, there is no log rate throttling with the journald driver. As a result, there is a risk of denial-of-service attacks from rogue containers.

Pre-deployment Configuration

An Ansible playbook is available to deploy and upgrade aggregated logging. You should familiarize yourself with the advanced installation and configuration section. This provides information for preparing to use Ansible and includes information about configuration. Parameters are added to the Ansible inventory file to configure various areas of the EFK stack.
Review the sizing guidelines to determine how best to configure your deployment.
Ensure that you have deployed a router for the cluster.
Ensure that you have the necessary storage for Elasticsearch. Note that each Elasticsearch replica requires its own storage volume. See Elasticsearch for more information.

Choose a project. Once deployed, the EFK stack collects logs for every project within your OpenShift Origin cluster. The examples in this section use the default project logging. The Ansible playbook creates the project for you if it does not already exist. You will only need to create a project if you want to specify a node-selector on it. Otherwise, the openshift-logging role will create a project.

$ oc adm new-project logging --node-selector=""
$ oc project logging

Specifying an empty node selector on the project is recommended, as Fluentd should be deployed throughout the cluster and any selector would restrict where it is deployed. To control component placement, specify node selectors per component to be applied to their deployment configurations.

Specifying Logging Ansible Variables

Parameters for the EFK deployment may be specified to the inventory host file to override the defaults. Read the Elasticsearch and the Fluentd sections before choosing parameters:

By default the Elasticsearch service uses port 9300 for TCP communication between nodes in a cluster.

Parameter Description

Parameter	Description
`openshift_logging_image_prefix`	The prefix for logging component images. For example, setting the prefix to openshift/origin- creates openshift/origin-logging-fluentd:v1.5.
`openshift_logging_image_version`	The version for logging component images. For example, setting the version to v1.5 creates openshift/origin-logging-fluentd:v1.5.
`openshift_logging_use_ops`	If set to `true`, configures a second Elasticsearch cluster and Kibana for operations logs. Fluentd splits logs between the main cluster and a cluster reserved for operations logs, which consists of the logs from the projects default, openshift, and openshift-infra, as well as Docker, OpenShift, and system logs from the journal. This means a second Elasticsearch cluster and Kibana are deployed. The deployments are distinguishable by the -ops suffix included in their names and have parallel deployment options listed below and described in Creating the Curator Configuration.
`openshift_logging_master_url`	The URL for the Kubernetes master, this does not need to be public facing but should be accessible from within the cluster. For example, https://<PRIVATE-MASTER-URL>:8443.
`openshift_logging_master_public_url`	The public facing URL for the Kubernetes master. This is used for Authentication redirection by the Kibana proxy. For example, https://<CONSOLE-PUBLIC-URL-MASTER>:8443.
`openshift_logging_namespace`	The namespace where Aggregated Logging is deployed.
`openshift_logging_install_logging`	Set to `true` to install logging. Set to `false` to uninstall logging.
`openshift_logging_purge_logging`	The common uninstall keeps PVC to prevent unwanted data loss during reinstalls. To ensure that the Ansible playbook completely and irreversibly removes all logging persistent data including PVC, set `openshift_logging_install_logging` to 'false' to trigger uninstallation and `openshift_logging_purge_logging` to 'true'. The default is set to 'false'.
`openshift_logging_install_eventrouter`	Coupled with `openshift_logging_install_logging`. When both are set to 'true', eventrouter will be installed. When both are 'false', eventrouter will be uninstalled.
`openshift_logging_eventrouter_image_prefix`	The prefix for the eventrouter logging image. The default is set to `openshift_logging_image_prefix`.
`openshift_logging_eventrouter_image_version`	The image version for the logging eventrouter. The default is set to 'latest'.
`openshift_logging_eventrouter_sink`	Select a sink for eventrouter, supported `stdout` and `glog`. The default is set to `stdout`.
`openshift_logging_eventrouter_nodeselector`	A map of labels, such as `"node":"infra"`,`"region":"west"`, to select the nodes where the pod will land.
`openshift_logging_eventrouter_replicas`	The default is set to '1'.
`openshift_logging_eventrouter_cpu_limit`	The minimum amount of CPU to allocate to eventrouter. The default is set to '100m'.
`openshift_logging_eventrouter_memory_limit`	The memory limit for eventrouter pods. The default is set to '128Mi'.
`openshift_logging_eventrouter_namespace`	The namespace where eventrouter is deployed. The default is set to 'default'.
`openshift_logging_image_pull_secret`	Specify the name of an existing pull secret to be used for pulling component images from an authenticated registry.
`openshift_logging_curator_default_days`	The default minimum age (in days) Curator uses for deleting log records.
`openshift_logging_curator_run_hour`	The hour of the day Curator will run.
`openshift_logging_curator_run_minute`	The minute of the hour Curator will run.
`openshift_logging_curator_run_timezone`	The timezone Curator uses for figuring out it’s run time.
`openshift_logging_curator_script_log_level`	The script log level for Curator.
`openshift_logging_curator_log_level`	The log level for the Curator process.
`openshift_logging_curator_cpu_limit`	The amount of CPU to allocate to Curator.
`openshift_logging_curator_memory_limit`	The amount of memory to allocate to Curator.
`openshift_logging_curator_nodeselector`	A node selector that specifies which nodes are eligible targets for deploying Curator instances.
`openshift_logging_curator_ops_cpu_limit`	Equivalent to `openshift_logging_curator_cpu_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_curator_ops_memory_limit`	Equivalent to `openshift_logging_curator_memory_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_kibana_hostname`	The external host name for web clients to reach Kibana.
`openshift_logging_kibana_cpu_limit`	The amount of CPU to allocate to Kibana.
`openshift_logging_kibana_memory_limit`	The amount of memory to allocate to Kibana.
`openshift_logging_kibana_proxy_debug`	When `true`, set the Kibana Proxy log level to DEBUG.
`openshift_logging_kibana_proxy_cpu_limit`	The amount of CPU to allocate to Kibana proxy.
`openshift_logging_kibana_proxy_memory_limit`	The amount of memory to allocate to Kibana proxy.
`openshift_logging_kibana_replica_count`	The number of to which Kibana should be scaled up.
`openshift_logging_kibana_nodeselector`	A node selector that specifies which nodes are eligible targets for deploying Kibana instances.
`openshift_logging_kibana_key`	The public facing key to use when creating the Kibana route.
`openshift_logging_kibana_cert`	The cert that matches the key when creating the Kibana route.
`openshift_logging_kibana_ca`	Optional. The CA to goes with the key and cert used when creating the Kibana route.
`openshift_logging_kibana_ops_hostname`	Equivalent to `openshift_logging_kibana_hostname` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_kibana_ops_cpu_limit`	Equivalent to `openshift_logging_kibana_cpu_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_kibana_ops_memory_limit`	Equivalent to `openshift_logging_kibana_memory_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_kibana_ops_proxy_debug`	Equivalent to `openshift_logging_kibana_proxy_debug` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_kibana_ops_proxy_cpu_limit`	Equivalent to `openshift_logging_kibana_proxy_cpu_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_kibana_ops_proxy_memory_limit`	Equivalent to `openshift_logging_kibana_proxy_memory_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_kibana_ops_replica_count`	Equivalent to `openshift_logging_kibana_replica_count` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_allow_external`	Set to `true` to expose Elasticsearch as a reencrypt route. Set to `false` by default.
`openshift_logging_es_hostname`	The external-facing hostname to use for the route and the TLS server certificate. The default is set to `es`. For example, if `openshift_master_default_subdomain` is set to `=example.test`, then the default value of `openshift_logging_es_hostname` will be `es.example.test`.
`openshift_logging_es_cert`	The location of the certificate Elasticsearch uses for the external TLS server cert. The default is a generated cert.
`openshift_logging_es_key`	The location of the key Elasticsearch uses for the external TLS server cert. The default is a generated key.
`openshift_logging_es_ca_ext`	The location of the CA cert Elasticsearch uses for the external TLS server cert. The default is the internal CA.
`openshift_logging_es_ops_allow_external`	Set to `true` to expose Elasticsearch as a reencrypt route. Set to `false` by defaut.
`openshift_logging_es_ops_hostname`	The external-facing hostname to use for the route and the TLS server certificate. The default is set to `es-ops`. For example, if `openshift_master_default_subdomain` is set to `=example.test`, then the default value of `openshift_logging_es_ops_hostname` will be `es-ops.example.test`.
`openshift_logging_es_ops_cert`	The location of the certificate Elasticsearch uses for the external TLS server cert. The default is a generated cert.
`openshift_logging_es_ops_key`	The location of the key Elasticsearch uses for the external TLS server cert. The default is a generated key.
`openshift_logging_es_ops_ca_ext`	The location of the CA cert Elasticsearch uses for the external TLS server cert. The default is the internal CA.
`openshift_logging_fluentd_nodeselector`	A node selector that specifies which nodes are eligible targets for deploying Fluentd instances. Any node where Fluentd should run (typically, all) must have this label before Fluentd is able to run and collect logs. When scaling up the Aggregated Logging cluster after installation, the `openshift_logging` role labels nodes provided by `openshift_logging_fluentd_hosts` with this node selector. As part of the installation, it is recommended that you add the Fluentd node selector label to the list of persisted node labels.
`openshift_logging_fluentd_cpu_limit`	The CPU limit for Fluentd pods.
`openshift_logging_fluentd_memory_limit`	The memory limit for Fluentd pods.
`openshift_logging_fluentd_journal_read_from_head`	Set to `true` if Fluentd should read from the head of Journal when first starting up, using this may cause a delay in ES receiving current log records.
`openshift_logging_fluentd_hosts`	List of nodes that should be labeled for Fluentd to be deployed.
`openshift_logging_fluentd_audit_container_engine`	When `openshift_logging_fluentd_audit_container_engine` is set to `true`, the audit log of the container engine is collected and stored in ES.
`openshift_logging_fluentd_audit_file`	Location of audit log file. The default is `/var/log/audit/audit.log`.
`openshift_logging_fluentd_audit_pos_file`	Location of the Fluentd `in_tail` position file for the audit log file. The default is `/var/log/audit/audit.log.pos`.
`openshift_logging_es_host`	The name of the ES service where Fluentd should send logs.
`openshift_logging_es_port`	The port for the ES service where Fluentd should send logs.
`openshift_logging_es_ca`	The location of the CA Fluentd uses to communicate with `openshift_logging_es_host`.
`openshift_logging_es_client_cert`	The location of the client certificate Fluentd uses for `openshift_logging_es_host`.
`openshift_logging_es_client_key`	The location of the client key Fluentd uses for `openshift_logging_es_host`.
`openshift_logging_es_cluster_size`	Elasticsearch replicas to deploy. Redundancy requires at least three or more.
`openshift_logging_es_cpu_limit`	The amount of CPU limit for the ES cluster.
`openshift_logging_es_memory_limit`	Amount of RAM to reserve per Elasticsearch instance. It must be at least 512M. Possible suffixes are G,g,M,m.
`openshift_logging_es_number_of_replicas`	The number of replica shards per primary shard for every new index. Defaults to '0'. A minimum of `1` is advisable for production clusters.
`openshift_logging_es_number_of_shards`	The number of primary shards for every new index created in ES. Defaults to '1'.
`openshift_logging_es_pv_selector`	A key/value map added to a PVC in order to select specific PVs.
`openshift_logging_es_pvc_dynamic`	If available for your cluster, set to `true` to have PVC claims annotated so that their backing storage is dynamically provisioned.
`openshift_logging_es_pvc_size`	Size of the persistent volume claim to create per Elasticsearch instance. For example, 100G. If omitted, no PVCs are created and ephemeral volumes are used instead.
`openshift_logging_es_pvc_prefix`	Prefix for the names of persistent volume claims to be used as storage for Elasticsearch instances. A number is appended per instance, such as logging-es-1. If they do not already exist, they are created with size `es-pvc-size`. When `openshift_logging_es_pvc_prefix` is set, and: `openshift_logging_es_pvc_dynamic`=`true`, the value for `openshift_logging_es_pvc_size` is optional. `openshift_logging_es_pvc_dynamic`=`false`, the value for `openshift_logging_es_pvc_size` must be set.
`openshift_logging_es_recover_after_time`	The amount of time ES will wait before it tries to recover.
`openshift_logging_es_storage_group`	Number of a supplemental group ID for access to Elasticsearch storage volumes. Backing volumes should allow access by this group ID.
`openshift_logging_es_nodeselector`	A node selector specified as a map that determines which nodes are eligible targets for deploying Elasticsearch instances. This can be used to place these instances on nodes reserved or optimized for running them. For example, the selector could be `{"node-type":"infrastructure"}`. At least one active node must have this label before Elasticsearch will deploy.
`openshift_logging_es_ops_allow_cluster_reader`	Set to `true` if cluster-reader role is allowed to read operation logs.
`openshift_logging_es_ops_host`	Equivalent to `openshift_logging_es_host` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_port`	Equivalent to `openshift_logging_es_port` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_ca`	Equivalent to `openshift_logging_es_ca` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_client_cert`	Equivalent to `openshift_logging_es_client_cert` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_client_key`	Equivalent to `openshift_logging_es_client_key` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_cluster_size`	Equivalent to `openshift_logging_es_cluster_size` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_cpu_limit`	Equivalent to `openshift_logging_es_cpu_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_memory_limit`	Equivalent to `openshift_logging_es_memory_limit` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_pv_selector`	Equivalent to `openshift_logging_es_pv_selector` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_pvc_dynamic`	Equivalent to `openshift_logging_es_pvc_dynamic` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_pvc_size`	Equivalent to `openshift_logging_es_pvc_size` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_pvc_prefix`	Equivalent to `openshift_logging_es_pvc_prefix` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_recover_after_time`	Equivalent to `openshift_logging_es_recovery_after_time` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_storage_group`	Equivalent to `openshift_logging_es_storage_group` for Ops cluster when `openshift_logging_use_ops` is set to `true`.
`openshift_logging_es_ops_nodeselector`	A node selector that specifies which nodes are eligible targets for deploying Elasticsearch instances. This can be used to place these instances on nodes reserved or optimized for running them. For example, the selector could be `node-type=infrastructure`. At least one active node must have this label before Elasticsearch will deploy.
`openshift_logging_elasticsearch_kibana_index_mode`	The default value, `unique`, allows users to each have their own Kibana index. In this mode, their saved queries, visualizations, and dashboards are not shared. You may also set the value `shared_ops`. In this mode, all operations users share a Kibana index which allows each operations user to see the the same queries, visualizations, and dashboards.
`openshift_logging_kibana_ops_nodeselector`	A node selector that specifies which nodes are eligible targets for deploying Kibana instances.
`openshift_logging_curator_ops_nodeselector`	A node selector that specifies which nodes are eligible targets for deploying Curator instances.

openshift_logging_image_prefix

The prefix for logging component images. For example, setting the prefix to openshift/origin- creates openshift/origin-logging-fluentd:v1.5.

openshift_logging_image_version

The version for logging component images. For example, setting the version to v1.5 creates openshift/origin-logging-fluentd:v1.5.

openshift_logging_use_ops

If set to true, configures a second Elasticsearch cluster and Kibana for operations logs. Fluentd splits logs between the main cluster and a cluster reserved for operations logs, which consists of the logs from the projects default, openshift, and openshift-infra, as well as Docker, OpenShift, and system logs from the journal. This means a second Elasticsearch cluster and Kibana are deployed. The deployments are distinguishable by the -ops suffix included in their names and have parallel deployment options listed below and described in Creating the Curator Configuration.

openshift_logging_master_url

The URL for the Kubernetes master, this does not need to be public facing but should be accessible from within the cluster. For example, https://<PRIVATE-MASTER-URL>:8443.

openshift_logging_master_public_url

The public facing URL for the Kubernetes master. This is used for Authentication redirection by the Kibana proxy. For example, https://<CONSOLE-PUBLIC-URL-MASTER>:8443.

openshift_logging_namespace

The namespace where Aggregated Logging is deployed.

openshift_logging_install_logging

Set to true to install logging. Set to false to uninstall logging.

openshift_logging_purge_logging

The common uninstall keeps PVC to prevent unwanted data loss during reinstalls. To ensure that the Ansible playbook completely and irreversibly removes all logging persistent data including PVC, set openshift_logging_install_logging to 'false' to trigger uninstallation and openshift_logging_purge_logging to 'true'. The default is set to 'false'.

openshift_logging_install_eventrouter

Coupled with openshift_logging_install_logging. When both are set to 'true', eventrouter will be installed. When both are 'false', eventrouter will be uninstalled.

openshift_logging_eventrouter_image_prefix

The prefix for the eventrouter logging image. The default is set to openshift_logging_image_prefix.

openshift_logging_eventrouter_image_version

The image version for the logging eventrouter. The default is set to 'latest'.

openshift_logging_eventrouter_sink

Select a sink for eventrouter, supported stdout and glog. The default is set to stdout.

openshift_logging_eventrouter_nodeselector

A map of labels, such as "node":"infra","region":"west", to select the nodes where the pod will land.

openshift_logging_eventrouter_replicas

The default is set to '1'.

openshift_logging_eventrouter_cpu_limit

The minimum amount of CPU to allocate to eventrouter. The default is set to '100m'.

openshift_logging_eventrouter_memory_limit

The memory limit for eventrouter pods. The default is set to '128Mi'.

openshift_logging_eventrouter_namespace

The namespace where eventrouter is deployed. The default is set to 'default'.

openshift_logging_image_pull_secret

Specify the name of an existing pull secret to be used for pulling component images from an authenticated registry.

openshift_logging_curator_default_days

The default minimum age (in days) Curator uses for deleting log records.

openshift_logging_curator_run_hour

The hour of the day Curator will run.

openshift_logging_curator_run_minute

The minute of the hour Curator will run.

openshift_logging_curator_run_timezone

The timezone Curator uses for figuring out it’s run time.

openshift_logging_curator_script_log_level

The script log level for Curator.

openshift_logging_curator_log_level

The log level for the Curator process.

openshift_logging_curator_cpu_limit

The amount of CPU to allocate to Curator.

openshift_logging_curator_memory_limit

The amount of memory to allocate to Curator.

openshift_logging_curator_nodeselector

A node selector that specifies which nodes are eligible targets for deploying Curator instances.

openshift_logging_curator_ops_cpu_limit

Equivalent to openshift_logging_curator_cpu_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_curator_ops_memory_limit

Equivalent to openshift_logging_curator_memory_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_kibana_hostname

The external host name for web clients to reach Kibana.

openshift_logging_kibana_cpu_limit

The amount of CPU to allocate to Kibana.

openshift_logging_kibana_memory_limit

The amount of memory to allocate to Kibana.

openshift_logging_kibana_proxy_debug

When true, set the Kibana Proxy log level to DEBUG.

openshift_logging_kibana_proxy_cpu_limit

The amount of CPU to allocate to Kibana proxy.

openshift_logging_kibana_proxy_memory_limit

The amount of memory to allocate to Kibana proxy.

openshift_logging_kibana_replica_count

The number of to which Kibana should be scaled up.

openshift_logging_kibana_nodeselector

A node selector that specifies which nodes are eligible targets for deploying Kibana instances.

openshift_logging_kibana_key

The public facing key to use when creating the Kibana route.

openshift_logging_kibana_cert

The cert that matches the key when creating the Kibana route.

openshift_logging_kibana_ca

Optional. The CA to goes with the key and cert used when creating the Kibana route.

openshift_logging_kibana_ops_hostname

Equivalent to openshift_logging_kibana_hostname for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_kibana_ops_cpu_limit

Equivalent to openshift_logging_kibana_cpu_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_kibana_ops_memory_limit

Equivalent to openshift_logging_kibana_memory_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_kibana_ops_proxy_debug

Equivalent to openshift_logging_kibana_proxy_debug for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_kibana_ops_proxy_cpu_limit

Equivalent to openshift_logging_kibana_proxy_cpu_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_kibana_ops_proxy_memory_limit

Equivalent to openshift_logging_kibana_proxy_memory_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_kibana_ops_replica_count

Equivalent to openshift_logging_kibana_replica_count for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_allow_external

Set to true to expose Elasticsearch as a reencrypt route. Set to false by default.

openshift_logging_es_hostname

The external-facing hostname to use for the route and the TLS server certificate. The default is set to es.

For example, if openshift_master_default_subdomain is set to =example.test, then the default value of openshift_logging_es_hostname will be es.example.test.

openshift_logging_es_cert

The location of the certificate Elasticsearch uses for the external TLS server cert. The default is a generated cert.

openshift_logging_es_key

The location of the key Elasticsearch uses for the external TLS server cert. The default is a generated key.

openshift_logging_es_ca_ext

The location of the CA cert Elasticsearch uses for the external TLS server cert. The default is the internal CA.

openshift_logging_es_ops_allow_external

Set to true to expose Elasticsearch as a reencrypt route. Set to false by defaut.

openshift_logging_es_ops_hostname

The external-facing hostname to use for the route and the TLS server certificate. The default is set to es-ops.

For example, if openshift_master_default_subdomain is set to =example.test, then the default value of openshift_logging_es_ops_hostname will be es-ops.example.test.

openshift_logging_es_ops_cert

The location of the certificate Elasticsearch uses for the external TLS server cert. The default is a generated cert.

openshift_logging_es_ops_key

The location of the key Elasticsearch uses for the external TLS server cert. The default is a generated key.

openshift_logging_es_ops_ca_ext

The location of the CA cert Elasticsearch uses for the external TLS server cert. The default is the internal CA.

openshift_logging_fluentd_nodeselector

A node selector that specifies which nodes are eligible targets for deploying Fluentd instances. Any node where Fluentd should run (typically, all) must have this label before Fluentd is able to run and collect logs.

When scaling up the Aggregated Logging cluster after installation, the openshift_logging role labels nodes provided by openshift_logging_fluentd_hosts with this node selector.

As part of the installation, it is recommended that you add the Fluentd node selector label to the list of persisted node labels.

openshift_logging_fluentd_cpu_limit

The CPU limit for Fluentd pods.

openshift_logging_fluentd_memory_limit

The memory limit for Fluentd pods.

openshift_logging_fluentd_journal_read_from_head

Set to true if Fluentd should read from the head of Journal when first starting up, using this may cause a delay in ES receiving current log records.

openshift_logging_fluentd_hosts

List of nodes that should be labeled for Fluentd to be deployed.

openshift_logging_fluentd_audit_container_engine

When openshift_logging_fluentd_audit_container_engine is set to true, the audit log of the container engine is collected and stored in ES.

openshift_logging_fluentd_audit_file

Location of audit log file. The default is /var/log/audit/audit.log.

openshift_logging_fluentd_audit_pos_file

Location of the Fluentd in_tail position file for the audit log file. The default is /var/log/audit/audit.log.pos.

openshift_logging_es_host

The name of the ES service where Fluentd should send logs.

openshift_logging_es_port

The port for the ES service where Fluentd should send logs.

openshift_logging_es_ca

The location of the CA Fluentd uses to communicate with openshift_logging_es_host.

openshift_logging_es_client_cert

The location of the client certificate Fluentd uses for openshift_logging_es_host.

openshift_logging_es_client_key

The location of the client key Fluentd uses for openshift_logging_es_host.

openshift_logging_es_cluster_size

Elasticsearch replicas to deploy. Redundancy requires at least three or more.

openshift_logging_es_cpu_limit

The amount of CPU limit for the ES cluster.

openshift_logging_es_memory_limit

Amount of RAM to reserve per Elasticsearch instance. It must be at least 512M. Possible suffixes are G,g,M,m.

openshift_logging_es_number_of_replicas

The number of replica shards per primary shard for every new index. Defaults to '0'. A minimum of 1 is advisable for production clusters.

openshift_logging_es_number_of_shards

The number of primary shards for every new index created in ES. Defaults to '1'.

openshift_logging_es_pv_selector

A key/value map added to a PVC in order to select specific PVs.

openshift_logging_es_pvc_dynamic

If available for your cluster, set to true to have PVC claims annotated so that their backing storage is dynamically provisioned.

openshift_logging_es_pvc_size

Size of the persistent volume claim to create per Elasticsearch instance. For example, 100G. If omitted, no PVCs are created and ephemeral volumes are used instead.

openshift_logging_es_pvc_prefix

Prefix for the names of persistent volume claims to be used as storage for Elasticsearch instances. A number is appended per instance, such as logging-es-1. If they do not already exist, they are created with size es-pvc-size.

When openshift_logging_es_pvc_prefix is set, and:

openshift_logging_es_pvc_dynamic=true, the value for openshift_logging_es_pvc_size is optional.
openshift_logging_es_pvc_dynamic=false, the value for openshift_logging_es_pvc_size must be set.

openshift_logging_es_recover_after_time

The amount of time ES will wait before it tries to recover.

openshift_logging_es_storage_group

Number of a supplemental group ID for access to Elasticsearch storage volumes. Backing volumes should allow access by this group ID.

openshift_logging_es_nodeselector

A node selector specified as a map that determines which nodes are eligible targets for deploying Elasticsearch instances. This can be used to place these instances on nodes reserved or optimized for running them. For example, the selector could be {"node-type":"infrastructure"}. At least one active node must have this label before Elasticsearch will deploy.

openshift_logging_es_ops_allow_cluster_reader

Set to true if cluster-reader role is allowed to read operation logs.

openshift_logging_es_ops_host

Equivalent to openshift_logging_es_host for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_port

Equivalent to openshift_logging_es_port for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_ca

Equivalent to openshift_logging_es_ca for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_client_cert

Equivalent to openshift_logging_es_client_cert for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_client_key

Equivalent to openshift_logging_es_client_key for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_cluster_size

Equivalent to openshift_logging_es_cluster_size for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_cpu_limit

Equivalent to openshift_logging_es_cpu_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_memory_limit

Equivalent to openshift_logging_es_memory_limit for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_pv_selector

Equivalent to openshift_logging_es_pv_selector for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_pvc_dynamic

Equivalent to openshift_logging_es_pvc_dynamic for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_pvc_size

Equivalent to openshift_logging_es_pvc_size for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_pvc_prefix

Equivalent to openshift_logging_es_pvc_prefix for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_recover_after_time

Equivalent to openshift_logging_es_recovery_after_time for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_storage_group

Equivalent to openshift_logging_es_storage_group for Ops cluster when openshift_logging_use_ops is set to true.

openshift_logging_es_ops_nodeselector

A node selector that specifies which nodes are eligible targets for deploying Elasticsearch instances. This can be used to place these instances on nodes reserved or optimized for running them. For example, the selector could be node-type=infrastructure. At least one active node must have this label before Elasticsearch will deploy.

openshift_logging_elasticsearch_kibana_index_mode

The default value, unique, allows users to each have their own Kibana index. In this mode, their saved queries, visualizations, and dashboards are not shared.

You may also set the value shared_ops. In this mode, all operations users share a Kibana index which allows each operations user to see the the same queries, visualizations, and dashboards.

openshift_logging_kibana_ops_nodeselector

A node selector that specifies which nodes are eligible targets for deploying Kibana instances.

openshift_logging_curator_ops_nodeselector

A node selector that specifies which nodes are eligible targets for deploying Curator instances.

Custom Certificates

You can specify custom certificates using the following inventory variables instead of relying on those generated during the deployment process. These certificates are used to encrypt and secure communication between a user’s browser and Kibana. The security-related files will be generated if they are not supplied.

File Name Description

File Name	Description
`openshift_logging_kibana_cert`	A browser-facing certificate for the Kibana server.
`openshift_logging_kibana_key`	A key to be used with the browser-facing Kibana certificate.
`openshift_logging_kibana_ca`	The absolute path on the control node to the CA file to use for the browser facing Kibana certs.
`openshift_logging_kibana_ops_cert`	A browser-facing certificate for the Ops Kibana server.
`openshift_logging_kibana_ops_key`	A key to be used with the browser-facing Ops Kibana certificate.
`openshift_logging_kibana_ops_ca`	The absolute path on the control node to the CA file to use for the browser facing ops Kibana certs.

openshift_logging_kibana_cert

A browser-facing certificate for the Kibana server.

openshift_logging_kibana_key

A key to be used with the browser-facing Kibana certificate.

openshift_logging_kibana_ca

The absolute path on the control node to the CA file to use for the browser facing Kibana certs.

openshift_logging_kibana_ops_cert

A browser-facing certificate for the Ops Kibana server.

openshift_logging_kibana_ops_key

A key to be used with the browser-facing Ops Kibana certificate.

openshift_logging_kibana_ops_ca

The absolute path on the control node to the CA file to use for the browser facing ops Kibana certs.

Deploying the EFK Stack

The EFK stack is deployed using an Ansible playbook to the EFK components. Run the playbook from the default OpenShift Ansible location using the default inventory file.

$ ansible-playbook playbooks/openshift-logging/config.yml

Running the playbook deploys all resources needed to support the stack; such as Secrets, ServiceAccounts, and DeploymentConfigs. The playbook waits to deploy the component pods until the stack is running. If the wait steps fail, the deployment could still be successful; it may be retrieving the component images from the registry which can take up to a few minutes. You can watch the process with:

$ oc get pods -w

They will eventually enter Running status. For additional details about the status of the pods during deployment by retrieving associated events:

$ oc describe pods/<pod_name>

Check the logs if the pods do not run successfully:

$ oc logs -f <pod_name>

Understanding and Adjusting the Deployment

This section describes adjustments that you can make to deployed components.

Ops Cluster

The logs for the default, openshift, and openshift-infra projects are automatically aggregated and grouped into the .operations item in the Kibana interface.

The project where you have deployed the EFK stack (logging, as documented here) is not aggregated into .operations and is found under its ID.

If you set openshift_logging_use_ops to true in your inventory file, Fluentd is configured to split logs between the main Elasticsearch cluster and another cluster reserved for operations logs, which are defined as node system logs and the projects default, openshift, and openshift-infra. Therefore, a separate Elasticsearch cluster, a separate Kibana, and a separate Curator are deployed to index, access, and manage operations logs. These deployments are set apart with names that include -ops. Keep these separate deployments in mind if you enable this option. Most of the following discussion also applies to the operations cluster if present, just with the names changed to include -ops.

Elasticsearch

A highly-available environment requires at least three replicas of Elasticsearch; each on a different host. Elasticsearch replicas require their own storage, but an OpenShift Origin deployment configuration shares storage volumes between all its pods. So, when scaled up, the EFK deployer ensures each replica of Elasticsearch has its own deployment configuration.

It is possible to scale your cluster up after creation by modifying the openshift_logging_es_cluser_size in the inventory file and re-running the logging playbook. Additional clustering parameters can be modified and are described in Specifying Logging Ansible Variables.

Refer to Elastic’s documentation for considerations involved in choosing storage and network location as directed below.

Viewing all Elasticsearch Deployments

To view all current Elasticsearch deployments:

$ oc get dc --selector logging-infra=elasticsearch

Node Selector

Because Elasticsearch can use a lot of resources, all members of a cluster should have low latency network connections to each other and to any remote storage. Ensure this by directing the instances to dedicated nodes, or a dedicated region within your cluster, using a node selector.

To configure a node selector, specify the openshift_logging_es_nodeselector configuration option in the inventory file. This applies to all Elasticsearch deployments; if you need to individualize the node selectors, you must manually edit each deployment configuration after deployment. The node selector is specified as a python compatible dict. For example, {"node-type":"infra", "region":"east"}.

Persistent Elasticsearch Storage

By default, the openshift_logging Ansible role creates an ephemeral deployment in which all of a pod’s data is lost upon restart. For production usage, specify a persistent storage volume for each Elasticsearch deployment configuration. You can create the necessary persistent volume claims before deploying or have them created for you. The PVCs must be named to match the openshift_logging_es_pvc_prefix setting, which defaults to logging-es-; each PVC name will have a sequence number added to it, so logging-es-1, logging-es-2, and so on. If a PVC needed for the deployment exists already, it is used; if not, and openshift_logging_es_pvc_size has been specified, it is created with a request for that size.

Using NFS storage as a volume or a persistent volume (or via NAS such as Gluster) is not supported for Elasticsearch storage, as Lucene relies on file system behavior that NFS does not supply. Data corruption and other problems can occur. If NFS storage is a requirement, you can allocate a large file on a volume to serve as a storage device and mount it locally on one host. For example, if your NFS storage volume is mounted at /nfs/storage:

$ truncate -s 1T /nfs/storage/elasticsearch-1
$ mkfs.xfs /nfs/storage/elasticsearch-1
$ mount -o loop /nfs/storage/elasticsearch-1 /usr/local/es-storage
$ chown 1000:1000 /usr/local/es-storage

Then, use /usr/local/es-storage as a host-mount as described below. Use a different backing file as storage for each Elasticsearch replica.

This loopback must be maintained manually outside of OpenShift Origin, on the node. You must not maintain it from inside a container.

It is possible to use a local disk volume (if available) on each node host as storage for an Elasticsearch replica. Doing so requires some preparation as follows.

The relevant service account must be given the privilege to mount and edit a local volume:
$ oc adm policy add-scc-to-user privileged \ system:serviceaccount:logging:aggregated-logging-elasticsearch (1)
1 Use the project you created earlier (for example, logging) when running the logging playbook.

Each Elasticsearch replica definition must be patched to claim that privilege, for example:

$ for dc in $(oc get deploymentconfig --selector logging-infra=elasticsearch -o name); do
    oc scale $dc --replicas=0
    oc patch $dc \
       -p '{"spec":{"template":{"spec":{"containers":[{"name":"elasticsearch","securityContext":{"privileged": true}}]}}}}'
  done

The Elasticsearch replicas must be located on the correct nodes to use the local storage, and should not move around even if those nodes are taken down for a period of time. This requires giving each Elasticsearch replica a node selector that is unique to a node where an administrator has allocated storage for it. To configure a node selector, edit each Elasticsearch deployment configuration and add or edit the nodeSelector section to specify a unique label that you have applied for each desired node:
apiVersion: v1 kind: DeploymentConfig spec: template: spec: nodeSelector: logging-es-node: "1" (1)
1 This label should uniquely identify a replica with a single node that bears that label, in this case logging-es-node=1. Use the oc label command to apply labels to nodes as needed.

To automate applying the node selector you can instead use the oc patch command:
$ oc patch dc/logging-es-<suffix> \ -p '{"spec":{"template":{"spec":{"nodeSelector":{"logging-es-node":"1"}}}}}'

Once these steps are taken, a local host mount can be applied to each replica as in this example (where we assume storage is mounted at the same path on each node):

$ for dc in $(oc get deploymentconfig --selector logging-infra=elasticsearch -o name); do
    oc set volume $dc \
          --add --overwrite --name=elasticsearch-storage \
          --type=hostPath --path=/usr/local/es-storage
    oc rollout latest $dc
    oc scale $dc --replicas=1
  done

Changing the Scale of Elasticsearch

If you need to scale up the number of Elasticsearch instances your cluster uses, it is not as simple as scaling up an Elasticsearch deployment configuration. This is due to the nature of persistent volumes and how Elasticsearch is configured to store its data and recover the cluster. Instead, scaling up requires creating a deployment configuration for each Elasticsearch cluster node.

The simplest way to change the scale of Elasticsearch is to modify the inventory host file a re-run the logging playbook as desribed previously. Assuming you have supplied persistent storage for the deployment, this should not be disruptive.

If you do not wish to reinstall, for instance because you have made customizations that you would like to preserve, then it is possible to add new Elasticsearch deployment configurations to the cluster using a template supplied by the deployer. This requires a more complicated procedure however.

Allowing cluster-reader to view operations logs

By default, only cluster-admin users are granted access in Elasticsearch and Kibana to view operations logs. To allow cluster-reader users to also view these logs, update the value of openshift.operations.allow_cluster_reader in the Elasticsearch configmap to true:

$ oc edit configmap/logging-elasticsearch

Please note that changes to the configmap might not appear until after redeploying the pods. Persisting these changes across deployments can be accomplished by setting openshift_logging_es_allows_cluster_reader to true in the inventory file.

Expose Elasticsearch as a Route

By default, Elasticsearch deployed with OpenShift aggregated logging is not accessible from outside the logging cluster. You can enable a route for external access to Elasticsearch for those tools that want to access its data.

You have access to Elasticsearch using your OpenShift token, and you can provide the external Elasticsearch and Elasticsearch Ops hostnames when creating the server certificate (similar to Kibana).

To access Elasticsearch as a reencrypt route, define the following variables:

openshift_logging_es_allow_external=True
openshift_logging_es_hostname=elasticsearch.example.com

Run the openshift-logging.yml Ansible playbook:

$ ansible-playbook [-i </path/to/inventory>] \
    /usr/share/ansible/openshift-ansible/playbooks/byo/openshift-cluster/openshift-logging.yml

To log in to Elasticsearch remotely, the request must contain three HTTP headers:

Authorization: Bearer $token
X-Proxy-Remote-User: $username
X-Forwarded-For: $ip_address

You must have access to the project in order to be able to access to the logs. For example:
```
$ oc login <user1>
$ oc new-project <user1project>
$ oc new-app <httpd-example>
```
You need to get the token of this ServiceAccount to be used in the request:
```
$ token=$(oc whoami -t)
```

Using the token previously configured, you should be able access Elasticsearch through the exposed route:

$ curl -k -H "Authorization: Bearer $token" -H "X-Proxy-Remote-User: $(oc whoami)" -H "X-Forwarded-For: 127.0.0.1" https://es.example.test/_cat/indices

Fluentd

Fluentd is deployed as a DaemonSet that deploys replicas according to a node label selector, which you can specify with the inventory parameter openshift_logging_fluentd_nodeselector and the default is logging-infra-fluentd. As part of the OpenShift cluster installation, it is recommended that you add the Fluentd node selector to the list of persisted node labels.

Fluentd uses journald as the system log source. These are log messages from the operating system, Docker, and OpenShift. For container logs, Fluentd determines which log driver Docker is using, json-file or journald, and automatically reads the logs from that source.

As of OpenShift Origin 3.3, Fluentd no longer reads historical log files when using the JSON file log driver. In situations where clusters have a large number of log files and are older than the EFK deployment, this avoids delays when pushing the most recent logs into Elasticsearch. Curator deleting logs are migrated soon after they are added to Elasticsearch.

It may require several minutes, or hours, depending on the size of your journal, before any new log entries are available in Elasticsearch, when using openshift_logging_journal_read_from_head=true.

It is highly recommended that you use the default value for use-journal. In scenarios where upgrading OpenShift Origin changes the Docker log driver, if use-journal=False is explicitly specified as part of installation, Fluentd still expects to read logs generated using the json-file log driver. This results in a lack of log ingestion. If this has happened within your logging cluster, troubleshoot it.

Aggregated logging is only supported using the journald driver in Docker. See Updating Fluentd’s Log Source After a Docker Log Driver Update for more information.

Configuring Fluentd to Send Logs to an External Log Aggregator

You can configure Fluentd to send a copy of its logs to an external log aggregator, and not the default Elasticsearch, using the secure-forward plug-in. From there, you can further process log records after the locally hosted Fluentd has processed them.

The secure-forward plug-in is provided with the Fluentd image as of v1.4.0.

The logging deployment provides a secure-forward.conf section in the Fluentd configmap for configuring the external aggregator:

<store>
@type secure_forward
self_hostname pod-${HOSTNAME}
shared_key thisisasharedkey
secure yes
enable_strict_verification yes
ca_cert_path /etc/fluent/keys/your_ca_cert
ca_private_key_path /etc/fluent/keys/your_private_key
ca_private_key_passphrase passphrase
<server>
  host ose1.example.com
  port 24284
</server>
<server>
  host ose2.example.com
  port 24284
  standby
</server>
<server>
  host ose3.example.com
  port 24284
  standby
</server>
</store>

This can be updated using the oc edit command:

$ oc edit configmap/logging-fluentd

Certificates to be used in secure-forward.conf can be added to the existing secret that is mounted on the Fluentd pods. The your_ca_cert and your_private_key values must match what is specified in secure-forward.conf in configmap/logging-fluentd:

$ oc patch secrets/logging-fluentd --type=json \
  --patch "[{'op':'add','path':'/data/your_ca_cert','value':'$(base64 /path/to/your_ca_cert.pem)'}]"
$ oc patch secrets/logging-fluentd --type=json \
  --patch "[{'op':'add','path':'/data/your_private_key','value':'$(base64 /path/to/your_private_key.pem)'}]"

When configuring the external aggregator, it must be able to accept messages securely from Fluentd.

If the external aggregator is another Fluentd server, it must have the fluent-plugin-secure-forward plug-in installed and make use of the input plug-in it provides:

<source>
  @type secure_forward

  self_hostname ${HOSTNAME}
  bind 0.0.0.0
  port 24284

  shared_key thisisasharedkey

  secure yes
  cert_path        /path/for/certificate/cert.pem
  private_key_path /path/for/certificate/key.pem
  private_key_passphrase secret_foo_bar_baz
</source>

Further explanation of how to set up the fluent-plugin-secure-forward plug-in can be found here.

Reducing the Number of Connections from Fluentd to the API Server

With mux, you can deploy N number of mux services, where N is fewer than the number of nodes. Each Fluentd is configured with USE_MUX_CLIENT=1. This tells Fluentd to send the raw logs to mux with no filtering and no Kubernetes metadata filtering, which involves connections to the API server. You can perform all of the processing and Kubernetes metadata filtering with mux.

The mux is a Technology Preview feature only.

Parameter Description

Parameter	Description
`openshift_logging_use_mux`	The default is set to `False`. If set to `True`, a service called `mux` is deployed. This service acts as a Fluentd `secure_forward` aggregator for the node agent Fluentd daemonsets running in the cluster. Use `openshift_logging_use_mux` to reduce the number of connections to the OpenShift API server, and configure each node in Fluentd to send raw logs to `mux` and turn off the Kubernetes metadata plug-in.
`openshift_logging_mux_allow_external`	The default is set to `False`. If set to `True`, the `mux` service is deployed, and it is configured to allow Fluentd clients running outside of the cluster to send logs using `secure_forward`. This allows OpenShift logging to be used as a central logging service for clients other than OpenShift, or other OpenShift clusters.
`openshift_logging_use_mux_client`	The default is set to `False`. If set to `True`, the node agent Fluentd services is configured to send logs to the `mux` service rather than directly to Elasticsearch, and their Kubernetes metadata filters is disabled, reducing the number of connections to the API server.
`openshift_logging_mux_hostname`	The default is `mux` plus `openshift_master_default_subdomain`. This is the hostname `external_clients` will use to connect to `mux`, and is used in the TLS server cert subject.
`openshift_logging_mux_port`	24284
`openshift_logging_mux_cpu_limit`	500M
`openshift_logging_mux_memory_limit`	1Gi
`openshift_logging_mux_default_namespaces`	The default is `mux-undefined`. The first value in the list is the namespace to use for undefined projects, followed by any additional namespaces to create by default. Usually, you do not need to set this value.
`openshift_logging_mux_namespaces`	The default value is empty, allowing for additional namespaces to create for external `mux` clients to associate with their logs. You will need to set this value.

openshift_logging_use_mux

The default is set to False. If set to True, a service called mux is deployed. This service acts as a Fluentd secure_forward aggregator for the node agent Fluentd daemonsets running in the cluster. Use openshift_logging_use_mux to reduce the number of connections to the OpenShift API server, and configure each node in Fluentd to send raw logs to mux and turn off the Kubernetes metadata plug-in.

openshift_logging_mux_allow_external

The default is set to False. If set to True, the mux service is deployed, and it is configured to allow Fluentd clients running outside of the cluster to send logs using secure_forward. This allows OpenShift logging to be used as a central logging service for clients other than OpenShift, or other OpenShift clusters.

openshift_logging_use_mux_client

The default is set to False. If set to True, the node agent Fluentd services is configured to send logs to the mux service rather than directly to Elasticsearch, and their Kubernetes metadata filters is disabled, reducing the number of connections to the API server.

openshift_logging_mux_hostname

The default is mux plus openshift_master_default_subdomain. This is the hostname external_clients will use to connect to mux, and is used in the TLS server cert subject.

openshift_logging_mux_port

24284

openshift_logging_mux_cpu_limit

500M

openshift_logging_mux_memory_limit

1Gi

openshift_logging_mux_default_namespaces

The default is mux-undefined. The first value in the list is the namespace to use for undefined projects, followed by any additional namespaces to create by default. Usually, you do not need to set this value.

openshift_logging_mux_namespaces

The default value is empty, allowing for additional namespaces to create for external mux clients to associate with their logs. You will need to set this value.

Throttling logs in Fluentd

For projects that are especially verbose, an administrator can throttle down the rate at which the logs are read in by Fluentd before being processed.

Throttling can contribute to log aggregation falling behind for the configured projects; log entries can be lost if a pod is deleted before Fluentd catches up.

Throttling does not work when using the systemd journal as the log source. The throttling implementation depends on being able to throttle the reading of the individual log files for each project. When reading from the journal, there is only a single log source, no log files, so no file-based throttling is available. There is not a method of restricting the log entries that are read into the Fluentd process.

To tell Fluentd which projects it should be restricting, edit the throttle configuration in its ConfigMap after deployment:

$ oc edit configmap/logging-fluentd

The format of the throttle-config.yaml key is a YAML file that contains project names and the desired rate at which logs are read in on each node. The default is 1000 lines at a time per node. For example:

logging:
  read_lines_limit: 500

test-project:
  read_lines_limit: 10

.operations:
  read_lines_limit: 100

Kibana

To access the Kibana console from the OpenShift Origin web console, add the loggingPublicURL parameter in the /etc/origin/master/master-config.yaml file, with the URL of the Kibana console (the kibana-hostname parameter). The value must be an HTTPS URL:

...
assetConfig:
  ...
  loggingPublicURL: "https://kibana.example.com"
...

Setting the loggingPublicURL parameter creates a View Archive button on the OpenShift Origin web console under the Browse → Pods → <pod_name> → Logs tab. This links to the Kibana console.

You can scale the Kibana deployment as usual for redundancy:

$ oc scale dc/logging-kibana --replicas=2

To ensure the scale persists across multiple executions of the logging playbook, make sure to update the openshift_logging_kibana_replica_count in the inventory file.

You can see the user interface by visiting the site specified by the openshift_logging_kibana_hostname variable.

See the Kibana documentation for more information on Kibana.

Kibana Visualize

Kibana Visualize enables you to create visualizations and dashboards for monitoring container and pod logs allows administrator users (cluster-admin or cluster-reader) to view logs by deployment, namespace, pod, and container.

Kibana Visualize exists inside the Elasticsearch and ES-OPS pod, and must be run inside those pods. To load dashboards and other Kibana UI objects, you must first log into Kibana as the user you want to add the dashboards to, then log out. This will create the necessary per-user configuration that the next step relies on. Then, run:

$ oc exec <$espod> -- es_load_kibana_ui_objects <user-name>

Where $espod is the name of any one of your Elasticsearch pods.

Curator

Curator allows administrators to configure scheduled Elasticsearch maintenance operations to be performed automatically on a per-project basis. It is scheduled to perform actions daily based on its configuration. Only one Curator pod is recommended per Elasticsearch cluster. Curator is configured via a YAML configuration file with the following structure:

$PROJECT_NAME:
  $ACTION:
    $UNIT: $VALUE

$PROJECT_NAME:
  $ACTION:
    $UNIT: $VALUE
 ...

The available parameters are:

Variable Name Description

Variable Name	Description
`$PROJECT_NAME`	The actual name of a project, such as myapp-devel. For OpenShift Origin operations logs, use the name `.operations` as the project name.
`$ACTION`	The action to take, currently only `delete` is allowed.
`$UNIT`	One of `days`, `weeks`, or `months`.
`$VALUE`	An integer for the number of units.
`.defaults`	Use `.defaults` as the `$PROJECT_NAME` to set the defaults for projects that are not specified.
`runhour`	(Number) the hour of the day in 24-hour format at which to run the Curator jobs. For use with `.defaults`.
`runminute`	(Number) the minute of the hour at which to run the Curator jobs. For use with `.defaults`.

$PROJECT_NAME

The actual name of a project, such as myapp-devel. For OpenShift Origin operations logs, use the name .operations as the project name.

$ACTION

The action to take, currently only delete is allowed.

$UNIT

One of days, weeks, or months.

$VALUE

An integer for the number of units.

.defaults

Use .defaults as the $PROJECT_NAME to set the defaults for projects that are not specified.

runhour

(Number) the hour of the day in 24-hour format at which to run the Curator jobs. For use with .defaults.

runminute

(Number) the minute of the hour at which to run the Curator jobs. For use with .defaults.

For example, to configure Curator to:

delete indices in the myapp-dev project older than 1 day
delete indices in the myapp-qe project older than 1 week
delete operations logs older than 8 weeks
delete all other projects indices after they are 30 days old
run the Curator jobs at midnight every day

Use:

myapp-dev:
 delete:
   days: 1

myapp-qe:
  delete:
    weeks: 1

.operations:
  delete:
    weeks: 8

.defaults:
  delete:
    days: 30
  runhour: 0
  runminute: 0

When you use month as the $UNIT for an operation, Curator starts counting at the first day of the current month, not the current day of the current month. For example, if today is April 15, and you want to delete indices that are 2 months older than today (delete: months: 2), Curator does not delete indices that are dated older than February 15; it deletes indices older than February 1. That is, it goes back to the first day of the current month, then goes back two whole months from that date. If you want to be exact with Curator, it is best to use days (for example, delete: days: 30).

Creating the Curator Configuration

The openshift_logging Ansible role provides a ConfigMap from which Curator reads its configuration. You may edit or replace this ConfigMap to reconfigure Curator. Currently the logging-curator ConfigMap is used to configure both your ops and non-ops Curator instances. Any .operations configurations are in the same location as your application logs configurations.

To edit the provided ConfigMap to configure your Curator instances:
```
$ oc edit configmap/logging-curator
```

To replace the provided ConfigMap instead:

$ create /path/to/mycuratorconfig.yaml
$ oc create configmap logging-curator -o yaml \
  --from-file=config.yaml=/path/to/mycuratorconfig.yaml | \
  oc replace -f -

After you make your changes, redeploy Curator:

$ oc rollout latest dc/logging-curator
$ oc rollout latest dc/logging-curator-ops

Cleanup

Remove everything generated during the deployment.

$ ansible-playbook playbooks/openshift-logging/config.yml \
    -e openshift_logging_install_logging=False

Troubleshooting Kibana

Using the Kibana console with OpenShift Origin can cause problems that are easily solved, but are not accompanied with useful error messages. Check the following troubleshooting sections if you are experiencing any problems when deploying Kibana on OpenShift Origin:

Login Loop

The OAuth2 proxy on the Kibana console must share a secret with the master host’s OAuth2 server. If the secret is not identical on both servers, it can cause a login loop where you are continuously redirected back to the Kibana login page.

To fix this issue, delete the current OAuthClient, and use openshift-ansible to re-run the openshift_logging role:

$ oc delete oauthclient/kibana-proxy
$ ansible-playbook [-i </path/to/inventory>] \
    /usr/share/ansible/openshift-ansible/playbooks/openshift-logging/config.yml

Cryptic Error When Viewing the Console

When attempting to visit the Kibana console, you may receive a browser error instead:

{"error":"invalid_request","error_description":"The request is missing a required parameter,
 includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed."}

This can be caused by a mismatch between the OAuth2 client and server. The return address for the client must be in a whitelist so the server can securely redirect back after logging in.

Fix this issue by replacing the OAuthClient entry:

$ oc delete oauthclient/kibana-proxy
$ ansible-playbook [-i </path/to/inventory>] \
    /usr/share/ansible/openshift-ansible/playbooks/openshift-logging/config.yml

If the problem persists, check that you are accessing Kibana at a URL listed in the OAuth client. This issue can be caused by accessing the URL at a forwarded port, such as 1443 instead of the standard 443 HTTPS port. You can adjust the server whitelist by editing the OAuth client:

$ oc edit oauthclient/kibana-proxy

503 Error When Viewing the Console

If you receive a proxy error when viewing the Kibana console, it could be caused by one of two issues.

First, Kibana may not be recognizing pods. If Elasticsearch is slow in starting up, Kibana may timeout trying to reach it. Check whether the relevant service has any endpoints:

$ oc describe service logging-kibana
Name:                   logging-kibana
[...]
Endpoints:              <none>

If any Kibana pods are live, endpoints are listed. If they are not, check the state of the Kibana pods and deployment. You may need to scale the deployment down and back up again.

The second possible issue may be caused if the route for accessing the Kibana service is masked. This can happen if you perform a test deployment in one project, then deploy in a different project without completely removing the first deployment. When multiple routes are sent to the same destination, the default router will only route to the first created. Check the problematic route to see if it is defined in multiple places:

$ oc get route  --all-namespaces --selector logging-infra=support

F-5 Load Balancer and X-Forwarded-For Enabled

If you are attempting to use a F-5 load balancer in front of Kibana with X-Forwarded-For enabled, this can cause an issue in which the Elasticsearch Searchguard plug-in is unable to correctly accept connections from Kibana.

Example Kibana Error Message

Kibana: Unknown error while connecting to Elasticsearch

Error: Unknown error while connecting to Elasticsearch
Error: UnknownHostException[No trusted proxies]

To configure Searchguard to ignore the extra header:

Scale down all Fluentd pods.
Scale down Elasticsearch after the Fluentd pods have terminated.
Add searchguard.http.xforwardedfor.header: DUMMY to the Elasticsearch configuration section.
```
$ oc edit configmap/logging-elasticsearch (1)
```
1 This approach requires that Elasticsearch’s configurations are within a ConfigMap.
Scale Elasticsearch back up.
Scale up all Fluentd pods.

Sending Logs to an External Elasticsearch Instance

Fluentd sends logs to the value of the ES_HOST, ES_PORT, OPS_HOST, and OPS_PORT environment variables of the Elasticsearch deployment configuration. The application logs are directed to the ES_HOST destination, and operations logs to OPS_HOST.

Sending logs directly to an AWS Elasticsearch instance is not supported. Use Fluentd Secure Forward to direct logs to an instance of Fluentd that you control and that is configured with the fluent-plugin-aws-elasticsearch-service plug-in.

To direct logs to a specific Elasticsearch instance, edit the deployment configuration and replace the value of the above variables with the desired instance:

$ oc edit dc/<deployment_configuration>

For an external Elasticsearch instance to contain both application and operations logs, you can set ES_HOST and OPS_HOST to the same destination, while ensuring that ES_PORT and OPS_PORT also have the same value.

If your externally hosted Elasticsearch instance does not use TLS, update the _CLIENT_CERT, _CLIENT_KEY, and _CA variables to be empty. If it does use TLS, but not mutual TLS, update the _CLIENT_CERT and _CLIENT_KEY variables to be empty and patch or recreate the logging-fluentd secret with the appropriate _CA value for communicating with your Elasticsearch instance. If it uses Mutual TLS as the provided Elasticsearch instance does, patch or recreate the logging-fluentd secret with your client key, client cert, and CA.

If you are not using the provided Kibana and Elasticsearch images, you will not have the same multi-tenant capabilities and your data will not be restricted by user access to a particular project.

Sending Logs to an External Syslog Server

Use the fluent-plugin-remote-syslog plug-in on the host to send logs to an external syslog server.

Set environment variables in the logging-fluentd or logging-mux deployment configurations:

- name: REMOTE_SYSLOG_HOST (1)
  value: host1
- name: REMOTE_SYSLOG_HOST_BACKUP
  value: host2
- name: REMOTE_SYSLOG_PORT_BACKUP
  value: 5555

1	The desired remote syslog host. Required for each host.

This will build two destinations. The syslog server on host1 will be receiving messages on the default port of 514, while host2 will be receiving the same messages on port 5555.

Alternatively, you can configure your own custom fluent.conf in the logging-fluentd or logging-mux ConfigMaps.

Fluentd Environment Variables

Parameter Description

Parameter	Description
`USE_REMOTE_SYSLOG`	Defaults to `false`. Set to `true` to enable use of the `fluent-plugin-remote-syslog` gem
`REMOTE_SYSLOG_HOST`	(Required) Hostname or IP address of the remote syslog server.
`REMOTE_SYSLOG_PORT`	Port number to connect on. Defaults to `514`.
`REMOTE_SYSLOG_SEVERITY`	Set the syslog severity level. Defaults to `debug`.
`REMOTE_SYSLOG_FACILITY`	Set the syslog facility. Defaults to `local0`.
`REMOTE_SYSLOG_USE_RECORD`	Defaults to `false`. Set to `true` to use the record’s severity and facility fields to set on the syslog message.
`REMOTE_SYSLOG_REMOVE_TAG_PREFIX`	Removes the prefix from the tag, defaults to `''` (empty).
`REMOTE_SYSLOG_TAG_KEY`	If specified, uses this field as the key to look on the record, to set the tag on the syslog message.
`REMOTE_SYSLOG_PAYLOAD_KEY`	If specified, uses this field as the key to look on the record, to set the payload on the syslog message.

USE_REMOTE_SYSLOG

Defaults to false. Set to true to enable use of the fluent-plugin-remote-syslog gem

REMOTE_SYSLOG_HOST

(Required) Hostname or IP address of the remote syslog server.

REMOTE_SYSLOG_PORT

Port number to connect on. Defaults to 514.

REMOTE_SYSLOG_SEVERITY

Set the syslog severity level. Defaults to debug.

REMOTE_SYSLOG_FACILITY

Set the syslog facility. Defaults to local0.

REMOTE_SYSLOG_USE_RECORD

Defaults to false. Set to true to use the record’s severity and facility fields to set on the syslog message.

REMOTE_SYSLOG_REMOVE_TAG_PREFIX

Removes the prefix from the tag, defaults to '' (empty).

REMOTE_SYSLOG_TAG_KEY

If specified, uses this field as the key to look on the record, to set the tag on the syslog message.

REMOTE_SYSLOG_PAYLOAD_KEY

If specified, uses this field as the key to look on the record, to set the payload on the syslog message.

This implementation is insecure, and should only be used in environments where you can guarantee no snooping on the connection.

Fluentd Logging Ansible Variables

Parameter Description

Parameter	Description
`openshift_logging_fluentd_remote_syslog`	The default is set to `false`. Set to `true` to enable use of the fluent-plugin-remote-syslog gem.
`openshift_logging_fluentd_remote_syslog_host`	Hostname or IP address of the remote syslog server, this is mandatory.
`openshift_logging_fluentd_remote_syslog_port`	Port number to connect on, defaults to `514`.
`openshift_logging_fluentd_remote_syslog_severity`	Set the syslog severity level, defaults to `debug`.
`openshift_logging_fluentd_remote_syslog_facility`	Set the syslog facility, defaults to `local0`.
`openshift_logging_fluentd_remote_syslog_use_record`	The default is set to `false`. Set to `true` to use the record’s severity and facility fields to set on the syslog message.
`openshift_logging_fluentd_remote_syslog_remove_tag_prefix`	Removes the prefix from the tag, defaults to `''` (empty).
`openshift_logging_fluentd_remote_syslog_tag_key`	If string is specified, uses this field as the key to look on the record, to set the tag on the syslog message.
`openshift_logging_fluentd_remote_syslog_payload_key`	If string is specified, uses this field as the key to look on the record, to set the payload on the syslog message.

openshift_logging_fluentd_remote_syslog

The default is set to false. Set to true to enable use of the fluent-plugin-remote-syslog gem.

openshift_logging_fluentd_remote_syslog_host

Hostname or IP address of the remote syslog server, this is mandatory.

openshift_logging_fluentd_remote_syslog_port

Port number to connect on, defaults to 514.

openshift_logging_fluentd_remote_syslog_severity

Set the syslog severity level, defaults to debug.

openshift_logging_fluentd_remote_syslog_facility

Set the syslog facility, defaults to local0.

openshift_logging_fluentd_remote_syslog_use_record

The default is set to false. Set to true to use the record’s severity and facility fields to set on the syslog message.

openshift_logging_fluentd_remote_syslog_remove_tag_prefix

Removes the prefix from the tag, defaults to '' (empty).

openshift_logging_fluentd_remote_syslog_tag_key

If string is specified, uses this field as the key to look on the record, to set the tag on the syslog message.

openshift_logging_fluentd_remote_syslog_payload_key

If string is specified, uses this field as the key to look on the record, to set the payload on the syslog message.

Mux Logging Ansible Variables

Parameter Description

Parameter	Description
`openshift_logging_mux_remote_syslog`	The default is set to `false`. Set to `true` to enable use of the fluent-plugin-remote-syslog gem.
`openshift_logging_mux_remote_syslog_host`	Hostname or IP address of the remote syslog server, this is mandatory.
`openshift_logging_mux_remote_syslog_port`	Port number to connect on, defaults to `514`.
`openshift_logging_mux_remote_syslog_severity`	Set the syslog severity level, defaults to `debug`.
`openshift_logging_mux_remote_syslog_facility`	Set the syslog facility, defaults to `local0`.
`openshift_logging_mux_remote_syslog_use_record`	The default is set to `false`. Set to `true` to use the record’s severity and facility fields to set on the syslog message.
`openshift_logging_mux_remote_syslog_remove_tag_prefix`	Removes the prefix from the tag, defaults to `''` (empty).
`openshift_logging_mux_remote_syslog_tag_key`	If string is specified, uses this field as the key to look on the record, to set the tag on the syslog message.
`openshift_logging_mux_remote_syslog_payload_key`	If string is specified, uses this field as the key to look on the record, to set the payload on the syslog message.

openshift_logging_mux_remote_syslog

The default is set to false. Set to true to enable use of the fluent-plugin-remote-syslog gem.

openshift_logging_mux_remote_syslog_host

Hostname or IP address of the remote syslog server, this is mandatory.

openshift_logging_mux_remote_syslog_port

Port number to connect on, defaults to 514.

openshift_logging_mux_remote_syslog_severity

Set the syslog severity level, defaults to debug.

openshift_logging_mux_remote_syslog_facility

Set the syslog facility, defaults to local0.

openshift_logging_mux_remote_syslog_use_record

The default is set to false. Set to true to use the record’s severity and facility fields to set on the syslog message.

openshift_logging_mux_remote_syslog_remove_tag_prefix

Removes the prefix from the tag, defaults to '' (empty).

openshift_logging_mux_remote_syslog_tag_key

If string is specified, uses this field as the key to look on the record, to set the tag on the syslog message.

openshift_logging_mux_remote_syslog_payload_key

If string is specified, uses this field as the key to look on the record, to set the payload on the syslog message.

Performing Administrative Elasticsearch Operations

As of logging version 1.2.0, an administrator certificate, key, and CA that can be used to communicate with and perform administrative operations on Elasticsearch are provided within the logging-elasticsearch secret.

To confirm whether or not your EFK installation provides these, run:

$ oc describe secret logging-elasticsearch

If they are not available, refer to Manual Upgrades to ensure you are on the latest version first.

Connect to an Elasticsearch pod that is in the cluster on which you are attempting to perform maintenance.

To find a pod in a cluster use either:

$ oc get pods -l component=es -o name | head -1
$ oc get pods -l component=es-ops -o name | head -1

Connect to a pod:
$ oc rsh <your_Elasticsearch_pod>
Once connected to an Elasticsearch container, you can use the certificates mounted from the secret to communicate with Elasticsearch per its Indices APIs documentation.

Fluentd sends its logs to Elasticsearch using the index format project.{project_name}.{project_uuid}.YYYY.MM.DD where YYYY.MM.DD is the date of the log record.

For example, to delete all logs for the logging project with uuid 3b3594fa-2ccd-11e6-acb7-0eb6b35eaee3 from June 15, 2016, we can run:
$ curl --key /etc/elasticsearch/secret/admin-key \ --cert /etc/elasticsearch/secret/admin-cert \ --cacert /etc/elasticsearch/secret/admin-ca -XDELETE \ "https://localhost:9200/project.logging.3b3594fa-2ccd-11e6-acb7-0eb6b35eaee3.2016.06.15"

Changing the Aggregated Logging Driver

By default, aggregated logging uses the journald log driver unless json-file was specified during installation. You can change the log driver between journald and json-file as needed.

When using the json-file driver, ensure that your Docker version is Docker version docker-1.12.6-55.gitc4618fb.el7_4 now or later.

Fluentd determines the driver Docker is using by checking the /etc/docker/daemon.json and /etc/sysconfig/docker files.

You can determine which driver Docker is using with the docker info command:

# docker info | grep Logging

Logging Driver: journald

To change between json-file and journald after installation:

Modify either the /etc/sysconfig/docker or /etc/docker/daemon.json files.

For example:

# cat /etc/sysconfig/docker
OPTIONS=' --selinux-enabled --log-driver=json-file --log-opt max-size=1M --log-opt max-file=3 --signature-verification=False'

cat /etc/docker/daemon.json
{
"log-driver": "json-file",
"log-opts": {
"max-size": "1M",
"max-file": "1"
}
}

Restart the Docker service:
```
systemctl restart docker
```
Update the Fluentd log source.

Updating Fluentd’s Log Source After a Docker Log Driver Update

If the Docker log driver has changed from json-file to journald and Fluentd was previously configured with USE_JOURNAL=False, then it will not be able to pick up any new logs that are created. When the Fluentd daemonset is configured with the default value for USE_JOURNAL, then it will detect the Docker log driver upon pod start-up, and configure itself to pull from the appropriate source.

To update Fluentd to detect the correct source upon start-up:

Remove the label from nodes where Fluentd is deployed:
```
$ oc label node --all logging-infra-fluentd- (1)
```
1 This example assumes use of the default Fluentd node selector and it being deployed on all nodes.

Update the daemonset/logging-fluentd USE_JOURNAL value to be empty:

$ oc patch daemonset/logging-fluentd \
     -p '{"spec":{"template":{"spec":{"containers":[{"name":"fluentd-elasticsearch","env":[{"name": "USE_JOURNAL", "value":""}]}]}}}}'

Relabel your nodes to schedule Fluentd deployments:
```
$ oc label node --all logging-infra-fluentd=true (1)
```
1 This example assumes use of the default Fluentd node selector and it being deployed on all nodes.

Exported Fields

These are the fields exported by the logging system and available for searching from Elasticsearch and Kibana. Use the full, dotted field name when searching. For example, for an Elasticsearch /_search URL, to look for a Kubernetes pod name, use /_search/q=kubernetes.pod_name:name-of-my-pod. The following sections describe fields that may not be present in your logging store. Not all of these fields are present in every record. The fields are grouped in the following categories:

exported-fields-Default
exported-fields-rsyslog
exported-fields-systemd
exported-fields-kubernetes
exported-fields-docker
exported-fields-pipeline_metadata
exported-fields-ovirt
exported-fields-aushape
exported-fields-tlog

Top Level Fields

The top level fields are common to every application, and may be present in every record. For the Elasticsearch template, top level fields populate the actual mappings of default in the template’s mapping section.

Parameter Description

Parameter	Description
`@timestamp`	The UTC value marking when the log payload was created, or when the log payload was first collected if the creation time is not known. This is the log processing pipeline’s best effort determination of when the log payload was generated. Add the `@` prefix convention to note a field as being reserved for a particular use. With Elasticsearch, most tools look for `@timestamp` by default. For example, the format would be 2015-01-24 14:06:05.071000.
`geoip`	This is geo-ip of the machine.
`hostname`	The `hostname` is the fully qualified domain name (FQDN) of the entity generating the original payload. This field is an attempt to derive this context. Sometimes the entity generating it knows the context. While other times that entity has a restricted namespace itself, which is known by the collector or normalizer.
`ipaddr4`	The IP address V4 of the source server, which can be an array.
`ipaddr6`	The IP address V6 of the source server, if available.
`level`	The logging level as provided by `rsyslog` (severitytext property), python’s logging module. Possible values are as listed at `misc/sys/syslog.h` plus `trace` and `unknown`. For example, "alert crit debug emerg err info notice trace unknown warning". Note that `trace` is not in the `syslog.h` list but many applications use it. . You should only use `unknown` when the logging system gets a value it does not understand, and note that it is the highest level. . Consider `trace` as higher or more verbose, than `debug`. . `error` is deprecated, use `err`. . Convert `panic` to `emerg`. . Convert `warn` to `warning`. Numeric values from `syslog/journal PRIORITY` can usually be mapped using the priority values as listed at misc/sys/syslog.h. Log levels and priorities from other logging systems should be mapped to the nearest match. See python logging for an example.
`message`	A typical log entry message, or payload. It can be stripped of metadata pulled out of it by the collector or normalizer, that is UTF-8 encoded.
`pid`	This is the process ID of the logging entity, if available.
`service`	The name of the service associated with the logging entity, if available. For example, the `syslog APP-NAME` and `rsyslog programname` property are mapped to the service field.
`tags`	Optionally provided operator defined list of tags placed on each log by the collector or normalizer. The payload can be a string with whitespace-delimited string tokens, or a JSON list of string tokens.
`file`	Optional path to the file containing the log entry local to the collector `TODO` analyzer for file paths.
`offset`	The offset value can represent bytes to the start of the log line in the file (zero or one based), or log line numbers (zero or one based), as long as the values are strictly monotonically increasing in the context of a single log file. The values are allowed to wrap, representing a new version of the log file (rotation).
`namespace_name`	Associate this record with the `namespace` that shares it’s name. This value will not be stored, but it is used to associate the record with the appropriate `namespace` for access control and visualization. Normally this value will be given in the tag, but if the protocol does not support sending a tag, this field can be used. If this field is present, it will override the `namespace` given in the tag or in `kubernetes.namespace_name`.
`namespace_uuid`	This is the `uuid` associated with the `namespace_name`. This value will not be stored, but is used to associate the record with the appropriate namespace for access control and visualization. If this field is present, it will override the `uuid` given in `kubernetes.namespace_uuid`. This will also cause the Kubernetes metadata lookup to be skipped for this log record.

@timestamp

The UTC value marking when the log payload was created, or when the log payload was first collected if the creation time is not known. This is the log processing pipeline’s best effort determination of when the log payload was generated. Add the @ prefix convention to note a field as being reserved for a particular use. With Elasticsearch, most tools look for @timestamp by default. For example, the format would be 2015-01-24 14:06:05.071000.

geoip

This is geo-ip of the machine.

hostname

The hostname is the fully qualified domain name (FQDN) of the entity generating the original payload. This field is an attempt to derive this context. Sometimes the entity generating it knows the context. While other times that entity has a restricted namespace itself, which is known by the collector or normalizer.

ipaddr4

The IP address V4 of the source server, which can be an array.

ipaddr6

The IP address V6 of the source server, if available.

level

The logging level as provided by rsyslog (severitytext property), python’s logging module. Possible values are as listed at misc/sys/syslog.h plus trace and unknown. For example, "alert crit debug emerg err info notice trace unknown warning". Note that trace is not in the syslog.h list but many applications use it.

. You should only use unknown when the logging system gets a value it does not understand, and note that it is the highest level. . Consider trace as higher or more verbose, than debug. . error is deprecated, use err. . Convert panic to emerg. . Convert warn to warning.

Numeric values from syslog/journal PRIORITY can usually be mapped using the priority values as listed at misc/sys/syslog.h.

Log levels and priorities from other logging systems should be mapped to the nearest match. See python logging for an example.

message

A typical log entry message, or payload. It can be stripped of metadata pulled out of it by the collector or normalizer, that is UTF-8 encoded.

pid

This is the process ID of the logging entity, if available.

service

The name of the service associated with the logging entity, if available. For example, the syslog APP-NAME and rsyslog programname property are mapped to the service field.

tags

Optionally provided operator defined list of tags placed on each log by the collector or normalizer. The payload can be a string with whitespace-delimited string tokens, or a JSON list of string tokens.

file

Optional path to the file containing the log entry local to the collector TODO analyzer for file paths.

offset

The offset value can represent bytes to the start of the log line in the file (zero or one based), or log line numbers (zero or one based), as long as the values are strictly monotonically increasing in the context of a single log file. The values are allowed to wrap, representing a new version of the log file (rotation).

namespace_name

Associate this record with the namespace that shares it’s name. This value will not be stored, but it is used to associate the record with the appropriate namespace for access control and visualization. Normally this value will be given in the tag, but if the protocol does not support sending a tag, this field can be used. If this field is present, it will override the namespace given in the tag or in kubernetes.namespace_name.

namespace_uuid

This is the uuid associated with the namespace_name. This value will not be stored, but is used to associate the record with the appropriate namespace for access control and visualization. If this field is present, it will override the uuid given in kubernetes.namespace_uuid. This will also cause the Kubernetes metadata lookup to be skipped for this log record.

`collectd` Fields

The following fields represent namespace metrics metadata.

Parameter Description

Parameter	Description
`collectd.interval`	type: float The `collectd` interval.
`collectd.plugin`	type: string The `collectd` plug-in.
`collectd.plugin_instance`	type: string The `collectd` plugin_instance.
`collectd.type_instance`	type: string The `collectd` `type_instance`.
`collectd.type`	type: string The `collectd` type.
`collectd.dstypes`	type: string The `collectd` dstypes.

collectd.interval

type: float

The collectd interval.

collectd.plugin

type: string

The collectd plug-in.

collectd.plugin_instance

type: string

The collectd plugin_instance.

collectd.type_instance

type: string

The collectd type_instance.

collectd.type

type: string

The collectd type.

collectd.dstypes

type: string

The collectd dstypes.

`collectd.processes` Fields

The following field corresponds to the collectd processes plug-in.

Parameter Description

Parameter	Description
`collectd.processes.ps_state`	type: integer The `collectd ps_state` type of processes plug-in.

collectd.processes.ps_state

type: integer The collectd ps_state type of processes plug-in.

`collectd.processes.ps_disk_ops` Fields

The collectd ps_disk_ops type of processes plug-in.

Parameter Description

Parameter	Description
`collectd.processes.ps_disk_ops.read`	type: float `TODO`
`collectd.processes.ps_disk_ops.write`	type: float `TODO`
`collectd.processes.ps_vm`	type: integer The `collectd` `ps_vm` type of processes plug-in.
`collectd.processes.ps_rss`	type: integer The `collectd` `ps_rss` type of processes plug-in.
`collectd.processes.ps_data`	type: integer The `collectd` `ps_data` type of processes plug-in.
`collectd.processes.ps_code`	type: integer The `collectd` `ps_code` type of processes plug-in.
`collectd.processes.ps_stacksize`	type: integer The `collectd` `ps_stacksize` type of processes plug-in.

collectd.processes.ps_disk_ops.read

type: float

TODO

collectd.processes.ps_disk_ops.write

type: float

TODO

collectd.processes.ps_vm

type: integer

The collectd ps_vm type of processes plug-in.

collectd.processes.ps_rss

type: integer

The collectd ps_rss type of processes plug-in.

collectd.processes.ps_data

type: integer

The collectd ps_data type of processes plug-in.

collectd.processes.ps_code

type: integer

The collectd ps_code type of processes plug-in.

collectd.processes.ps_stacksize

type: integer

The collectd ps_stacksize type of processes plug-in.

`collectd.processes.ps_cputime` Fields

The collectd ps_cputime type of processes plug-in.

Parameter Description

Parameter	Description
`collectd.processes.ps_cputime.user`	type: float `TODO`
`collectd.processes.ps_cputime.syst`	type: float `TODO`

collectd.processes.ps_cputime.user

type: float

TODO

collectd.processes.ps_cputime.syst

type: float

TODO

`collectd.processes.ps_count` Fields

The collectd ps_count type of processes plug-in.

Parameter Description

Parameter	Description
`collectd.processes.ps_count.processes`	type: integer `TODO`
`collectd.processes.ps_count.threads`	type: integer `TODO`

collectd.processes.ps_count.processes

type: integer

TODO

collectd.processes.ps_count.threads

type: integer

TODO

`collectd.processes.ps_pagefaults` Fields

The collectd ps_pagefaults type of processes plug-in.

Parameter Description

Parameter	Description
`collectd.processes.ps_pagefaults.majflt`	type: float `TODO`
`collectd.processes.ps_pagefaults.minflt`	type: float `TODO`

collectd.processes.ps_pagefaults.majflt

type: float

TODO

collectd.processes.ps_pagefaults.minflt

type: float

TODO

`collectd.processes.ps_disk_octets` Fields

The collectd ps_disk_octets type of processes plug-in.

Parameter Description

Parameter	Description
`collectd.processes.ps_disk_octets.read`	type: float `TODO`
`collectd.processes.ps_disk_octets.write`	type: float `TODO`
`collectd.processes.fork_rate`	type: float The `collectd` `fork_rate` type of processes plug-in.

collectd.processes.ps_disk_octets.read

type: float

TODO

collectd.processes.ps_disk_octets.write

type: float

TODO

collectd.processes.fork_rate

type: float

The collectd fork_rate type of processes plug-in.

`collectd.disk` Fields

Corresponds to collectd disk plug-in.

`collectd.disk.disk_merged` Fields

The collectd disk_merged type of disk plug-in.

Parameter Description

Parameter	Description
`collectd.disk.disk_merged.read`	type: float `TODO`
`collectd.disk.disk_merged.write`	type: float `TODO`

collectd.disk.disk_merged.read

type: float

TODO

collectd.disk.disk_merged.write

type: float

TODO

`collectd.disk.disk_octets` Fields

The collectd disk_octets type of disk plug-in.

Parameter Description

Parameter	Description
`collectd.disk.disk_octets.read`	type: float `TODO`
`collectd.disk.disk_octets.write`	type: float `TODO`

collectd.disk.disk_octets.read

type: float

TODO

collectd.disk.disk_octets.write

type: float

TODO

`collectd.disk.disk_time` Fields

The collectd disk_time type of disk plug-in.

Parameter Description

Parameter	Description
`collectd.disk.disk_time.read`	type: float `TODO`
`collectd.disk.disk_time.write`	type: float `TODO`

collectd.disk.disk_time.read

type: float

TODO

collectd.disk.disk_time.write

type: float

TODO

`collectd.disk.disk_ops` Fields

The collectd disk_ops type of disk plug-in.

Parameter Description

Parameter	Description
`collectd.disk.disk_ops.read`	type: float `TODO`
`collectd.disk.disk_ops.write`	type: float `TODO`
`collectd.disk.pending_operations`	type: integer The `collectd` `pending_operations` type of disk plug-in.

collectd.disk.disk_ops.read

type: float

TODO

collectd.disk.disk_ops.write

type: float

TODO

collectd.disk.pending_operations

type: integer

The collectd pending_operations type of disk plug-in.

`collectd.disk.disk_io_time` Fields

The collectd disk_io_time type of disk plug-in.

Parameter Description

Parameter	Description
`collectd.disk.disk_io_time.io_time`	type: float `TODO`
`collectd.disk.disk_io_time.weighted_io_time`	type: float `TODO`

collectd.disk.disk_io_time.io_time

type: float

TODO

collectd.disk.disk_io_time.weighted_io_time

type: float

TODO

`collectd.interface` Fields

Corresponds to the collectd interface plug-in.

`collectd.interface.if_octets` Fields

The collectd if_octets type of interface plug-in.

Parameter Description

Parameter	Description
`collectd.interface.if_octets.rx`	type: float `TODO`
`collectd.interface.if_octets.tx`	type: float `TODO`

collectd.interface.if_octets.rx

type: float

TODO

collectd.interface.if_octets.tx

type: float

TODO

`collectd.interface.if_packets` Fields

The collectd if_packets type of interface plug-in.

Parameter Description

Parameter	Description
`collectd.interface.if_packets.rx`	type: float `TODO`
`collectd.interface.if_packets.tx`	type: float `TODO`

collectd.interface.if_packets.rx

type: float

TODO

collectd.interface.if_packets.tx

type: float

TODO

`collectd.interface.if_errors` Fields

The collectd if_errors type of interface plug-in.

Parameter Description

Parameter	Description
`collectd.interface.if_errors.rx`	type: float `TODO`
`collectd.interface.if_errors.tx`	type: float `TODO`

collectd.interface.if_errors.rx

type: float

TODO

collectd.interface.if_errors.tx

type: float

TODO

collectd.interface.if_dropped Fields

The collectd if_dropped type of interface plug-in.

Parameter Description

Parameter	Description
`collectd.interface.if_dropped.rx`	type: float `TODO`
`collectd.interface.if_dropped.tx`	type: float `TODO`

collectd.interface.if_dropped.rx

type: float

TODO

collectd.interface.if_dropped.tx

type: float

TODO

`collectd.virt` Fields

Corresponds to collectd virt plug-in.

`collectd.virt.if_octets` Fields

The collectd if_octets type of virt plug-in.

Parameter Description

Parameter	Description
`collectd.virt.if_octets.rx`	type: float `TODO`
`collectd.virt.if_octets.tx`	type: float `TODO`

collectd.virt.if_octets.rx

type: float

TODO

collectd.virt.if_octets.tx

type: float

TODO

`collectd.virt.if_packets` Fields

The collectd if_packets type of virt plug-in.

Parameter Description

Parameter	Description
`collectd.virt.if_packets.rx`	type: float `TODO`
`collectd.virt.if_packets.tx`	type: float `TODO`

collectd.virt.if_packets.rx

type: float

TODO

collectd.virt.if_packets.tx

type: float

TODO

`collectd.virt.if_errors` Fields

The collectd if_errors type of virt plug-in.

Parameter Description

collectd.virt.if_errors.rx

type: float

TODO

collectd.virt.if_errors.tx

type: float

TODO

`collectd.virt.if_dropped` Fields

The collectd if_dropped type of virt plug-in.

Parameter Description

collectd.virt.if_dropped.rx

type: float

TODO

collectd.virt.if_dropped.tx

type: float

TODO

`collectd.virt.disk_ops` Fields

The collectd disk_ops type of virt plug-in.

Parameter Description

collectd.virt.disk_ops.read

type: float

TODO

collectd.virt.disk_ops.write

type: float

TODO

`collectd.virt.disk_octets` Fields

The collectd disk_octets type of virt plug-in.

Parameter Description

collectd.virt.disk_octets.read

type: float

TODO

collectd.virt.disk_octets.write

type: float

TODO

collectd.virt.memory

type: float

The collectd memory type of virt plug-in.

collectd.virt.virt_vcpu

type: float

The collectd virt_vcpu type of virt plug-in.

collectd.virt.virt_cpu_total

type: float

The collectd virt_cpu_total type of virt plug-in.

`collectd.CPU` Fields

Corresponds to the collectd CPU plug-in.

Parameter Description

collectd.CPU.percent

type: float

The collectd type percent of plug-in CPU.

collectd.df Fields

Corresponds to the collectd df plug-in.

Parameter Description

collectd.df.df_complex

type: float

The collectd type df_complex of plug-in df.

collectd.df.percent_bytes

type: float

The collectd type percent_bytes of plug-in df.

`collectd.entropy` Fields

Corresponds to the collectd entropy plug-in.

Parameter Description

collectd.entropy.entropy

type: integer

The collectd entropy type of entropy plug-in.

`collectd.nfs` Fields

Corresponds to the collectd NFS plug-in.

Parameter Description

collectd.nfs.nfs_procedure

type: integer

The collectd nfs_procedure type of nfs plug-in.

`collectd.memory` Fields

Corresponds to the collectd memory plug-in.

Parameter Description

collectd.memory.memory

type: float

The collectd memory type of memory plug-in.

collectd.memory.percent

type: float

The collectd percent type of memory plug-in.

`collectd.swap` Fields

Corresponds to the collectd swap plug-in.

Parameter Description

collectd.swap.swap

type: integer

The collectd swap type of swap plug-in.

collectd.swap.swap_io

type: integer

The collectd swap_io type of swap plug-in.

`collectd.load` Fields

Corresponds to the collectd load plug-in.

`collectd.load.load` Fields

The collectd load type of load plug-in

Parameter Description

collectd.load.load.shortterm

type: float

TODO

collectd.load.load.midterm

type: float

TODO

collectd.load.load.longterm

type: float

TODO

`collectd.aggregation` Fields

Corresponds to collectd aggregation plug-in.

Parameter Description

collectd.aggregation.percent

type: float

TODO

`collectd.statsd` Fields

Corresponds to collectd statsd plug-in.

Parameter Description

collectd.statsd.host_cpu

type: integer

The collectd CPU type of statsd plug-in.

collectd.statsd.host_elapsed_time

type: integer

The collectd elapsed_time type of statsd plug-in.

collectd.statsd.host_memory

type: integer

The collectd memory type of statsd plug-in.

collectd.statsd.host_nic_speed

type: integer

The collectd nic_speed type of statsd plug-in.

collectd.statsd.host_nic_rx

type: integer

The collectd nic_rx type of statsd plug-in.

collectd.statsd.host_nic_tx

type: integer

The collectd nic_tx type of statsd plug-in.

collectd.statsd.host_nic_rx_dropped

type: integer

The collectd nic_rx_dropped type of statsd plug-in.

collectd.statsd.host_nic_tx_dropped

type: integer

The collectd nic_tx_dropped type of statsd plug-in.

collectd.statsd.host_nic_rx_errors

type: integer

The collectd nic_rx_errors type of statsd plug-in.

collectd.statsd.host_nic_tx_errors

type: integer

The collectd nic_tx_errors type of statsd plug-in.

collectd.statsd.host_storage

type: integer

The collectd storage type of statsd plug-in.

collectd.statsd.host_swap

type: integer

The collectd swap type of statsd plug-in.

collectd.statsd.host_vdsm

type: integer

The collectd VDSM type of statsd plug-in.

collectd.statsd.host_vms

type: integer

The collectd VMS type of statsd plug-in.

collectd.statsd.vm_nic_tx_dropped

type: integer

The collectd nic_tx_dropped type of statsd plug-in.

collectd.statsd.vm_nic_rx_bytes

type: integer

The collectd nic_rx_bytes type of statsd plug-in.

collectd.statsd.vm_nic_tx_bytes

type: integer

The collectd nic_tx_bytes type of statsd plug-in.

collectd.statsd.vm_balloon_min

type: integer

The collectd balloon_min type of statsd plug-in.

collectd.statsd.vm_balloon_max

type: integer

The collectd balloon_max type of statsd plug-in.

collectd.statsd.vm_balloon_target

type: integer

The collectd balloon_target type of statsd plug-in.

collectd.statsd.vm_balloon_cur

type: integer

The collectd balloon_cur type of statsd plug-in.

collectd.statsd.vm_cpu_sys

type: integer

The collectd cpu_sys type of statsd plug-in.

collectd.statsd.vm_cpu_usage

type: integer

The collectd cpu_usage type of statsd plug-in.

collectd.statsd.vm_disk_read_ops

type: integer

The collectd disk_read_ops type of statsd plug-in.

collectd.statsd.vm_disk_write_ops

type: integer

The collectd` disk_write_ops type of statsd plug-in.

collectd.statsd.vm_disk_flush_latency

type: integer

The collectd disk_flush_latency type of statsd plug-in.

collectd.statsd.vm_disk_apparent_size

type: integer

The collectd disk_apparent_size type of statsd plug-in.

collectd.statsd.vm_disk_write_bytes

type: integer

The collectd disk_write_bytes type of statsd plug-in.

collectd.statsd.vm_disk_write_rate

type: integer

The collectd disk_write_rate type of statsd plug-in.

collectd.statsd.vm_disk_true_size

type: integer

The collectd disk_true_size type of statsd plug-in.

collectd.statsd.vm_disk_read_rate

type: integer

The collectd disk_read_rate type of statsd plug-in.

collectd.statsd.vm_disk_write_latency

type: integer

The collectd disk_write_latency type of statsd plug-in.

collectd.statsd.vm_disk_read_latency

type: integer

The collectd disk_read_latency type of statsd plug-in.

collectd.statsd.vm_disk_read_bytes

type: integer

The collectd disk_read_bytes type of statsd plug-in.

collectd.statsd.vm_nic_rx_dropped

type: integer

The collectd nic_rx_dropped type of statsd plug-in.

collectd.statsd.vm_cpu_user

type: integer

The collectd cpu_user type of statsd plug-in.

collectd.statsd.vm_nic_rx_errors

type: integer

The collectd nic_rx_errors type of statsd plug-in.

collectd.statsd.vm_nic_tx_errors

type: integer

The collectd nic_tx_errors type of statsd plug-in.

collectd.statsd.vm_nic_speed

type: integer

The collectd nic_speed type of statsd plug-in.

`collectd.postgresql Fields`

Corresponds to collectd postgresql plug-in.

Parameter Description

collectd.postgresql.pg_n_tup_g

type: integer

The collectd type pg_n_tup_g of plug-in postgresql.

collectd.postgresql.pg_n_tup_c

type: integer

The collectd type pg_n_tup_c of plug-in postgresql.

collectd.postgresql.pg_numbackends

type: integer

The collectd type pg_numbackends of plug-in postgresql.

collectd.postgresql.pg_xact

type: integer

The collectd type pg_xact of plug-in postgresql.

collectd.postgresql.pg_db_size

type: integer

The collectd type pg_db_size of plug-in postgresql.

collectd.postgresql.pg_blks

type: integer

The collectd type pg_blks of plug-in postgresql.

`rsyslog` Fields

The following fields are RFC5424 based metadata.

Parameter Description

rsyslog.facility

See syslog specification for more information on rsyslog.

rsyslog.protocol-version

This is the rsyslog protocol version.

rsyslog.structured-data

See syslog specification for more information on syslog structured-data.

rsyslog.msgid

This is the syslog msgid field.

rsyslog.appname

If app-name is the same as programname, then only fill top-level field service. If app-name is not equal to programname, this field will hold app-name. See syslog specifications for more information.

`systemd` Fields

Contains common fields specific to systemd journal. Applications may write their own fields to the journal. These will be available under the systemd.u namespace. RESULT and UNIT are two such fields.

`systemd.k` Fields

The following table contains systemd kernel-specific metadata.

Parameter Description

systemd.k.KERNEL_DEVICE

systemd.k.KERNEL_DEVICE is the kernel device name.

systemd.k.KERNEL_SUBSYSTEM

systemd.k.KERNEL_SUBSYSTEM is the kernel subsystem name.

systemd.k.UDEV_DEVLINK

systemd.k.UDEV_DEVLINK includes additional symlink names that point to the node.

systemd.k.UDEV_DEVNODE

systemd.k.UDEV_DEVNODE is the node path of the device.

systemd.k.UDEV_SYSNAME

systemd.k.UDEV_SYSNAME is the kernel device name.

`systemd.t` Fields

systemd.t Fields are trusted journal fields, fields that are implicitly added by the journal, and cannot be altered by client code.

Parameter Description

systemd.t.AUDIT_LOGINUID

systemd.t.AUDIT_LOGINUID is the user ID for the journal entry process.

systemd.t.BOOT_ID

systemd.t.BOOT_ID is the kernel boot ID.

systemd.t.AUDIT_SESSION

systemd.t.AUDIT_SESSION is the session for the journal entry process.

systemd.t.CAP_EFFECTIVE

systemd.t.CAP_EFFECTIVE represents the capabilities of the journal entry process.

systemd.t.CMDLINE

systemd.t.CMDLINE is the command line of the journal entry process.

systemd.t.COMM

systemd.t.COMM is the name of the journal entry process.

systemd.t.EXE

systemd.t.EXE is the executable path of the journal entry process.

systemd.t.GID

systemd.t.GID is the group ID for the journal entry process.

systemd.t.HOSTNAME

systemd.t.HOSTNAME is the name of the host.

systemd.t.MACHINE_ID

systemd.t.MACHINE_ID is the machine ID of the host.

systemd.t.PID

systemd.t.PID is the process ID for the journal entry process.

systemd.t.SELINUX_CONTEXT

systemd.t.SELINUX_CONTEXT is the security context, or label, for the journal entry process.

systemd.t.SOURCE_REALTIME_TIMESTAMP

systemd.t.SOURCE_REALTIME_TIMESTAMP is the earliest and most reliable timestamp of the message. This is converted to RFC 3339 NS format.

systemd.t.SYSTEMD_CGROUP

systemd.t.SYSTEMD_CGROUP is the systemd control group path.

systemd.t.SYSTEMD_OWNER_UID

systemd.t.SYSTEMD_OWNER_UID is the owner ID of the session.

systemd.t.SYSTEMD_SESSION

systemd.t.SYSTEMD_SESSION, if applicable, is the systemd session ID.

systemd.t.SYSTEMD_SLICE

systemd.t.SYSTEMD_SLICE is the slice unit of the journal entry process.

systemd.t.SYSTEMD_UNIT

systemd.t.SYSTEMD_UNIT is the unit name for a session.

systemd.t.SYSTEMD_USER_UNIT

systemd.t.SYSTEMD_USER_UNIT, if applicable, is the user unit name for a session.

systemd.t.TRANSPORT

systemd.t.TRANSPORT is the method of entry by the journal service. This includes, audit, driver, syslog, journal, stdout, and kernel.

systemd.t.UID

systemd.t.UID is the user ID for the journal entry process.

systemd.t.SYSLOG_FACILITY

systemd.t.SYSLOG_FACILITY is the field containing the facility, formatted as a decimal string, for syslog.

systemd.t.SYSLOG_IDENTIFIER

systemd.t.systemd.t.SYSLOG_IDENTIFIER is the identifier for syslog.

systemd.t.SYSLOG_PID

SYSLOG_PID is the client process ID for syslog.

`systemd.u` Fields

systemd.u Fields are directly passed from clients and stored in the journal.

Parameter Description

systemd.u.CODE_FILE

systemd.u.CODE_FILE is the code location containing the filename of the source.

systemd.u.CODE_FUNCTION

systemd.u.CODE_FUNCTION is the code location containing the function of the source.

systemd.u.CODE_LINE

systemd.u.CODE_LINE is the code location containing the line number of the source.

systemd.u.ERRNO

systemd.u.ERRNO, if present, is the low-level error number formatted in numeric value, as a decimal string.

systemd.u.MESSAGE_ID

systemd.u.MESSAGE_ID is the message identifier ID for recognizing message types.

systemd.u.RESULT

For private use only.

systemd.u.UNIT

For private use only.

Kubernetes Fields

The namespace for Kubernetes-specific metadata. The kubernetes.pod_name is the name of the pod.

`kubernetes.labels` Fields

Labels attached to the OpenShift object are kubernetes.labels. Each label name is a subfield of labels field. Each label name is de-dotted, meaning dots in the name are replaced with underscores.

Parameter Description

kubernetes.pod_id

Kubernetes ID of the pod.

kubernetes.namespace_name

The name of the namespace in Kubernetes.

kubernetes.namespace_id

ID of the namespace in Kubernetes.

kubernetes.host

Kubernetes node name.

kubernetes.container_name

The name of the container in Kubernetes.

kubernetes.labels.deployment

The deployment associated with the Kubernetes object.

kubernetes.labels.deploymentconfig

The deploymentconfig associated with the Kubernetes object.

kubernetes.labels.component

The component associated with the Kubernetes object.

kubernetes.labels.provider

`kubernetes.annotations` Fields

Annotations associated with the OpenShift object are kubernetes.annotations fields.

Docker Fields

Namespace for docker container-specific metadata. The docker.container_id is the Docker container ID.

`pipeline_metadata` Fields

This includes metadata related to ViaQ log collection pipeline. Everything related to log collector, normalizers, and mappings goes here. Data in this subgroup is stored for troubleshooting and other purposes. The pipeline_metadata.@version field is the version of com.redhat.viaq mapping the document is intended to adhere by the normalizer. It must be set by the normalizer. The value must correspond to the [_meta][version]. For example, class with the description TODO, and region with the description region mapping.

`pipeline_metadata.collector` Fields

This section contains metadata specific to the collector.

Parameter Description

pipeline_metadata.collector.hostname

FQDN of the collector. It might be different from the FQDN of the actual emitter of the logs.

pipeline_metadata.collector.name

Name of the collector.

pipeline_metadata.collector.version

Version of the collector.

pipeline_metadata.collector.ipaddr4

IP address v4 of the collector server, can be an array.

pipeline_metadata.collector.ipaddr6

IP address v6 of the collector server, can be an array.

pipeline_metadata.collector.inputname

How the log message was received by the collector whether it was TCP/UDP, or imjournal/imfile.

pipeline_metadata.collector.received_at

Time when the message was received by the collector.

pipeline_metadata.collector.original_raw_message

The original non-parsed log message, collected by the collector or as close to the source as possible.

`pipeline_metadata.normalizer` Fields

This section contains metadata specific to the normalizer.

Parameter Description

pipeline_metadata.normalizer.hostname

FQDN of the normalizer.

pipeline_metadata.normalizer.name

Name of the normalizer.

pipeline_metadata.normalizer.version

Version of the normalizer.

pipeline_metadata.normalizer.ipaddr4

IP address v4 of the normalizer server, can be an array.

pipeline_metadata.normalizer.ipaddr6

IP address v6 of the normalizer server, can be an array.

pipeline_metadata.normalizer.inputname

how the log message was received by the normalizer whether it was TCP/UDP.

pipeline_metadata.normalizer.received_at

Time when the message was received by the normalizer.

pipeline_metadata.normalizer.original_raw_message

The original non-parsed log message as it is received by the normalizer.

pipeline_metadata.trace

The field records the trace of the message. Each collector and normalizer appends information about itself and the date and time when the message was processed.

oVirt Fields

Namespace for oVirt metadata.

Parameter Description

ovirt.entity

The type of the data source, hosts, VMS, and engine.

ovirt.host_id

The oVirt host UUID.

`ovirt.engine` Fields

Namespace for oVirt engine related metadata. The FQDN of the oVirt engine is ovirt.engine.fqdn

Aushape Fields

Audit events converted with Aushape. For more information please see Aushape.

Parameter Description

aushape.serial

Audit event serial number.

aushape.node

Name of the host where the audit event occurred.

aushape.error

The error aushape encountered while converting the event.

aushape.trimmed

An array of JSONPath expressions relative to the event object, specifying objects or arrays with the content removed as the result of event size limiting. An empty string means the event removed the content, and an empty array means the trimming occurred by unspecified objects and arrays.

aushape.text

An array log record strings representing the original audit event.

`aushape.data` Fields

Parsed audit event data related to Aushape.

Parameter Description

aushape.data.avc

type: nested

aushape.data.execve

type: string

aushape.data.netfilter_cfg

type: nested

aushape.data.obj_pid

type: nested

aushape.data.path

type: nested

Tlog Fields

Tlog terminal I/O recording messages. For more information please see Tlog.

Parameter Description

tlog.ver

Message format version number.

tlog.user

Recorded user name.

tlog.term

Terminal type name.

tlog.session

Audit session ID of the recorded session.

tlog.id

ID of the message within the session.

tlog.pos

Message position in the session, milliseconds.

tlog.timing

Distribution of this message’s events in time.

tlog.in_txt

Input text with invalid characters scrubbed.

tlog.in_bin

Scrubbed invalid input characters as bytes.

tlog.out_txt

Output text with invalid characters scrubbed.

tlog.out_bin

Scrubbed invalid output characters as bytes.

Manual Elasticsearch Rollouts

As of OpenShift Origin 3.7 the Aggregated Logging stack updated the Elasticsearch Deployment Config object so that it no longer has a Config Change Trigger, meaning any changes to the dc will not result in an automatic rollout. This was to prevent unintended restarts happening in the ES cluster, which could create excessive shard rebalancing as cluster members restart.

This section presents two restart procedures: rolling-restart and full-restart. Where a rolling restart applies appropriate changes to the Elasticsearch cluster without down time (provided three masters are configured) and a full restart safely applies major changes without risk to existing data.

Performing an Elasticsearch Rolling Cluster Restart

A rolling restart is recommended, when any of the following changes are made:

nodes on which Elasticsearch pods run require a reboot
logging-elasticsearch configmap
logging-es-* deployment configuration
new image deployment, or upgrade

This will be the recommended restart policy going forward.

Any action you do for an ES cluster will need to be repeated for the ops cluster if openshift_logging_use_ops was configured to be True.

Prevent shard balancing when purposely bringing down nodes:

$ oc exec -c elasticsearch <any_es_pod_in_the_cluster> --
          curl -s
          --cacert /etc/elasticsearch/secret/admin-ca \
          --cert /etc/elasticsearch/secret/admin-cert \
          --key /etc/elasticsearch/secret/admin-key \
          -XPUT 'https://localhost:9200/_cluster/settings' \
          -d '{ "transient": { "cluster.routing.allocation.enable" : "none" } }'

Once complete, for each dc you have for an ES cluster, run oc rollout latest to deploy the latest version of the dc object:
```
$ oc rollout latest <dc_name>
```
You will see a new pod deployed. Once the pod has two ready containers, you can move on to the next dc.

Once all `dc`s for the cluster have been rolled out, re-enable shard balancing:

$ oc exec -c elasticsearch <any_es_pod_in_the_cluster> --
          curl -s
          --cacert /etc/elasticsearch/secret/admin-ca \
          --cert /etc/elasticsearch/secret/admin-cert \
          --key /etc/elasticsearch/secret/admin-key \
          -XPUT 'https://localhost:9200/_cluster/settings' \
          -d '{ "transient": { "cluster.routing.allocation.enable" : "all" } }'

Performing an Elasticsearch Full Cluster Restart

A full restart is recommended when changing major versions of Elasticsearch or other changes which might put data integrity a risk during the change process.

Any action you do for an ES cluster will need to be repeated for the ops cluster if openshift_logging_use_ops was configured to be True.

When making changes to the logging-es-ops service use components "es-ops-blocked" and "es-ops" instead in the patch

Disable all external communications to the ES cluster while it is down. Edit your non-cluster logging service (for example, logging-es, logging-es-ops) to no longer match the ES pods running:
```
$  oc patch svc/logging-es -p '{"spec":{"selector":{"component":"es-blocked","provider":"openshift"}}}'
```

Prevent shard balancing when purposely bringing down nodes:

$ oc exec -c elasticsearch <any_es_pod_in_the_cluster> --
          curl -s
          --cacert /etc/elasticsearch/secret/admin-ca \
          --cert /etc/elasticsearch/secret/admin-cert \
          --key /etc/elasticsearch/secret/admin-key \
          -XPUT 'https://localhost:9200/_cluster/settings' \
          -d '{ "transient": { "cluster.routing.allocation.enable" : "none" } }'

Perform a shard synced flush to ensure there are no pending operations waiting to be written to disk prior to shutting down:

$ oc exec -c elasticsearch <any_es_pod_in_the_cluster> --
          curl -s
          --cacert /etc/elasticsearch/secret/admin-ca \
          --cert /etc/elasticsearch/secret/admin-cert \
          --key /etc/elasticsearch/secret/admin-key \
          -XPUT 'https://localhost:9200/_flush/synced'

Once complete, for each dc you have for an ES cluster, run oc rollout latest to deploy the latest version of the dc object:
```
$ oc rollout latest <dc_name>
```
You will see a new pod deployed. Once the pod has two ready containers, you can move on to the next dc.

Once all DCs for the cluster have been rolled out, re-enable shard balancing:

$ oc exec -c elasticsearch <any_es_pod_in_the_cluster> --
          curl -s
          --cacert /etc/elasticsearch/secret/admin-ca \
          --cert /etc/elasticsearch/secret/admin-cert \
          --key /etc/elasticsearch/secret/admin-key \
          -XPUT 'https://localhost:9200/_cluster/settings' \
          -d '{ "transient": { "cluster.routing.allocation.enable" : "all" } }'

Once the restart is complete, enable all external communications to the ES cluster. Edit your non-cluster logging service (for example, logging-es, logging-es-ops) to match the ES pods running again:
```
$ oc patch svc/logging-es -p '{"spec":{"selector":{"component":"es","provider":"openshift"}}}'
```

Overview

Pre-deployment Configuration

Specifying Logging Ansible Variables

Deploying the EFK Stack

Understanding and Adjusting the Deployment

Ops Cluster

Elasticsearch

Fluentd

Kibana

Curator

Creating the Curator Configuration

Cleanup

Troubleshooting Kibana

Sending Logs to an External Elasticsearch Instance

Sending Logs to an External Syslog Server

Performing Administrative Elasticsearch Operations

Changing the Aggregated Logging Driver

Updating Fluentd’s Log Source After a Docker Log Driver Update

Exported Fields

Top Level Fields

collectd Fields

collectd.processes Fields

collectd.processes.ps_disk_ops Fields

collectd.processes.ps_cputime Fields

collectd.processes.ps_count Fields

collectd.processes.ps_pagefaults Fields

collectd.processes.ps_disk_octets Fields

collectd.disk Fields

collectd.disk.disk_merged Fields

collectd.disk.disk_octets Fields

collectd.disk.disk_time Fields

collectd.disk.disk_ops Fields

collectd.disk.disk_io_time Fields

collectd.interface Fields

collectd.interface.if_octets Fields

collectd.interface.if_packets Fields

collectd.interface.if_errors Fields

collectd.interface.if_dropped Fields

collectd.virt Fields

collectd.virt.if_octets Fields

collectd.virt.if_packets Fields

collectd.virt.if_errors Fields

collectd.virt.if_dropped Fields

collectd.virt.disk_ops Fields

collectd.virt.disk_octets Fields

collectd.CPU Fields

collectd.df Fields

collectd.entropy Fields

collectd.nfs Fields

collectd.memory Fields

collectd.swap Fields

collectd.load Fields

collectd.load.load Fields

collectd.aggregation Fields

collectd.statsd Fields

collectd.postgresql Fields

rsyslog Fields

systemd Fields

systemd.k Fields

systemd.t Fields

systemd.u Fields

Kubernetes Fields

kubernetes.labels Fields

kubernetes.annotations Fields

Docker Fields

pipeline_metadata Fields

pipeline_metadata.collector Fields

pipeline_metadata.normalizer Fields

oVirt Fields

ovirt.engine Fields

Aushape Fields

aushape.data Fields

Tlog Fields

Manual Elasticsearch Rollouts

Performing an Elasticsearch Rolling Cluster Restart

Performing an Elasticsearch Full Cluster Restart

`collectd` Fields

`collectd.processes` Fields

`collectd.processes.ps_disk_ops` Fields

`collectd.processes.ps_cputime` Fields

`collectd.processes.ps_count` Fields

`collectd.processes.ps_pagefaults` Fields

`collectd.processes.ps_disk_octets` Fields

`collectd.disk` Fields

`collectd.disk.disk_merged` Fields

`collectd.disk.disk_octets` Fields

`collectd.disk.disk_time` Fields

`collectd.disk.disk_ops` Fields

`collectd.disk.disk_io_time` Fields

`collectd.interface` Fields

`collectd.interface.if_octets` Fields

`collectd.interface.if_packets` Fields

`collectd.interface.if_errors` Fields

`collectd.virt` Fields

`collectd.virt.if_octets` Fields

`collectd.virt.if_packets` Fields

`collectd.virt.if_errors` Fields

`collectd.virt.if_dropped` Fields

`collectd.virt.disk_ops` Fields

`collectd.virt.disk_octets` Fields

`collectd.CPU` Fields

`collectd.entropy` Fields

`collectd.nfs` Fields

`collectd.memory` Fields

`collectd.swap` Fields

`collectd.load` Fields

`collectd.load.load` Fields

`collectd.aggregation` Fields

`collectd.statsd` Fields

`collectd.postgresql Fields`

`rsyslog` Fields

`systemd` Fields

`systemd.k` Fields

`systemd.t` Fields

`systemd.u` Fields

`kubernetes.labels` Fields

`kubernetes.annotations` Fields

`pipeline_metadata` Fields

`pipeline_metadata.collector` Fields

`pipeline_metadata.normalizer` Fields

`ovirt.engine` Fields

`aushape.data` Fields