Introduction

May 1, 2026 · View on GitHub

Note

This document is the deep-dive for the JSON + jq workflow. If you're new to reli's memory profiling, most users should start with:

memory-dump.md — dump a target's memory efficiently (short stop time; inspector:memory:dump)
memory-report.md — automated findings report (inspector:memory:report, inspector:memory:compare)
rmem-explore-and-serve.md — interactive TUI over a snapshot (rmem:explore)

Come back here when you want to hand-query the JSON with jq, understand the on-disk structure, or integrate with other tooling.

This page documents inspector:memory's default JSON output — the original memory-profiling entry point in reli — and the jq-based analysis style that grew up around it. inspector:memory itself still works exactly as described below; what has changed since its first iteration is the recommended way to use its output:

For interactive exploration and prioritised findings, reach for the captured-snapshot pipeline (memory-dump.md → rmem-explore-and-serve.md / memory-report.md). It stops the target for much less time and ships with purpose-built analysers, all built around the .rmem format.
Read this page when you need to hand-query snapshots with jq, understand the on-disk JSON structure, integrate with other tooling that expects JSON, or maintain pipelines that predate the .rmem / report workflow.

The canonical invocation:

reli inspector:memory -p <pid_of_target_process>

By default this writes the analysed snapshot as JSON on stdout — that's what the rest of this document covers. The same command also accepts other output formats, and for any analysis-tool-driven workflow -f rmem (the .rmem format) is the fastest and is what every analyser (rmem:explore, rmem:serve, rmem:mcp, inspector:memory:report, inspector:memory:compare) reads natively. Other accepted formats: -f sqlite3 (for SQL tooling — see memory-profiler-database.md), -f report (direct findings report — see memory-report.md), -f mysql / -f postgresql (stream into a remote database).

When -f is omitted, the format is inferred from the -o extension: .rmem selects rmem, .sqlite3 / .sqlite / .db select sqlite3, anything else (or no -o) falls back to json. So inspector:memory -p <pid> -o snap.rmem is equivalent to passing -f rmem explicitly.

You can use this mode to analyze the memory usage of the target process — for finding memory bottlenecks or memory leaks. For example, you can see statistics such as whether strings, arrays or objects are particularly dominant in a script's memory usage, or contextual information such as where certain local variables in a given call frame are referenced from elsewhere, and the actual values held by certain memory areas.

The functionality of this mode is similar to php-meminfo, but works in the phpspy-ish way: it captures the memory contents of the target from outside the process, analyses them with knowledge of the PHP VM's internal structures, then dumps the whole analysis. Target programs don't need any modifications and don't need to load a specific extension.

Requirements

See Getting started § Requirements for the canonical runtime / target requirements (PHP version, NTS/ZTS support, platform notes). No command-specific overrides apply to inspector:memory.

Installation

See Getting started § Install for the recommended install paths (Docker wrapper, Composer, Git).

Options

./reli inspector:memory --help is the source of truth for the full flag list and defaults. The flags you most often reach for:

-p, --pid <PID> — target process id (or pass a cmd after -- to spawn one)
-f, --output-format <fmt> — json (default), sqlite3, rmem (.rmem), report, report-json, mysql, postgresql. rmem / sqlite3 / mysql / postgresql require -o (or --db-*).
-o, --output <path> — write to a file instead of stdout
--pretty-print — pretty-print the JSON output (default: off)
--stop-process / --no-stop-process — SIGSTOP the target during the read (default: on)
--db-host / --db-port / --db-name / --db-user / --db-password — destination for mysql / postgresql formats
--memory-limit-error-file / --memory-limit-error-line / --memory-limit-error-max-depth — focus analysis on a specific memory_limit site (used by inspector:sidecar)
--php-regex / --libpthread-regex / --zts-globals-regex / --php-version / --php-path / --libpthread-path — target binary discovery and version overrides (rarely needed; ZTS / chroot / unusual binary names)
--no-cache — bypass the binary analysis cache for this run
--memory-limit <size> — ini_set('memory_limit', ...) for the analyser itself, not the target

Usage

Caution

Don't upload the output of this command to the internet, because it can contain sensitive information of the target script!!!

This tool can be used like this.

sudo ./reli inspector:memory --pretty-print -p <pid_of_target_process> >memory_analyzed.json

The analysis takes seconds in many case. During the analysis, the target process is stopped by default.

And the output is like below. The target process is psalm in this example.

