Transactions

All start with a transaction. Transaction represent an execution cycle and it can contains one or hundreds of segments.

It should be started as soon as possible in your application to better represent the time your script takes to fulfill the request.

Typically the transaction should be started in the entry point of your application e.g. index.php

/*
 * A transaction should start as soon as possible, 
 * typically in the "index.php" file of your application.
 */
$pathInfo = explode('?', $_SERVER["REQUEST_URI"]);
$path = array_shift($pathInfo);
​
$inspector->startTransaction($path);
​
​
// Continue with the script...

Set transaction result

When your application return a response back to the client you can setup the result of the transaction like the HTTP code:

$inspector->currentTransaction()->setResult(200);

Add Context

Each transaction can be enriched with additional information to have a more complete picture of the process execution context.

You can use the addCotext method to attach new tabs to the current transaction:

$inspector->currentTransaction()->addContext('label', ['foo' => 'bar']);

Contextual information will be reported as additional tabs in the transaction view. This code example creates a new tab "Label" in the transaction details as showed in the image below:

Segments

Transactions contains segments that represents the tasks executed during the current execution cycle.

Thanks to Inspector you are able to put everything you want in your transaction's timeline getting a real-time feedback about the execution of a code block inside your app:

• DB queries

• Http call to external services (webhooks, integration, etc.)

• Functions that deal with files (pdf, excel, images)

• Data manipulation processes (import/export, data aggregation, etc.)

and anything else you think is relevant.

Add Segments (short form)

This is the most easy way to wrap a code block with a monitor:

$inspector->addSegment(function () {
    
    // Code block that you want add to the transaction timeline.
    // DB queries, http calls, etc.
    
}, 'type', 'label');

The code block inside the callback will be transparently executed, and your script will continue its execution normally. Inspector will works under the hood to profile execution performance.

Here is an example of how you'll be able to explore your code performance execution in your dashboard thanks to the timeline:

As showed in the example above a new segment is built with two input parameters:

Think about how database queries is reported. That's one master category like mysql but each query has its own custom label that simply is an extract of the sql code executed.

• mysql: master type

• select * from table: task name

In this way you can mark toghether the statements related to the same topic or service, using something like mysql as type parameter and use the specific query string or task name as label for each statements of this type.

Add Segments (extended code)

You can use startSegment() method on the Inspector instance to manually control the monitoring of the code block:

/* 
 * Create a new "segment" that will be automatically attached 
 * to the current transaction.
 */
$segment = $inspector->startSegment('type', 'label');
​
try {
​
    /*
     * Write here your code block
     */
​
} catch(UnauthorizedException $exception) {
​
    /*
     * Report the exception to Inspector for diagnosis purpose.
     */
    $inspector->reportException($exception);
    
} finally {
    /*
     * Close the code block with end() method to stop segment monitoring.
     */
    $segment->end();
}

As you can see in the example above we use try/catch/finally to be sure that your code block is monitored in a consistent way.

Or you can use addSegment() that performs this strategy for you as seen above:

$inspector->addSegment(function () {
    
    /*
     * Write here your code block
     */
     
}, 'type', 'label');

Segments tips and tricks

It may happen that you aren't able to wrap directly the statement to trace performance, so it might be useful to add a segment after the task has been executed.

In this case you can create the segment manually passing the start time in the start() method, and the duration in the end() method, as shown in the example below:

/*
 * Http call to an external url could be perfromed with following result.
 */
$url = 'https://www.inspector.dev';
$duration_ms = 10; // Duration in milliseconds
​
/** 
 * -----------------------------------------
 * Create the segment manually setting timing information.
 * -----------------------------------------
 */
​
// convert duration in seconds
$timespamp_start = microtime(true) - ($duration_ms/1000) 
​
$inspector->startSegment('api', $url)
    ->start($timespamp_start)
    ->end($duration_ms);

Make Inspector available in your application globally

To be free to add new segments, or interact with the current transaction you need a way to make the Inspector instance available everywhere in your application.

Use an IoC container like PHP-DI is a common way to distribute internal services inside an application. If your application has one, or implement other similar strategies, you could put the Inspector instance in the registry:

$container->set('inspector', $inspector);

in order to use it later inside your application to add segments:

class UserController extends BaseController
{
    /**
     * @var \Inspector\Inspector
     */
    protected $inspector;
    
    /**
     * UserController constructor.
     */
    public function __construct()
    {
        // Get Inspector instance from the container.
        $this->inspector = $container->get('inspector');
    }
    
    /**
     * Do something.
     */
    public function action()
    {
        // Monitor a piece of code and return the result back to the client.
        return $this->inspector->addSegment(function () {
            
            return $this->someService->doSomething();
        
        }, 'someService', 'doSomething');
    }
}