# Custom Segments

### Add Segments (short form)

This is the most easy way to wrap a code block into a segment:

```php
$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 the segment will appear in the timeline:

![A new segment in the transaction's timeline](https://2873457055-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LQ51SrLj6qvIRejC1XD%2F-LuWftDEBTwuMd7Hu5-D%2F-LuWgbN9J5ftiM5TDO2T%2Fcodeblock-timeline.png?alt=media\&token=1a5bd2d6-f538-4d09-aa5b-6272b0d4ed01)

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

| Parameter | Required | Description                                                                                                             |
| --------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| type      | YES      | This is the master category of your segment                                                                             |
| label     | NO       | Human readable label or specific task's name that will be used as label during visualization. Otherwise `type` is used. |

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

* **mysql**: master type
* **select \* from table**: task label

In this way you can mark toghether statements related to the same topic or service, using something like `mysql` as type parameter and use the `specific query string` as label for a better timeline visualization.

This also increase your ability to filter data in the dashboard.

### Get return

What you return from the callback will be returned back by `addSegment()` method:

```php
// $response will contain "true"
$response = $inspector->addSegment(function () {
    
    // Your code block here
    return true;
    
}, 'type', 'label');
```

### Add Segments (extended code)

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

```php
/* 
 * Create a new "segment" that will be automatically attached 
 * to the current transaction.
 */
$segment = $inspector->startSegment('type', 'label');

try {

    /*
     * Here is your code
     */

} catch(UnauthorizedException $exception) {

    /*
     * Report the exception to Inspector for diagnosis purpose.
     */
    $inspector->reportException($exception);
    
} finally {
    /*
     * Close the code block with end() method to stop 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 the `addSegment()` method that implements this strategy for you as seen above:

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

![](https://2873457055-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LQ51SrLj6qvIRejC1XD%2F-LuWftDEBTwuMd7Hu5-D%2F-LuWgbN9J5ftiM5TDO2T%2Fcodeblock-timeline.png?alt=media\&token=1a5bd2d6-f538-4d09-aa5b-6272b0d4ed01)

## Segments tips and tricks

It may happen that you aren't able to wrap directly a specific statement, so it might be useful to add a segment after the task has been executed. Like the hook to listen the execution of database queries by an ORM. 

When you hook the **saved** event, the query has already been executed.

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

```php
/*
 * Http call to an external url has been perfromed with this result.
 */
$url = 'https://www.inspector.dev';
$duration_ms = 10; // Duration in milliseconds

/** 
 * -----------------------------------------
 * Create the segment manually setting timing information after the execution.
 * -----------------------------------------
 */

// convert duration in seconds
$timespamp_start = microtime(true) - ($duration_ms/1000) 

$inspector->startSegment('api', $url)
    ->start($timespamp_start)
    ->end($duration_ms);
```

### Access the Inspector instance

If you are using a framework like Laravel or Symfony, you have to access the current Inspector instance to call the `addSegment()` method. Check it out on their specific documetation:

* [**Laravel**](https://docs.inspector.dev/guides/laravel/installation#access-the-inspector-instance)
* [**Symfony**](https://docs.inspector.dev/symfony/intallation#access-the-inspector-instance)
* [**CodeIgniter**](https://docs.inspector.dev/guides/codeigniter/configuration#access-the-inspector-instance)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.inspector.dev/guides/raw-php/custom-segments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.