A tracing and troubleshooting tool for PHP scripts.
Clone or download
Latest commit d400e41 Aug 3, 2017

README.md

phptrace

We have a new trace tool Molten, It's an OpenTracing supported tracer, for Distributed Tracing System.

我们开发了新的Trace工具 Molten, 它支持OpenTracing,用于分布式追踪系统。

Build Status

Readme in Chinese 中文

phptrace is a low-overhead tracing tool for PHP.

It can trace all PHP executing, function calls, request information during run-time. And provides features like Filter, Statistics, Current Status and so on.

It is very useful to locate blocking, heavy-load problems and debug in all environments, especially in production environments.

Features:

  • low-overhead, when extension loaded and trace is off
  • stable, running on Qihoo 360 and tested on mainstream frameworks
  • ease of use, view PHP run-time status without extension installation

Misc:

News We have build another interesting project pika. It's a NoSQL compatible with Redis protocol with huge storage space.

Install from source

  1. Extracting tarball

    tar -xf phptrace-{version}.tar.gz
    cd phptrace-{version}/extension
    
  2. Build

    PHP Extension

    {php_bin_dir}/phpize
    ./configure --with-php-config={php_bin_dir}/php-config
    make
    

    CLI Binary

    make cli
    
  3. Install & Configure

    Install PHP Extension, CLI Binary into PHP path

    make install-all
    

    Edit php.ini, add the following line. A reload is needed if PHP running on php-fpm mode.

    extension=trace.so
    
  4. Verify

    php -r 'for ($i = 0; $i < 20; $i++) usleep(50000);' &
    phptrace -p $!
    

    You should see something below if it works fine

    process attached
    [pid 3600]> cli php -
    [pid 3600]> {main}() called at [Command line code:1]
    [pid 3600]    > usleep(50000) called at [Command line code:1]
    [pid 3600]    < usleep(50000) = NULL called at [Command line code:1] ~ 0.051s 0.051s
    [pid 3600]    > usleep(50000) called at [Command line code:1]
    [pid 3600]    < usleep(50000) = NULL called at [Command line code:1] ~ 0.051s 0.051s
    [pid 3600]    > usleep(50000) called at [Command line code:1]
    [pid 3600]    < usleep(50000) = NULL called at [Command line code:1] ~ 0.051s 0.051s
    [pid 3600]    > usleep(50000) called at [Command line code:1]
    ...
    

Usage

Just try php example.php.

Command line options

  • trace trace running php process(default)
  • status display php process status
  • version show version
  • -p specify php process id ('all' to trace all processes)
  • -h show helper
  • -v same as version
  • -f filter data by type(url,function,class) and content
  • -l limit output count
  • --ptrace in status mode fetch data using ptrace

Trace executing

$ phptrace -p 3600

[pid 3600]    > Me->run() called at [example.php:57]
[pid 3600]        > Me->say("good night") called at [example.php:33]
[pid 3600]        < Me->say("good night") = NULL called at [example.php:33] ~ 0.000s 0.000s
[pid 3600]        > Me->sleep() called at [example.php:34]
[pid 3600]            > Me->say("sleeping...") called at [example.php:27]
[pid 3600]            < Me->say("sleeping...") = NULL called at [example.php:27] ~ 0.000s 0.000s
[pid 3600]            > sleep(2) called at [example.php:28]
[pid 3600]            < sleep(2) = 0 called at [example.php:28] ~ 2.000s 2.000s
[pid 3600]        < Me->sleep() = NULL called at [example.php:34] ~ 2.000s 0.000s
[pid 3600]        > Me->say("wake up") called at [example.php:35]
[pid 3600]        < Me->say("wake up") = NULL called at [example.php:35] ~ 0.000s 0.000s
[pid 3600]    < Me->run() = NULL called at [example.php:57] ~ 2.000s 0.000s

Print current status

$ phptrace status -p 3600

------------------------------- Status --------------------------------
PHP Version:       7.0.16
SAPI:              cli
script:            example.php
elapse:            26.958s
------------------------------ Arguments ------------------------------
$0
------------------------------ Backtrace ------------------------------
#0  fgets() called at [example.php:53]
#1  {main}() called at [example.php:53]

Tracing with filter of url/class/function

$ phptrace -p 3600 -f type=class,content=Me

[pid 3600]> Me->run() called at [example.php:57]
[pid 3600]> Me->say("good night") called at [example.php:33]
[pid 3600]< Me->say("good night") = NULL called at [example.php:33] ~ 0.000s 0.000s
[pid 3600]> Me->sleep() called at [example.php:34]
[pid 3600]> Me->say("sleeping...") called at [example.php:27]
[pid 3600]< Me->say("sleeping...") = NULL called at [example.php:27] ~ 0.000s 0.000s
[pid 3600]< Me->sleep() = NULL called at [example.php:34] ~ 2.000s 2.000s
[pid 3600]> Me->say("wake up") called at [example.php:35]
[pid 3600]< Me->say("wake up") = NULL called at [example.php:35] ~ 0.000s 0.000s
[pid 3600]< Me->run() = NULL called at [example.php:57] ~ 2.001s 0.000s

Limit frame/URL display times

$ phptrace -p 3600 -l 2

[pid 3600]    > Me->run() called at [example.php:57]
[pid 3600]        > Me->say("good night") called at [example.php:33]
[pid 3600]        < Me->say("good night") = NULL called at [example.php:33] ~ 0.000s 0.000s
[pid 3600]        > Me->sleep() called at [example.php:34]
[pid 3600]            > Me->say("sleeping...") called at [example.php:27]
[pid 3600]            < Me->say("sleeping...") = NULL called at [example.php:27] ~ 0.000s 0.000s

Contributing

Welcome developers who willing to make PHP environment better.

If you are interested but have no idea about how to starting, please try these below:

License

This project is released under the Apache 2.0 License.