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:
composer require inspector-apm/inspector-laravelFor 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:testGo 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
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');
}
}Last updated