Global Profiling Engine

Configure logging for the Global Profiling Engine

On this page

You have several options for logging Global Profiling Engine events.

  • Write each syslog priority level to a separate file.
  • Log to a UNIX domain socket (local syslog server).
  • Log to a TCP/UDP inet socket (remote syslog server).
  • (legacy) Redirect the stdout/stderr stream output to a file.

Write syslog priority levels to files Jump to heading

Available since

  • HAProxy Enterprise - GPE version 1.0 (hapee-extras-gpe10 package or newer)

To write logged messages with different priority levels to a file:

  1. Create the directory where you will save log files, such as /var/log/haproxy-gpe/.

    nix
    sudo mkdir /var/log/haproxy-gpe/
    nix
    sudo mkdir /var/log/haproxy-gpe/

  2. Edit the file /etc/hapee-extras/hapee-gpe.json. Add log_format, log_stderr, and log_files fields:

    hapee-gpe.json
    json
    {
      "worker_thread_count": 4,
      "inter_worker_queue_size": 1024,
      "collector_queue_size": 64,
      "httpd_port": 9888,
      "datadir": "/var/cache/hapee-extras/hct_datadir",
      "default_stick_table_handling": 1,
      "prometheus_exporter": 1,
      "ignore_tables": [],
      "detail_tables": [],
      "aggregate_tables": [],
      "stat_retentions": [
        {
          "duration": 300,
          "retention": 12
        },
        {
          "duration": 3600,
          "retention": 24
        },
        {
          "duration": 86400,
          "retention": 14
        }
      ],
      "log_format": "file",
      "log_stderr": "local3",
      "log_files": [
        { "priority": "all",     "path": "/var/log/haproxy-gpe/common.log"  },
        { "priority": "err",     "path": "/var/log/haproxy-gpe/err.log"     },
        { "priority": "warning", "path": "/var/log/haproxy-gpe/warning.log" }
      ]
    }
    hapee-gpe.json
    json
    {
      "worker_thread_count": 4,
      "inter_worker_queue_size": 1024,
      "collector_queue_size": 64,
      "httpd_port": 9888,
      "datadir": "/var/cache/hapee-extras/hct_datadir",
      "default_stick_table_handling": 1,
      "prometheus_exporter": 1,
      "ignore_tables": [],
      "detail_tables": [],
      "aggregate_tables": [],
      "stat_retentions": [
        {
          "duration": 300,
          "retention": 12
        },
        {
          "duration": 3600,
          "retention": 24
        },
        {
          "duration": 86400,
          "retention": 14
        }
      ],
      "log_format": "file",
      "log_stderr": "local3",
      "log_files": [
        { "priority": "all",     "path": "/var/log/haproxy-gpe/common.log"  },
        { "priority": "err",     "path": "/var/log/haproxy-gpe/err.log"     },
        { "priority": "warning", "path": "/var/log/haproxy-gpe/warning.log" }
      ]
    }

    where:

    • log_format is file.
    • log_stderr redirects stderr messages to the local3 syslog facility. You can choose any facility value, but you must configure your local syslog service to handle these messages.
    • log_files is an array of files to write to for each syslog priority. Use any of emerg, alert, crit, err, warning, notice, info, or debug. Use all as a catch-all for all other priorities. If the file doesn’t exist, it will be created automatically, which gives you a way to archive log files by changing the file’s name, since the file will be recreated.

    For more details, see Reference.

  3. Restart the GPE service:

    nix
    sudo systemctl restart hapee-extras-gpe
    nix
    sudo systemctl restart hapee-extras-gpe

Log to UNIX domain socket Jump to heading

Available since

  • HAProxy Enterprise - GPE version 1.0 (hapee-extras-gpe10 package or newer)

