Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/krakjoe/tombs

Detect unused code in production
https://github.com/krakjoe/tombs

Last synced: 3 months ago
JSON representation

Detect unused code in production

Awesome Lists containing this project

README 

        
# Tombs



[![Build Status](https://travis-ci.com/krakjoe/tombs.svg?branch=develop)](https://travis-ci.com/krakjoe/tombs)



Tombs is a Zend extension for PHP that provides a way to track if a piece of code is actually invoked. This concept is called [Tombstones](https://www.youtube.com/watch?v=29UXzfQWOhQ).  

It uses Zend hooks to populate a graveyard at runtime, wherein a tomb is representative of every function that Zend has constructed. As Zend executes, functions that are used

have their tombs vacated. When the programmer connects to the Tombs socket, a background thread will send populated tombs without interrupting the execution of your application.



# Requirements



  - PHP7.1+

  - unix



*Note: Windows is unsupported, Tombs targets production ...*



# How To



Here is a quick run down of how to use Tombs ...



## To build Tombs:



  - `phpize`

  - `./configure [--with-php-config=/path/to/php-config]`

  - `make`

  - `make install`



## To load Tombs:



Tombs must be loaded as a Zend extension:



  - add `zend_extension=tombs.so` to the target configuration



`php -v` should show something like:

    ...

    with Tombs vX.X.X-X, Copyright (c) 2019, by krakjoe



## To configure Tombs:



The following configuration directives are available:



| Name           | Default                   | Purpose                                                        |

|:---------------|:--------------------------|:---------------------------------------------------------------|

|tombs.slots     |`10000`                    | Set to (a number greater than) the maximum number of functions |

|tombs.strings   |`32M`                      | Set size of string buffer (supports suffixes, be generous)     |

|tombs.socket    |`zend.tombs.socket`        | Set path to socket, setting to 0 disables socket               |

|tombs.dump      |`0`                        | Set to a file descriptor for dump on shutdown                  |

|tombs.namespace | N/A                       | Set to restrict recording to a namespace                       |

|tombs.graveyard_format | `json`             | Format of graveyard: `json`, `function`                        |



## To communicate with Tombs:



Tombs can be configured to communicate via a unix or TCP socket, the following are valid examples:



  - `unix://zend.tombs.socket`

  - `unix:///var/run/zend.tombs.socket`

  - `tcp://127.0.0.1:8010`

  - `tcp://localhost:8010`



*Note: If the scheme is omitted, the scheme is assumed to be unix*



Tombs will send each populated tomb as a json encoded packet, with one tomb per line, with the following format, prettified for readability (tombs.graveyard_format=`json`):



    {

        "location": {

            "file":  "004.php",

            "start": 5,

            "end":   6

        },

        "scope": "Foo",

        "function": "bar"

    }



*Note: The `scope` element will only be present for methods*



### Output format "function"



For more compact output use tombs.graveyard_format=`function`:



    Foo::bar



## Internals



On startup (MINIT) Tombs maps three regions of memory:



  - Markers   - a pointer to zend_bool in the reserved region of every op array

  - Strings   - region of memory for copying persistent strings: file names, class names, and function names

  - Graveyard - a tomb for each possible function



All memory is shared among forks and threads, and Tombs uses atomics, for maximum glory.



Should mapping fail, because there isn't enough memory for example, Tombs will not stop the process from starting up but will only output a warning. Should mapping succeed, the configured socket will be opened. Should opening the socket fail, Tombs will be shutdown immediately but allow the process to continue.



### Markers



The op array constructor hook for zend extensions is used to set reserved memory to a mapped pointer to zend_bool. If the atomic set succeeds, the hook then populates a tomb in the graveyard.



### Strings



When Tombs needs to reference a string, it is copied from its current location and into mapped memory. These copied strings are reused, and are indepdenent of the request cycle of PHP, and opcache.



Once allocated, a string is never free'd. We must be sure that even after the request has ended or opcache restarted, the string is available. We must also be sure that should there be a client connected to the socket we do not free memory that is being written to the socket.



### Graveyard



The executor function that Tombs installs updates the value of the marker when the function is entered. If the atomic set succeeds, the tomb is vacated.



## TODO



  - Tests

  - CI