<commit_before>[[admin-guide-router]]
= Monitoring Routers
{product-author}
{product-version]
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
Depending on the underlying implementation, you can monitor a running
xref:../architecture/core_concepts/routes.adoc#architecture-core-concepts-routes[router] in multiple ways. This
topic discusses the HAProxy template router and the components to check to
ensure its health.

== Viewing Statistics
The HAProxy router exposes a web listener for the HAProxy statistics. Enter the
router's public IP address and the correctly configured port (*1936* by default)
to view the statistics page, and enter the administrator password when prompted.
This password and port are configured during the router installation, but they
can be found by viewing the *_haproxy.config_* file on the container.

== Disabling Statistics View
By default the HAProxy statistics are exposed on port *1936* (with a
password protected account). To disable exposing the HAProxy statistics,
specify *0* as the stats port number.

ifdef::openshift-enterprise[]
====
----
$ oadm router hap --service-account=router --stats-port=0  \
    --credentials='/etc/origin/master/openshift-router.kubeconfig'
----
====
endif::[]
ifdef::openshift-origin[]
====
----
$ oadm router hap --service-account=router --stats-port=0  \
    --credentials="$KUBECONFIG"
----
====
endif::[]


Note: HAProxy will still collect and store statistics, it would just _not_
      expose them via a web listener. You can still get access to the
      statistics by sending a request to the HAProxy AF_UNIX socket inside
      the HAProxy Router container.

====
----
$ cmd="echo 'show stat' | socat - UNIX-CONNECT:/var/lib/haproxy/run/haproxy.sock"
$ routerPod=$(oc get pods --selector="router=router"  \
    --template="{{with index .items 0}}{{.metadata.name}}{{end}}")
$ oc exec $routerPod -- bash -c "$cmd"
----
====

[IMPORTANT]
====
link:https://access.redhat.com/errata/RHSA-2015:1650[For security purposes], the
`oc exec` command does not work when accessing privileged containers. Instead,
you can SSH into a node host, then use the `docker exec` command on the desired
container.
====

== Viewing Logs
To view a router log, run the `oc logs` command on the pod. Since the router is
running as a plug-in process that manages the underlying implementation, the log
is for the plug-in, not the actual HAProxy log.

To view the logs generated by HAProxy you need to start a syslog server and pass
the location to a router pod using two environment variables.

.Router Syslog Variables [[syslog-vars]]
[cols="3a,8a",options="header"]
|===

|Environment Variable | Description

|`*ROUTER_SYSLOG_ADDRESS*`
|The IP address of the SYSLOG server. Port *514* is the
default if no port is specified.

|`*ROUTER_LOG_LEVEL*`
|Optional, set to change the log level of HAProxy. If  not set  the default log
level is `warning`; this can be changed to any of the 8 log levels that
HAProxy supports.
|===

To set a running router pod to send messages to a syslog server:
====
----
$ oc env dc/router ROUTER_SYSLOG_ADDRESS=<dest_ip:dest_port>  ROUTER_LOG_LEVEL=<level>
----
====

For example:

----
$ oc env dc/router ROUTER_SYSLOG_ADDRESS=127.0.0.1 ROUTER_LOG_LEVEL=debug
----

sets HAProxy to log send logs to 127.0.0.1 with default port *514* and changes
the log level to debug.

== Viewing the Router Internals
*routes.json*

Routes are processed by the HAProxy router, and are stored both in memory, on
disk, and in the HAProxy configuration file. The internal route representation,
which is passed to the template to generate the HAProxy configuration file, is
found in the *_/var/lib/containers/router/routes.json_* file. When
troubleshooting a routing issue, view this file to see the data being used to
drive configuration.

*HAProxy configuration*
<commit_msg>followup edits to PR 1873<commit_after>[[admin-guide-router]]
= Monitoring Routers
{product-author}
{product-version]
:data-uri:
:icons:
:experimental:
:toc: macro
:toc-title:
:prewrap!:

