Merge pull request #20 from BitOne/frame_label

Adding frame and root information on items.

Author: BitOne

CHANGELOG.md

@@ -1,3 +1,7 @@
+2016-03-15 Benoit Jacquemont <[email protected]>
+* Added frame and symbol information
+* Added analyzers to find path that kept references
+
 2016-01-26 Benoit Jacquemont <[email protected]>
 * Added the object handle to uniquely identify objects
 
@@ -7,7 +11,5 @@
 2014-02-08 Benoit Jacquemont <[email protected]>
 * Migrating from Google Code to GitHub
 
-
 2011-01-16 Benoit Jacquemont <[email protected]>
-
 * Extension creation.

README.md

@@ -2,7 +2,7 @@ MEMINFO
 =======
 PHP Meminfo is a PHP extension that gives you insights on the PHP memory content.
 
-Its main goal is to help you understand memory leaks, but by looking at data present in memory, you can better understand your application behaviour.
+Its main goal is to help you understand memory leaks: by looking at data present in memory, you can better understand your application behaviour.
 
 One of the main source of inspiration for this tool is the Java jmap tool with the -histo option (see `man jmap`).
 
@@ -13,6 +13,7 @@ Compiled and tested on:
  - PHP 5.4.4 (Debian 7)
  - PHP 5.5.8 (Ubuntu 12.04 LTS)
  - PHP 5.5.20 (CentOS 7)
+ - PHP 5.6.17 (Debian 8)
 
 Compilation instructions
 ------------------------
@@ -24,7 +25,7 @@ $ apt-get install php5-dev
 Once you have this command, follow this steps:
 
 ## Compilation
-From the root of the extension directory:
+From the root of the `extension/` directory:
 
 ```bash
 $ phpize
@@ -40,31 +41,18 @@ Add the following line to your `php.ini`:
 extension=meminfo.so
 ```
 
-Usage
------
-All meminfo functions take a stream handle as a parameter. It allows you to specify a file, as well as to use standard output with the `php://stdout` stream.
-
-## Exploring Memory usage
-The provided user interface allows you to explore the content of your memory. It will show you the items instanciated, the dependencies between items and the size of each of them.
-
-### Summary Screen
-The main screen lists the top memory consumers, ordered by their total size.
-![summary screen](doc/images/ui_summary.png)
-
-### Item details Screen
-Clicking on an item brings you to the Item Details Screen.
-![summary screen](doc/images/ui_item_details.png)
-
-On this screen, you will see 5 parts:
- - title
-Item type (object, array, string, boolean, etc...) and its pointer address in memory at the time of the data extraction.
-This memory address is used as the unique identifier of the item
+Installing analyzers
+--------------------
+Analyzers allow to analyze a memory dump (see below).
 
- - Information
-Small summary on the item itself, like the class name in case of object and memory size information.
+```bash
+$ cd analyzers
+$ composer update
+```
 