{
    "summary": [
        {
            "zend_mm_heap_total": 153092096,
            "zend_mm_heap_usage": 126947784,
            "zend_mm_chunk_total": 153092096,
            "zend_mm_chunk_usage": 126947784,
            "zend_mm_huge_total": 0,
            "zend_mm_huge_usage": 0,
            "vm_stack_total": 262144,
            "vm_stack_usage": 8720,
            "compiler_arena_total": 1900544,
            "compiler_arena_usage": 1791992,
            "possible_allocation_overhead_total": 10196000,
            "possible_array_overhead_total": 21284000,
            "memory_get_usage": 129053816,
            "memory_get_real_usage": 153092096,
            "cached_chunks_size": 0,
            "chunks_count": 73,
            "peak_chunks_count": 73,
            "cached_chunks_count": 0,
            "last_chunks_delete_boundary": 0,
            "last_chunks_delete_count": 0,
            "chunks_total_free_bytes": 552960,
            "chunks_mostly_empty_count": 0,
            "heap_memory_analyzed_percentage": 98.36809784842008,
            "php_version": "v82",
            "analyzer": "reli 0.12.0"
        }
    ],
    "location_types_summary": {
        "ZendObjectMemoryLocation": {
            "count": 124341,
            "memory_usage": 45245784
        },
        "ZendArrayTableOverheadMemoryLocation": {
            "count": 108548,
            "memory_usage": 21204736
        },
        "ZendArrayTableMemoryLocation": {
            "count": 109462,
            "memory_usage": 17964240
        },
        "ZendStringMemoryLocation": {
            "count": 242532,
            "memory_usage": 16149456
        },
<--- snip --->
    "class_objects_summary": {
        "Psalm\\CodeLocation": {
            "count": 32875,
            "memory_usage": 13413000
        },
        "Psalm\\Type\\Union": {
            "count": 24924,
            "memory_usage": 12960480
        },
        "Psalm\\Internal\\MethodIdentifier": {
            "count": 8838,
            "memory_usage": 636336
        },
<--- snip --->
    "context": {
        "call_frames": {
            "#node_id": 0,
            "#type": "CallFramesContext",
            "#count": 4,
            "0": {
                "#node_id": 1,
                "#type": "CallFrameContext",
                "function_name": "Psalm\\IssueBuffer::finish",
                "local_variables": {
                    "#node_id": 2,
                    "#type": "CallFrameVariableTableContext",
                    "project_analyzer": {
                        "#node_id": 3,
                        "#type": "ObjectContext",
                        "#locations": [
                            {
                                "address": 139957204265152,
                                "size": 424,
                                "refcount": 3,
                                "type_info": 3221319688,
                                "class_name": "Psalm\\Internal\\Analyzer\\ProjectAnalyzer"
                            }
                        ],
                        "object_handlers": {
                            "#node_id": 4,
                            "#type": "ObjectHandlersContext",
                            "#locations": [
                                {
                                    "address": 93902816133472,
                                    "size": 200
                                }
                            ]
                        },
                        "object_properties": {
                            "#node_id": 5,
                            "#type": "ObjectPropertiesContext",
                            "#count": 24,
                            "config": {
                                "#node_id": 6,
                                "#type": "ObjectContext",
                                "#locations": [
                                    {
                                        "address": 139957201996800,
                                        "size": 1544,
                                        "refcount": 7,
                                        "type_info": 3221239816,
                                        "class_name": "Psalm\\Config"
                                    }
                                ],
                                "object_handlers": {
                                    "#reference_node_id": 4
                                },
<--- snip --->
...

A quick tour of each part of the output

ZendMM allocates 153,092,096 byte of chunks in total
126,947,784 bytes of them are located by this tool
If the target process calls memory_get_usage(false) at this moment, the return value would be 129,053,816
So 98.36809784842008% of areas reported by memory_get_usage() is analyzed
The kind of the top most memory area is the locations for zend_object, which corresponding to the PHP objects in the target process
- The number of objects is 124,341, and the total analyzed size of them is 45,245,784 bytes
The class with the most number of instances is Psalm\CodeLocation
- The number of instances is 32,875, and the total analyzed size of them is 13,413,000 bytes
The "context" field can be used to find out which areas in the script are used in what context. For example, the executing function at this moment is Psalm\IssueBuffer::finish(). Its local variables contain $project_analyzer, which is an instance of Psalm\Internal\Analyzer\ProjectAnalyzer. And you can extract all references to the same instance with jq.

$ cat memory_analized.json | jq 'path(..|objects|select(."#reference_node_id"==3 or ."#node_id"==3))|join(".")'
"context.call_frames.0.local_variables.project_analyzer"
"context.call_frames.1.local_variables.project_analyzer"
"context.class_table.psalm\\internal\\analyzer\\projectanalyzer.static_properties.instance"
"context.objects_store.17"

Useful snippets for analyzing the output