toc::[]

== Overview
Depending on the underlying implementation, you can monitor a running
xref:../architecture/core_concepts/routes.adoc#architecture-core-concepts-routes[router] in multiple ways. This
topic discusses the HAProxy template router and the components to check to
ensure its health.

== Viewing Statistics
The HAProxy router exposes a web listener for the HAProxy statistics. Enter the
router's public IP address and the correctly configured port (*1936* by default)
to view the statistics page, and enter the administrator password when prompted.
This password and port are configured during the router installation, but they
can be found by viewing the *_haproxy.config_* file on the container.

== Disabling Statistics View
By default the HAProxy statistics are exposed on port *1936* (with a
password protected account). To disable exposing the HAProxy statistics,
specify *0* as the stats port number.

ifdef::openshift-enterprise[]
====
----
$ oadm router hap --service-account=router --stats-port=0  \
    --credentials='/etc/origin/master/openshift-router.kubeconfig'
----
====
endif::[]
ifdef::openshift-origin[]
====
----
$ oadm router hap --service-account=router --stats-port=0  \
    --credentials="$KUBECONFIG"
----
====
endif::[]


Note: HAProxy will still collect and store statistics, it would just _not_
      expose them via a web listener. You can still get access to the
      statistics by sending a request to the HAProxy AF_UNIX socket inside
      the HAProxy Router container.

====
----
$ cmd="echo 'show stat' | socat - UNIX-CONNECT:/var/lib/haproxy/run/haproxy.sock"
$ routerPod=$(oc get pods --selector="router=router"  \
    --template="{{with index .items 0}}{{.metadata.name}}{{end}}")
$ oc exec $routerPod -- bash -c "$cmd"
----
====

[IMPORTANT]
====
link:https://access.redhat.com/errata/RHSA-2015:1650[For security purposes], the
`oc exec` command does not work when accessing privileged containers. Instead,
you can SSH into a node host, then use the `docker exec` command on the desired
container.
====

== Viewing Logs
To view a router log, run the `oc logs` command on the pod. Since the router is
running as a plug-in process that manages the underlying implementation, the log
is for the plug-in, not the actual HAProxy log.

To view the logs generated by HAProxy, start a syslog server and pass the
location to a router pod using the following environment variables.

.Router Syslog Variables [[syslog-vars]]
[cols="3a,8a",options="header"]
|===

|Environment Variable | Description

|`*ROUTER_SYSLOG_ADDRESS*`
|The IP address of the syslog server. Port *514* is the default if no port is
specified.

|`*ROUTER_LOG_LEVEL*`
|Optional. Set to change the HAProxy log level. If not set, the default log
level is *warning*. This can be changed to any log level that HAProxy supports.
|===

To set a running router pod to send messages to a syslog server:
====
----
$ oc env dc/router ROUTER_SYSLOG_ADDRESS=<dest_ip:dest_port>  ROUTER_LOG_LEVEL=<level>
----
====

For example, the following sets HAProxy to send logs to 127.0.0.1 with the
default port *514* and changes the log level to *debug*.

----
$ oc env dc/router ROUTER_SYSLOG_ADDRESS=127.0.0.1 ROUTER_LOG_LEVEL=debug
----

== Viewing the Router Internals
*routes.json*

Routes are processed by the HAProxy router, and are stored both in memory, on
disk, and in the HAProxy configuration file. The internal route representation,
which is passed to the template to generate the HAProxy configuration file, is
found in the *_/var/lib/containers/router/routes.json_* file. When
troubleshooting a routing issue, view this file to see the data being used to
drive configuration.

*HAProxy configuration*

{'fraction_non_alphanumeric': 0.10460035980467747, 'fraction_numerical': 0.010922641994345927, 'mean_word_length': 4.330821917808219, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 4, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2095523', 'n_tokens_mistral': 2365, 'n_tokens_neox': 2255, 'n_words': 962}