To write logged messages to a syslog UNIX domain socket on the GPE server:

  1. Edit the file /etc/hapee-extras/hapee-gpe.json. Add log_format, log_stderr, and log_socket fields:

    hapee-gpe.json
    json
    {
      "worker_thread_count": 4,
      "inter_worker_queue_size": 1024,
      "collector_queue_size": 64,
      "httpd_port": 9888,
      "datadir": "/var/cache/hapee-extras/hct_datadir",
      "default_stick_table_handling": 1,
      "prometheus_exporter": 1,
      "ignore_tables": [],
      "detail_tables": [],
      "aggregate_tables": [],
      "stat_retentions": [
        {
          "duration": 300,
          "retention": 12
        },
        {
          "duration": 3600,
          "retention": 24
        },
        {
          "duration": 86400,
          "retention": 14
        }
      ],
      "log_format": "rfc3164",
      "log_stderr": "local3",
      "log_socket": "/dev/log"
    }
    hapee-gpe.json
    json
    {
      "worker_thread_count": 4,
      "inter_worker_queue_size": 1024,
      "collector_queue_size": 64,
      "httpd_port": 9888,
      "datadir": "/var/cache/hapee-extras/hct_datadir",
      "default_stick_table_handling": 1,
      "prometheus_exporter": 1,
      "ignore_tables": [],
      "detail_tables": [],
      "aggregate_tables": [],
      "stat_retentions": [
        {
          "duration": 300,
          "retention": 12
        },
        {
          "duration": 3600,
          "retention": 24
        },
        {
          "duration": 86400,
          "retention": 14
        }
      ],
      "log_format": "rfc3164",
      "log_stderr": "local3",
      "log_socket": "/dev/log"
    }

    where:

    • log_format is rfc3164.
    • log_stderr redirects stderr messages to the local3 syslog facility. You can choose any facility value, but you must configure your local syslog service to handle these messages.
    • log_socket is the socket’s file path.

    For more details, see Reference.

    The GPE server will send messages to the local syslog server with a predefined set of syslog facility codes that map to severity levels, which cannot be overridden. Configure your syslog server to expect these facility codes:

    GPE Priority Facility Syslog Priority
    emerg local0 local0.debug
    alert local1 local1.debug
    crit local2 local2.debug
    err local3 local3.debug
    warning local4 local4.debug
    notice local5 local5.debug
    info local6 local6.debug
    debug local7 local7.debug

    The exception is logging the stderr stream to syslog, where any syslog facility can be specified as output. The syslog priority used in that case is .debug.

  2. Restart the GPE service:

    nix
    sudo systemctl restart hapee-extras-gpe
    nix
    sudo systemctl restart hapee-extras-gpe

Log to TCP/UDP inet socket Jump to heading

Available since

  • HAProxy Enterprise - GPE version 1.0 (hapee-extras-gpe10 package or newer)