-### How memory size is computed
-See [the dedicated documentation](/doc/memory_calculation.md).
+Usage
+-----
+All meminfo functions take a stream handle as a parameter. It allows you to specify a file (ex `fopen('/tmp/file.txt', 'w')`, as well as to use standard output with the `php://stdout` stream.
 
 ## Object instances count per class
 Display the number of instances per class, ordered descending. Very useful to identify the content of a memory leak.
@@ -73,7 +61,7 @@ Display the number of instances per class, ordered descending. Very useful to id
     meminfo_objects_summary(fopen('php://stdout','w'));
 ```
 
-The result will provide something similar to the following example (generated at the end of the Symfony2 console launch)
+The result will provide something similar to the following example generated at the end of a Symfony2 console launch:
 
 ```
     Instances count by class:
@@ -98,6 +86,49 @@ The `examples/` directory at the root of the repository contains more detailed e
     $ php examples/objects_summary.php
 ```
 
+## Memory state dump
+This feature allow to dump the list of items present in memory at the time of the function execution. Each memory items (string, boolean, objects, array, etc...) are dumped in a JSON format, with the following information:
+ - in memory address
+ - type (object, array, int, string, ...)
+ - class (only for objects)
+ - object handle (only for objects.
+ - self size (without the size of the linked objects)
+ - is_root (tells if the item is directly linked to a variable)
+ - symbol name (variable name, if linked to a variable)
+ - execution frame (name of the method where the variable has been declared)
+ - children: list of linked items with the key value if array or property name if object and the item address in memory
+
+### Analyzing a memory dump
+The analyzer is available from the `analyzer/` directory. It will be invoked with:
+``` bash
+$ bin/analyzer
+```
+
+#### Querying a memory dump
+The `query` command on the analyzer allows you to filter out some items from a memory dump. The `-f` option can be used several times, effectively *anding* the filters. The supported operators are exact match `=` and regexp match `~`.
+
+The `-v`option display all the information of the items found.
+
+##### Examples
+ - finding array that are not directly linked to a variable
+```bash
+$ bin/analyzer query -f "type=array" -f "is_root=0" my_dump_file.json
+```
+ - finding objects whose class name contains `Product` and linked to a variable
+```bash
+$ bin/analyzer query -f "class~Product" -f "is_root=1" -v my_dump_file.json
+```
+
+#### Finding out why an object has not been removed from memory
+When you are tracking down a memory leak, it's very interesting to understand why an object is still in memory.
+
+The analyzer provides the `ref-path` command that load the memory dump as a graph in memory and findout all paths linking an item to a root (a variable define in an execution frame).
+
+Without the `-v` option, the output will contains only item memory adress and key/property name. Adding the `-v` option will display all the information of the linked items.
+
+```bash
+$ bin/analyzer ref-path my_dump_file.json 0x12345678
+```
 
 ## List of items in memory
 Provides a list of items in memory (objects, arrays, string, etc.) with their sizes.

analyzer/.gitignore

@@ -0,0 +1,2 @@
+/vendor/
+/composer.lock

analyzer/bin/analyzer

@@ -0,0 +1,7 @@
+#!/usr/bin/env php
+<?php
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+$analyzer = new BitOne\PhpMemInfo\Console\Application();
+$analyzer->run();

analyzer/composer.json

@@ -0,0 +1,21 @@
+{
+    "name": "bitone/php-meminfo-analyzer",
+    "license": "MIT",
+    "type": "project",
+    "description": "Tools to analyze meminfo dump files",
+    "require": {
+        "symfony/console" : "^2.8.3",
+        "symfony/filesystem" : "^2.8.3",
+        "symfony/serializer" : "^2.8.3",
+        "clue/graph": "^0.9.0",
+        "graphp/algorithms": "^0.8.1"
+    },
+    "autoload": {
+        "psr-4": { "": "src/" }
+    },
+    "require-dev": {
+        "squizlabs/php_codesniffer": "^2.5",
+        "phpspec/phpspec": "^2.4",
+        "fabpot/php-cs-fixer": "^1.11"
+    }
+}

analyzer/src/BitOne/PhpMemInfo/Analyzer/GraphBrowser.php

@@ -0,0 +1,120 @@
+<?php
+
+namespace BitOne\PhpMemInfo\Analyzer;
+
+use Fhaculty\Graph\Graph;
+use Graphp\Algorithms\ShortestPath\BreadthFirst;
+
+/**
+ * Analyzer to load the data as a graph and analyze the graph.
+ *
+ * @author    Benoit Jacquemont <[email protected]>
+ * @copyright 2016 Benoit Jacquemont
+ * @license   http://opensource.org/licenses/MIT MIT
+ */
+class GraphBrowser
+{
+    /** @var array */
+    protected $items;
+
+    /** @var Graph */
+    protected $graph;
+
+    /**
+     * @param array $items
+     */
+    public function __construct(array $items)
+    {
+        $this->items = $items;
+    }
+
+    /**
+     * Find all references coming from roots.
+     *
+     * @param string $itemid
+     *
+     * @return array
+     */
+    public function findReferencePaths($itemId)
+    {
+        $graph = $this->getGraph();
+
+        $to = $graph->getVertex($itemId);
+
+        $paths = [];
+
+        $mapSearch = new BreadthFirst($to);
+
+        $map = $mapSearch->getEdgesMap();
+
+        foreach ($map as $endVertexId => $path) {
+            $endVertex = $graph->getVertex($endVertexId);
+            $endVertexData = $endVertex->getAttribute('data');
+
+            if ($endVertexData['is_root']) {
+                $paths[$endVertexId] = $path;
+            }
+        }
+
+        if ($to->getAttribute('data')['is_root']) {
+            $edge = $to->createEdgeTo($to);
+            $edge->setAttribute('name', '<self>');
+            $paths[$to->getId()] = [$edge];
+        }
+
+        return $paths;
+    }
+
+    /**
+     * Build the graph if necessary and return it.
+     *
+     * @param Graph
+     */
+    protected function getGraph()
+    {
+        if (null === $this->graph) {
+            $this->buildGraph();
+        }
+
+        return $this->graph;
+    }
+
+    /**
+     * Build the graph from the items.
+     */
+    protected function buildGraph()
+    {
+        $this->graph = new Graph();
+        $this->createVertices();
+        $this->createEdges();
+    }
+
+    /**
+     * Create vertices on the graph from items.
+     */
+    protected function createVertices()
+    {
+        foreach ($this->items as $itemId => $itemData) {
+            $vertex = $this->graph->createVertex($itemId);
+            $vertex->setAttribute('data', $itemData);
+        }
+    }
+
+    /**
+     * Create edges on the graph between vertices.
+     */
+    protected function createEdges()
+    {
+        foreach ($this->items as $itemId => $itemData) {
+            if (isset($itemData['children'])) {
+                $children = $itemData['children'];
+                $vertex = $this->graph->getVertex($itemId);
+
+                foreach ($children as $link => $child) {
+                    $childVertex = $this->graph->getVertex($child);
+                    $childVertex->createEdgeTo($vertex)->setAttribute('name', $link);
+                }
+            }
+        }
+    }
+}

analyzer/src/BitOne/PhpMemInfo/Analyzer/QueryExecutor.php

@@ -0,0 +1,95 @@
+<?php
+
+namespace BitOne\PhpMemInfo\Analyzer;
+
+/**
+ * Analyzer to do simple query on the data.
+ *
+ * @author    Benoit Jacquemont <[email protected]>
+ * @copyright 2016 Benoit Jacquemont
+ * @license   http://opensource.org/licenses/MIT MIT
+ */
+class QueryExecutor
+{
+    /** @var array */
+    protected $items;
+
+    /**
+     * @param array $items
+     */
+    public function __construct(array $items)
+    {
+        $this->items = $items;
+
+        foreach ($this->items as $itemid => &$itemData) {
+            $itemData['id'] = $itemid;
+        }
+    }
+
+    /**
+     * Query the existing items.
+     *
+     * @param array $filters
+     * @param int   $limit
+     *
+     * @return array
+     */
+    public function executeQuery(array $filters, $limit = 10)
+    {
+        $results = [];
+
+        foreach ($this->items as $itemId => $itemData) {
+            if ($this->matches($itemData, $filters)) {
+                $results[$itemId] = $itemData;
+            }
+
+            if (count($results) >= $limit) {
+                break;
+            }
+        }
+
+        return $results;
+    }
+
+    /**
+     * Apply filters on an item and return if it is a match or not.
+     *
+     * @param array $item
+     * @param array $filters
+     *
+     * @return bool
+     */
+    public function matches(array $item, array $filters)
+    {
+        $matches = true;
+
+        foreach ($filters as $attribute => $filter) {
+            $operator = $filter['operator'];
+            $value = $filter['value'];
+
+            if (!isset($item[$attribute])) {
+                $matches = false;
+            } else {
+                switch ($operator) {
+                    case '=':
+                        $matches = ($item[$attribute] == $value);
+                        break;
+                    case '~':
+                        $pattern = sprintf('#%s#', $value);
+                        $regexpResult = preg_match($pattern, $item[$attribute]);
+                        if (false === $regexpResult) {
+                            throw new \InvalidArgumentException("Provided regexp is invalid: $value");
+                        }
+                        $matches = (1 === $regexpResult);
+                        break;
+                }
+            }
+
+            if (!$matches) {
+                break;
+            }
+        }
+
+        return $matches;
+    }
+}