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 -vTo know what is the Laravel version behind your application run this command in your application's main directory:
php artisan --versionClear 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:clearInstall
Type the command below in your terminal to install the latest version of the package:
1
composer require inspector-apm/inspector-laravel
Copied!
For Lumen
If your application is based on Lumen you need to manually register the
InspectorServiceProvider:1
$app->register(\Inspector\Laravel\InspectorServiceProvider::class);
Copied!
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:1
$app->withFacades();
Copied!
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:
1
INSPECTOR_INGESTION_KEY=[ingestion key]
Copied!
Test everything is working
Execute the test command to check if your app can send data to inspector correctly:
1
php artisan inspector:test
Copied!
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:1
protected function bootstrappers()
2
{
3
return array_merge(
4
[\Inspector\Laravel\OutOfMemoryBootstrapper::class],
5
parent::bootstrappers(),
6
);
7
}
Copied!
The
OutOfMemoryBootstrapper must be the first registered bootstrapper, or it may not be called before the out of memory exception crashes your app.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:1
use Inspector\Laravel\Facades\Inspector;
2
3
Inspector::beforeFlush(function ($inspector) {
4
// Do something before data are sent.
5
});
Copied!
The callback will receive the current Inspector instance as parameter.
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
ExampleJob executions:1
<?php
2
3
namespace App\Providers;
4
5
use App\Jobs\ExampleJob;
6
use Illuminate\Support\ServiceProvider;
7
use Inspector\Laravel\Facades\Inspector;
8
9
class AppServiceProvider extends ServiceProvider
10
{
11
/**
12
* Register any application services.
13
*
14
* @return void
15
*/
16
public function register()
17
{
18
//
19
}
20
21
/**
22
* Bootstrap any application services.
23
*
24
* @return void
25
*/
26
public function boot()
27
{
28
Inspector::beforeFlush(function ($inspector) {
29
if ($inspector->currentTransaction()->name === ExampleJob::class) {
30
$prob = mt_rand(0, mt_getrandmax() - 1) / mt_getrandmax();
31
32
return $prob < 0.7; // Report 70% of the executions
33
}
34
});
35
}
36
}
Copied!
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:1
<?php
2
3
namespace App\Providers;
4
5
use App\Jobs\ExampleJob;
6
use Illuminate\Support\ServiceProvider;
7
use Inspector\Laravel\Facades\Inspector;
8
9
class AppServiceProvider extends ServiceProvider
10
{
11
/**
12
* Register any application services.
13
*
14
* @return void
15
*/
16
public function register()
17
{
18
//
19
}
20
21
/**
22
* Bootstrap any application services.
23
*
24
* @return void
25
*/
26
public function boot()
27
{
28
Inspector::beforeFlush(function ($inspector) {
29
$inspector->currentTransaction()
30
->host
31
->hostname = config('app.service_name')??'rest-api'
32
});
33
}
34
}
Copied!
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:
1
/*
2
* Using the helper function
3
*/
4
inspector()->addSegment(function () {
5
// Do something
6
}, 'label');
7
8
9
10
/*
11
* Using the Facade
12
*/
13
\Inspector\Laravel\Facades\Inspector::addSegment(function () {
14
// Do something
15
}, 'label');
Copied!
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.
1
namespace App\Http\Controllers;
2
3
use Illuminate\Http\Request;
4
use Inspector\Laravel\Inspector;
5
6
class HomeController extends Controller
7
{
8
/**
9
* Show the application dashboard.
10
*
11
* @return \Illuminate\Contracts\Support\Renderable
12
*/
13
public function index(Inspector $inspector)
14
{
15
return view('home');
16
}
17
}
Copied!
Last modified 3mo ago