To write logged messages to a remote syslog server:

  1. Edit the file /etc/hapee-extras/hapee-gpe.json. Add log_format, log_stderr, and log_proto, log_nodename, and log_servname fields:

    hapee-gpe.json
    json
    {
      "worker_thread_count": 4,
      "inter_worker_queue_size": 1024,
      "collector_queue_size": 64,
      "httpd_port": 9888,
      "datadir": "/var/cache/hapee-extras/hct_datadir",
      "default_stick_table_handling": 1,
      "prometheus_exporter": 1,
      "ignore_tables": [],
      "detail_tables": [],
      "aggregate_tables": [],
      "stat_retentions": [
        {
          "duration": 300,
          "retention": 12
        },
        {
          "duration": 3600,
          "retention": 24
        },
        {
          "duration": 86400,
          "retention": 14
        }
      ],
      "log_format": "rfc5424",
      "log_stderr": "local3",
      "log_proto": "tcp",
      "log_nodename": "192.168.56.10",
      "log_servname": "514"
    }
    hapee-gpe.json
    json
    {
      "worker_thread_count": 4,
      "inter_worker_queue_size": 1024,
      "collector_queue_size": 64,
      "httpd_port": 9888,
      "datadir": "/var/cache/hapee-extras/hct_datadir",
      "default_stick_table_handling": 1,
      "prometheus_exporter": 1,
      "ignore_tables": [],
      "detail_tables": [],
      "aggregate_tables": [],
      "stat_retentions": [
        {
          "duration": 300,
          "retention": 12
        },
        {
          "duration": 3600,
          "retention": 24
        },
        {
          "duration": 86400,
          "retention": 14
        }
      ],
      "log_format": "rfc5424",
      "log_stderr": "local3",
      "log_proto": "tcp",
      "log_nodename": "192.168.56.10",
      "log_servname": "514"
    }

    where:

    • log_format is rfc5424.
    • log_stderr redirects stderr messages to the local3 syslog facility. You can choose any facility value, but you must configure your target syslog service to handle these messages.
    • log_proto is either tcp or udp.
    • log_nodename is the remote syslog server’s address.
    • log_servename is the remote syslog server’s service name or a decimal port number like 514.

    For more details, see Reference.

    The GPE server will send messages to the remote syslog server with a predefined set of syslog facility codes that map to severity levels, which cannot be overridden. Configure your syslog server to expect these facility codes:

    GPE Priority Facility Syslog Priority
    emerg local0 local0.debug
    alert local1 local1.debug
    crit local2 local2.debug
    err local3 local3.debug
    warning local4 local4.debug
    notice local5 local5.debug
    info local6 local6.debug
    debug local7 local7.debug

    The exception is logging the stderr stream to syslog, where any syslog facility can be specified as output. The syslog priority used in that case is .debug.

  2. Restart the GPE service:

    nix
    sudo systemctl restart hapee-extras-gpe
    nix
    sudo systemctl restart hapee-extras-gpe

Redirect stdout/stderr to a file Jump to heading

Legacy notice

This is the legacy way to log to a file. It’s better to write syslog priority levels to files.

To redirect all logged messages from stdout / stderr to a file:

  1. Edit the file /etc/default/hapee-extras-gpe and set the -l startup argument to a file path. Prefix the path with either A: for append or W: for truncate. For details, see Startup arguments.

    hapee-extras-gpe
    text
    GPE_OPTIONS="-f /etc/hapee-extras/hapee-gpe-stktagg.cfg -c /etc/hapee-extras/hapee-gpe.json -l A:/var/log/haproxy-gpe/log-file.txt"
    hapee-extras-gpe
    text
    GPE_OPTIONS="-f /etc/hapee-extras/hapee-gpe-stktagg.cfg -c /etc/hapee-extras/hapee-gpe.json -l A:/var/log/haproxy-gpe/log-file.txt"

  2. Restart the GPE service:

    nix
    sudo systemctl restart hapee-extras-gpe
    nix
    sudo systemctl restart hapee-extras-gpe

Reference Jump to heading

This section describes the available log setting fields.

Field Type Description
log_appname string rfc5424 APP-NAME field (default: -).
log_files array

Each array item specifies:

  • priority: emerg, alert, crit, err, warning, notice, info, debug. Use all to indicate others not otherwise handled.
  • Full path of the log file, such as /var/log/gpe-debug.txt.
log_format string Set to rfc3164 to use the rfc3164 protocol, rfc5424 to use the rfc5424 protocol, or to the path of a file.
log_hostname string rfc3164/rfc5424 HOSTNAME field (default: hostname where the program is running).
log_msgid string rfc5424 MSGID field (default: -).
log_nodename string Node name or an IP address of the syslog server.
log_procid string rfc5424 PROCID field (default: -, process ID if PID is entered for the value).
log_proto string Protocol used when connecting to the syslog server: tcp or udp.
log_servname string A service name or TCP/UDP port number of the syslog server. Default: 514.
log_socket string Full path of the UNIX domain syslog socket.
log_stderr string Syslog facility to which log messages are sent from stderr stream (default: not used). Choose any facility code, but be sure to configure the receiving syslog server to expect messages with this facility.
log_rec_len number The size of the circular buffer for log messages (in bytes) (2 - 8192, default: 256).
log_rec_size number The maximum size of a syslog message (in bytes) (256 - 2048, default: 512).

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?

Previous page Historical aggregation Next page Reference
© 2025 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences