set profiling

Enable or disable profiling.

Description Jump to heading #

Enable (on) or disable (off) profiling.

This operation is equivalent to setting or clearing the profiling settings in the global section of the configuration file. Profiling is essentially intended for product developers as it exposes CPU and memory consumption in the code. This command enables or disables per-task CPU profiling. As of version 2.4r1, by default, or when the tasks argument is specified, this command enables or disables per-task CPU profiling.

CPU profiling per task reveals where CPU execution time is spent and how requests affect each other. Enabling profiling typically affects overall performance by less than 1%. This feature requires a system supporting the clock_gettime(2) system call with clock identifiers CLOCK_MONOTONIC and CLOCK_THREAD_CPUTIME_ID. Otherwise, the reported time is zero.

Enabling task profiling manually resets scheduler statistics, providing a convenient way to check activity over a given interval.

As of version 2.0r1, when per-task CPU profiling is set to auto, profiling automatically initiates a thread when it starts to suffer from an average latency of 1000 microseconds or higher as reported in the avg_loop_us activity field. Profiling automatically turns off when the latency returns below 990 microseconds. This value is an average over the last 1024 loops so it does not vary quickly and tends to significantly smooth short spikes. Profiling may also spontaneously trigger from time to time on overloaded systems, containers, virtual machines, or when the system swaps (which must absolutely never happen on a load balancer).

In general, it is recommended to leave profiling set to the default auto value so that it only operates when a problem is identified.

As of version 2.4r1, as an alternative to per-task CPU profiling, you can perform per-function memory profiling by specifying the memory argument instead of tasks.

Per-function memory profiling keeps usage statistics of malloc, calloc, realloc, and free calls anywhere in the process (including libraries) which will be reported on the CLI using the show profiling command. This is essentially meant to be used when an abnormal memory usage is observed that cannot be explained by the pools and other info are required. The performance hit will typically be around 1%, maybe a bit more on highly threaded machines, so it is normally suitable for use in production.

Memory profiling is supported only on certain operating systems (known to work on the linux-glibc target), and requires USE_MEMORY_PROFILING to be set at compile time.

Examples Jump to heading #

Enable per-task CPU profiling:

nix
echo "set profiling on" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "set profiling on" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Enable automatic mode for per-task CPU profiling (as of version 2.0r1):

nix
echo "set profiling tasks auto" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "set profiling tasks auto" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Enable per-function memory profiling (as of version 2.4r1):

nix
echo "set profiling memory on" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "set profiling memory on" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

See also Jump to heading #

• show profiling