// Module included in the following assemblies:
//
// * ingress/configure-ingress-operator.adoc

:_mod-docs-content-type: PROCEDURE
[id="nw-configure-ingress-access-logging_{context}"]
= Configuring Ingress access logging

You can configure the Ingress Controller to enable access logs. If you have clusters that do not receive much traffic, then you can log to a sidecar. If you have high traffic clusters, to avoid exceeding the capacity of the logging stack or  to integrate with a logging infrastructure outside of {product-title}, you can forward logs to a custom syslog endpoint. You can also specify the format for access logs.

Container logging is useful to enable access logs on low-traffic clusters when there is no existing Syslog logging infrastructure, or for short-term use while diagnosing problems with the Ingress Controller.

Syslog is needed for high-traffic clusters where access logs could exceed the OpenShift Logging stack's capacity, or for environments where any logging solution needs to integrate with an existing Syslog logging infrastructure. The Syslog use-cases can overlap.

.Prerequisites

* Log in as a user with `cluster-admin` privileges.

.Procedure

* For Ingress access logging to a sidecar, complete the following commands:
+
** To enable Ingress access logging to a sidecar, enter the following command:
+
[source,terminal]
----
$ oc patch ingresscontroller default -n openshift-ingress-operator --type=merge \
  -p '{"spec":{"logging":{"access":{"destination":{"type":"Container"}}}}}'
----
+
After you configure the Ingress Controller to log to a sidecar, the Operator creates a container named `logs` inside a router pod that exists in the `openshift-ingress` namespace.
+
** If you need to disable Ingress access logging, enter the following command that does not specify any values for `spec.logging`:
+
[source,terminal]
----
$ oc patch ingresscontroller default -n openshift-ingress-operator --type=json \
  -p='[{"op": "remove", "path": "/spec/logging"}]'
----
+
** To stream the access logs and system events from the {product-title} Ingress Controller, enter the following command:     
+
[source,terminal]
----
$ oc -n openshift-ingress logs deployment.apps/router-default -c logs
----
+
.Example output
[source,terminal]
----
2020-05-11T19:11:50.135710+00:00 router-default-57dfc6cd95-bpmk6 router-default-57dfc6cd95-bpmk6 haproxy[108]: 174.19.21.82:39654 [11/May/2020:19:11:50.133] public be_http:hello-openshift:hello-openshift/pod:hello-openshift:hello-openshift:10.128.2.12:8080 0/0/1/0/1 200 142 - - --NI 1/1/0/0/0 0/0 "GET / HTTP/1.1"
----

* To enable logging to an external Syslog server, enter the following command. Use this option if you need to forward logs to a centralized logging solution such as Splunk, Rsyslog, or Logstash.
+
[source,terminal]
----
$ oc patch ingresscontroller default -n openshift-ingress-operator --type=merge \
  -p '{"spec":{"logging":{"access":{"destination":{"type":"Syslog","syslog":{"address":"1.2.3.4","port":514,"maxLenght":1024}}}}}}'
----
+
** Replace `1.2.3.4` with the destination IP address of your logging server. Syslog does not support a DNS hostname value. 
** Replace `514` with the UDP destination port of your logging server.
** Replace `1024` with the maximum length of a log message in bytes that you want to set for log messages.

* To customize the log format, append an HAProxy-compatible log string to the following command. The string determines what information gets captured in the log format, such as a client IP address.
+
[source,terminal]
----
$ oc patch ingresscontroller default -n openshift-ingress-operator --type=merge \
  -p '{"spec":{"logging":{"access":{"httpLogFormat":"%ci:%cp [%t] %ft %b/%s %B %bq %HM %HU %HV"}}}}'
----
+
[NOTE]
====
For a list of HAProxy log variable descriptions, see link:https://docs.haproxy.org/2.8/configuration.html#8.2.6[Custom log format] in the upstream HAProxy documentation. 
====

* To capture custom HTTP headers or response headers in your logs, enter the following command. Consider this option if you need to track an `X-Forwarded-For` header or custom application IDs in the Ingress and application logs.
+
[source,terminal]
----
$ oc patch ingresscontroller default -n openshift-ingress-operator --type=merge -p '{"spec":{"logging":{"access":{"httpCaptureHeaders":{"request":[{"name":"User-Agent","maxLength": 1024}],"response":[{"name":"Content-Type","maxLength": 1024}]}}}}}'
----

* To configure a log empty requests policy, enter the following command and set the `logEmptyRequests` parameter to `Log`. By default, HAProxy might not log empty requests or health checks, so you must manually enable this feature. To disable the feature, set the `logEmptyRequests` parameter to `Ignore`.
+
[source,terminal]
----
$ oc patch ingresscontroller default -n openshift-ingress-operator --type=merge -p '{"spec":{"logging":{"access":{"logEmptyRequests":"Ignore"}}}}'
----
