README

Before moving on, please consider giving us a GitHub star ⭐️. Thank you!

Code Execution Monitoring, built for PHP developers.

Requirements

• PHP >= ^8.1

Install

Install the latest version by:

composer require inspector-apm/inspector-php

Use

To start sending data to Inspector you need an Ingestion Key to create an instance of the Configuration class. You can obtain INSPECTOR_API_KEY creating a new project in your Inspector dashboard.

use Inspector\Inspector;
use Inspector\Configuration;

$configuration = new Configuration('YOUR_INGESTION_KEY');
$inspector = new Inspector($configuration);

All start with a transaction. Transaction represents an execution cycle, and it can contain one or hundred of segments:

// Start an execution cycle with a transaction
$inspector->startTransaction($_SERVER['PATH_INFO']);

Use addSegment method to monitor a code block in your transaction:

$result = $inspector->addSegment(function ($segment) {
    // Do something here...
	return "Hello World!";
}, 'my-process');

echo $result; // this will print "Hello World!"

Inspector will monitor your code execution in real time alerting you if something goes wrong.

Custom Transport

You can also set up a custom transport class to transfer monitoring data from your server to Inspector in a personalized way.

The transport class needs to implement \Inspector\Transports\TransportInterface:

class CustomTransport implements \Inspector\Transports\TransportInterface
{
    protected $configuration;

    protected $queue = [];

    public function __constructor($configuration)
    {
        $this->configuration = $configuration;
    }

    public function addEntry(\Inspector\Models\Model $entry)
    {
        // Add an \Inspector\Models\Model entry in the queue.
        $this->queue[] = $entry;
    }

    public function flush()
    {
        // Performs data transfer.
        $handle = curl_init('https://ingest.inspector.dev');
        curl_setopt($handle, CURLOPT_POST, 1);
        curl_setopt($handle, CURLOPT_HTTPHEADER, [
            'X-Inspector-Key: xxxxxxxxxxxx',
            'Content-Type: application/json',
            'Accept: application/json',
        ]);
        curl_setopt($handle, CURLOPT_POSTFIELDS, json_encode($this->queue));
        curl_exec($handle);
        curl_close($handle);
    }
}

Then you can set the new transport in the Inspector instance using a callback that will receive the current configuration state as parameter.

$inspector->setTransport(function (\Inspector\Configuration $configuration) {
    return new CustomTransport($configuration);
});

Concurrent & Async Tasks

When monitoring concurrent or async tasks (e.g. using Fibers, ReactPHP, Amp, or pcntl_fork), a single segment stack would produce incorrect parent-child relationships because tasks interleave on the shared stack. Use fork() to create an independent Scope for each concurrent task:

$inspector->startTransaction('request');
$controller = $inspector->startSegment('controller', 'handle');

// Fork independent scopes — both capture $controller as base parent
$scopeA = $inspector->fork();
$scopeB = $inspector->fork();

// Pass $scopeA and $scopeB to your async tasks
// Task A (e.g. in a Fiber or child process)
$scopeA->startSegment('http', 'api-call-A')->end();

// Task B (running concurrently)
$scopeB->startSegment('http', 'api-call-B')->end();

// Segments in each scope maintain their own nesting hierarchy
$nested = $scopeA->startSegment('database', 'query');
// parent_hash points to api-call-A ✓
$nested->end();

Each Scope has its own segment stack, so interleaving tasks never corrupt the parent-child hierarchy. Scopes also support addSegment(), fork() (for nested forking), and getOpenSegments().

Chek out the official documentation

Agentic Integration

You can connect the Inspector library documentation to your coding assistant as a Model Context Protocol (MCP) server.

It makes it easy for tools like Claude Code, Cursor, and VS Code extensions reliably understand what Inspector client library can do, its configurations, how to use it.

AI Assisted Integration

Contributing

We encourage you to contribute to Inspector! Please check out the Contribution Guidelines about how to proceed. Join us!

LICENSE

This package is licensed under the MIT license.