Custom Segments

Monitor custom code blocks inside your application.

Thanks to Inspector you are able to put everything you want in the transactions timeline getting a real-time feedback about the execution of a code block inside your application.

By default Inspector will report database queries, jobs, emails sent and so on, but you are free to "wrap" some parts of your code that you consider relevant to create a more complete picture of what statements are impacting more in any execution cycle.

Short form

Just a few lines of code are needed:

inspector()->addSegment(function () {
// Your code block here...
}, '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 code performance.

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

A new segment in the timeline

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

Parameter

Required

Description

callback

YES

The code block you want keep under real-time monitoring

type

YES

This is the master category of your segments

label

NO

Human readable label or specific task name that will be showed inside the timeline in your Inspector dashboard. If it isn't provided type is used as label.

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 for a better timeline consultation.

  • mysql: master type

  • select * from table...: label

In this way you can mark toghether the statements related to an external service using something like exrernal-api as type parameter and use the specific url or task name as label for each statement of this type.

Get return

What you return from your callback will be returned back by addSegment method.

/**
* "$result" will contains the string "Hello"
*/
$result = inspector()->addSegment(function () {
// execute your code and return what you want to continue execution...
return "Hello!";
}, 'type', 'label');

Add contextual informations

If you need to report some context information, the new segment will be injected as callback parameter:

$result = inspector()->addSegment(function ($segment) {
// Your code block here...
$segment->addContext('payload', ['foo' => 'bar']);
return "Hello!";
}, 'external-api', 'The label');

Some ideas to use custom segments

Here are some scenarios where new segments can help you to anticipate bugs and bottlenecks:

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

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

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

Manually manage a segment

If you need more flexibility to wrap a more complex code block you can start and end a new segment manually.

You can use Inspector facade or inspector helper function:

// Inspector Facade
$segment = \Inspector::startSegment('type', 'label');
// Helper function
$segment = inspector()->startSegment('type', 'label');

Terminate a Segment

Each segment must be completed calling the end() method.

To allows Inspector to do its job it's mandatory to call the end() method on the segment instance. To be sure to accomplish this task you can use the finally statement in a try - catch block:

try {
$segment = inspector()->startSegment('activecampaign-api', 'Add Tag');
// Your code block here...
} catch(GuzzleException $exception) {
Inspector::reportException($exception);
} finally {
$segment->end();
}

This is the safest way to manually monitor a code block in your application.