README

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 <zzz@zzz.org.ua>

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.