8.3. Advanced logging options

Some advanced logging options are often looked for but are not easy to find out
just by looking at the various options. Here is an entry point for the few
options which can enable better logging. Please refer to the keywords reference
for more information about their usage.

8.3.1. Disabling logging of external tests

It is quite common to have some monitoring tools perform health checks on
haproxy. Sometimes it will be a layer 3 load-balancer such as LVS or any
commercial load-balancer, and sometimes it will simply be a more complete
monitoring system such as Nagios. When the tests are very frequent, users often
ask how to disable logging for those checks. There are three possibilities :
 
  - if connections come from everywhere and are just TCP probes, it is often
    desired to simply disable logging of connections without data exchange, by
    setting "option dontlognull" in the frontend. It also disables logging of
    port scans, which may or may not be desired.
 
  - if the connection come from a known source network, use "monitor-net" to
    declare this network as monitoring only. Any host in this network will then
    only be able to perform health checks, and their requests will not be
    logged. This is generally appropriate to designate a list of equipment
    such as other load-balancers.
 
  - if the tests are performed on a known URI, use "monitor-uri" to declare
    this URI as dedicated to monitoring. Any host sending this request will
    only get the result of a health-check, and the request will not be logged.

8.3.2. Logging before waiting for the session to terminate

The problem with logging at end of connection is that you have no clue about
what is happening during very long sessions, such as remote terminal sessions
or large file downloads. This problem can be worked around by specifying
"option logasap" in the frontend. HAProxy will then log as soon as possible,
just before data transfer begins. This means that in case of TCP, it will still
log the connection status to the server, and in case of HTTP, it will log just
after processing the server headers. In this case, the number of bytes reported
is the number of header bytes sent to the client. In order to avoid confusion
with normal logs, the total time field and the number of bytes are prefixed
with a '+' sign which means that real numbers are certainly larger.

8.3.3. Raising log level upon errors

Sometimes it is more convenient to separate normal traffic from errors logs,
for instance in order to ease error monitoring from log files. When the option
"log-separate-errors" is used, connections which experience errors, timeouts,
retries, redispatches or HTTP status codes 5xx will see their syslog level
raised from "info" to "err". This will help a syslog daemon store the log in
a separate file. It is very important to keep the errors in the normal traffic
file too, so that log ordering is not altered. You should also be careful if
you already have configured your syslog daemon to store all logs higher than
"notice" in an "admin" file, because the "err" level is higher than "notice".

8.3.4. Disabling logging of successful connections

Although this may sound strange at first, some large sites have to deal with
multiple thousands of logs per second and are experiencing difficulties keeping
them intact for a long time or detecting errors within them. If the option
"dontlog-normal" is set on the frontend, all normal connections will not be
logged. In this regard, a normal connection is defined as one without any
error, timeout, retry nor redispatch. In HTTP, the status code is checked too,
and a response with a status 5xx is not considered normal and will be logged
too. Of course, doing is is really discouraged as it will remove most of the
useful information from the logs. Do this only if you have no other
alternative.