ngx_trace

ngx_trace copied to clipboard

NAME tracerx.pl - runtime call tracer for nginx

DESCRIPTION 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.

INSTALLATION 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 tracerx.pl:

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

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

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

SYNOPSIS tracerx.pl [OPTIONS] COMMAND [ARGS]

OPTIONS -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

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

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

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

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

AUTHOR Alexandr Gomoliako [email protected]

LICENSE 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.