Installation & Set-up

Connect your Laravel application with Inspector.

Server requirements

• PHP >= 7.2

• Laravel >= 5.5

To verify what version of PHP is installed on your server run this command in your terminal:

php -v

To know what is the Laravel version behind your application run this command in your application's main directory:

php artisan --version

Clear the Laravel configuration

Before installing the package you should clear your Laravel configuration to avoid unexpected error loading the default package config file.

Run the command below to clear your cached configuration:

php artisan config:clear

Install

Type the command below in your terminal to install the latest version of the package:

composer require inspector-apm/inspector-laravel

For Lumen

If your application is based on Lumen you need to manually register the InspectorServiceProvider:

$app->register(\Inspector\Laravel\InspectorServiceProvider::class);

If you wish to use the \Inspector\Laravel\Facades\Inspector facade, you should also enable facades if you did not already by uncommenting the withFacades() call in bootstrap/app.php:

$app->withFacades();

Configure the Ingestion Key

Get a new Ingestion Key by signing up for Inspector (https://app.inspector.dev/register) and creating a new application.

Put the Inspector Ingestion Key in your environment file:

INSPECTOR_INGESTION_KEY=[ingestion key]

Test everything is working

Execute the test command to check if your app can send data to inspector correctly:

php artisan inspector:test

Go to https://app.inspector.dev/home to explore your data.

By default Inspector will monitor everything executed in background:

• Queued Jobs

• Artisan commands

• Unhandled Exceptions

If you want learn more about background jobs monitoring take a look on our article: https://www.inspector.dev/laravel-background-jobs-commands-monitoring-with-inspector/

Go the Http Request Monitoring section to understand how to trace your application when it's executed due to an incoming http request.

Reporting Out Of Memory Errors

When your app runs out of memory it's needed to temporary increase the PHP memory limit to ensure inspector can report the current transaction. To do this, a “bootstrapper” class must be registered in both the app/Http/Kernel.php and app/Console/Kernel.php files:

protected function bootstrappers()
{
    return array_merge(
        [\Inspector\Laravel\OutOfMemoryBootstrapper::class],
        parent::bootstrappers(),
    );
}

The OutOfMemoryBootstrapper must be the first registered bootstrapper, or it may not be called before the out of memory exception crashes your app.

Scheduled Jobs

Laravel allows you to execute jobs as cron tasks. Here is an example of an entry in the Laravel scheduler:

$schedule->job(ProcessAudioFiles::class)->everyFifteenMinutes();

Using this feature might run into the "Inspector::$transaction not found" error. Use the configuration below to avoid it to happen.

To allow Inspector to correctly monitor the scheduled job you must be sure that the job class implements the Illuminate\Contracts\Queue\ShouldQueue interface:

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;

class ProcessAudioFiles implements ShouldQueue 
{
    ...
}

Since Laravel internally runs a closure to dispatch the job onto the queue, you need to add the class name of the job in the ignore_commands property in the inspector.php config file to filter out the execution of this closure from the monitoring dashboard.

/*
|--------------------------------------------------------------------------
| Artisan command to ignore
|--------------------------------------------------------------------------
|
| Add at this list all command signature that you don't want monitoring
| in your Inspector dashboard.
|
*/

'ignore_commands' => [
    ...,
    \App\Jobs\ProcessAudioFiles::class,
],

Before flush callback

The package allows you to register a callback before data are sent to the remote platform. Paste the code below in the boot method of your AppServiceProvider:

use Inspector\Laravel\Facades\Inspector as InspectorFacade;
use Inspector\Inspector;

InspectorFacade::beforeFlush(function (Inspector $inspector) {
    // Do something before data are sent.
});

The callback will receive the current Inspector instance as parameter.

For more detailed instruction on how to use the beforeFlush method take a look at the PHP documentation.

Sampling a specific transaction

The most common use case for beforeFlush method is sampling. If your application execute a specific transaction for a huge number of times every hour, it could be useful to sample this transasction to mitigate the quota consumption still guaranteeing a good level of detail of the metrics.

In the example below we report only the 70% of the GET /healthceck endpoint calls:

<?php

namespace App\Providers;

use App\Jobs\ExampleJob;
use Illuminate\Support\ServiceProvider;
use Inspector\Laravel\Facades\Inspector;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Inspector::beforeFlush(function ($inspector) {
            if ($inspector->transaction()->name === 'GET /healthceck') {
                $prob = mt_rand(0, mt_getrandmax() - 1) / mt_getrandmax();
                
                return $prob < 0.7; // Report 70% of the times
            }
        });
    }
}

You can do the same with Jobs using the fully qualified class name of the job in the IF statement:

if ($inspector->transaction()->name === ExampleJob::class) {
    $prob = mt_rand(0, mt_getrandmax() - 1) / mt_getrandmax();
               
    return $prob < 0.7; // Report 70% of the times
}

Set a custom service name

If your application runs in Kubernates cluster or use "auto-scaling" you could see a bit of mess in your charts. It is probably due to the constant turnover of servers to handle the application load dynamically.

It may be useful to monitor each autoscaling group with the same name regardless of the hostnames of the servers that are continuously turned on and off.

Using the beforeFlush() method you can group your monitoring data by services (API, workers, web app, etc) instead by hostnames:

<?php

namespace App\Providers;

use App\Jobs\ExampleJob;
use Illuminate\Support\ServiceProvider;
use Inspector\Laravel\Facades\Inspector;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Inspector::beforeFlush(function ($inspector) {
            $inspector->transaction()
                ->host
                ->hostname = config('app.service_name')??'rest-api'
        });
    }
}

In the example above you can get your service name by a custom configuration property, or alternatively you could create an environment variable. You are free to configure it based also on your CI/CD pipelines.

Access the Inspector instance

You can get the current Inspector instance using the helper function or the Facade:

/*
 * Using the helper function
 */
inspector()->addSegment(function () {
    // Do something
}, 'label');



/*
 * Using the Facade
 */
\Inspector\Laravel\Facades\Inspector::addSegment(function () {
    // Do something
}, 'label');

The current Inspector instance is binded in the Laravel service container. In your controller, you can type-hint an argument with the Inspector's class name.

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Inspector\Laravel\Inspector;

class HomeController extends Controller
{
    /**
     * Show the application dashboard.
     *
     * @return \Illuminate\Contracts\Support\Renderable
     */
    public function index(Inspector $inspector)
    {
        return view('home');
    }
}