runtime call tracer for nginx
Perl C Shell


NAME - runtime call tracer for nginx

    Simple runtime call tracer. Uses profiling instrument functions and
    symbol table to record and print calls. Useful for complex problems and
    learning nginx internals.

    Something similar can be done with gdb and lots of breakpoints, but
    annoyingly slowly.

    Download and compile nginx with "ngx_trace" module:

        % ./configure --add-module=/path/to/ngx_trace  && make

    This will enable debug symbols and instrument functions for gcc. Next,
    make sure binary works and can print its own version:

        % ./objs/nginx -V

    Prepare environment to run nginx from:

        % mkdir mynginx
        % mkdir mynginx/logs
        % cp -r conf mynginx/
        % cp -r html mynginx/

    Edit your new "nginx.conf", make sure it runs single process in
    foreground and uses ports that don't require privileges to bind to:

        daemon off;
        master_process off;
        http {
            server {
                listen 5678;

    I find it useful to print errors to stderr as well:

        error_log /dev/stderr debug;

    And now you can start playing with

        % /path/to/ngx_trace/ ./objs/nginx -p mynginx

    More useful: prints filename, line number, calls within http, event
    modules, ngx_connection.c and ignores access.log messages:

        % ./ -l -f 'core/ngx_conn|http/|event/' \
                       -i 'get_indexed_variable|_log_' \
                       ./objs/nginx -p mynginx


    -l      print filename, line number saved from "nm -l" and time offset

    -s PATTERN
            print calls matching specified regex pattern only

    -c PATTERN
            print calls matching specified regex pattern in yellow color

    -i PATTERN
            ignore calls matching regex pattern

    -f PATTERN
            print calls if filename matches pattern

    -t      show how much time it took to run each function in microseconds

    -u      show addresses of unknown functions

    Show all calls within src/http and src/event modules:

        % ./ -f 'src/http|src/event' ./objs/nginx -p mynginx

    Show calls within http and ignore all calls containing _log_ in function

        % ./ -f 'src/http' -i '_log_' ./objs/nginx -p mynginx

    Alexandr Gomoliako <>

    Copyright 2011 Alexandr Gomoliako. All rights reserved.

    This module is free software. It may be used, redistributed and/or
    modified under the same terms as Perl itself.