Inspector logo

Custom Segments

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

$segment = Inspector::startSegment('http');

// Your statement here...

$segment->end();

This will produce a new segment in the timeline:

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 executed during an application transaction.

Let me show you how simple it is.

How to create a segment

{info} Consider to install our composer package before proceed. Go to Installation section.

To create a new segment you can use Inspector facade:

use Inspector\Laravel\Facades\Inspector;

$segment = Inspector::startSegment('type', 'label');

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

Parameter Required Description
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 databse 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 an external service using something like activecampaign-api as type parameter and use the specific url or task name as label for each statements of this type.

Thanks to this grouping strategy Inspector will allows you to add custom charts for each type to analyze how your application interact with others components, in terms of throughput and runtime performance.

![]()

Terminate a segment

{warning} 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('type', 'label');

    // Your statememnt here...

} catch(\Exception $exception) {
    Inspector::reportException($exception);
} finally {
    $segment->end();
}

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

Putting everything together

Suppose you have a queued job that executes some database queries and an http request to an external service in background.

Job execution and subsequent queries are reported automatically, but we are interested to monitor and measure the execution of the http request.

Simply use the Inspector facade:

use Inspector\Laravel\Facades\Inspector;

class TagUserAsActive extends Job
{
    public function handle()
    {
        try {
            // Add a segment to the timeline
            $segment = Inspector::startSegment('activecampaign-api', 'Tag user');

            // Your statement
            $this->guzzle->post('[mail-marketing-url]/add_tag', [
                'email' => $htis->user->email,
                'tag' => 'active',
            ]);

        } catch (GuzzleException $exception) {
            // Report the exception if something goes wrong
            Inspector::reportException($exception)
        } finally {
            // End segment
            $segment->end();
        }
    }
}

In your dashboard you will see the new segment in the transaction's timeline and if something goes wrong during http call you'll be alerted in real-time to investigate and resolve issues immediately.