Installation & set-up

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 palzin-apm/palzin-laravel

For Lumen

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

$app->register(\Palzin\Laravel\PalzinServiceProvider::class);

If you wish to use the \Palzin\Laravel\Facades\Palzin 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 Palzin Monitor (https://palzin.app/register) and creating a new application.

Put the Palzin Monitor (APM) Ingestion Key in your environment file:

PALZIN_APM_INGESTION_KEY=[ingestion key]

Test everything is working

Execute the test command to check if your app can send data to Palzin Monitor (APM) correctly:

php artisan palzin:test

Go to https://palzin.app/ to explore your data.

By default Palzin Monitor (APM) 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://palzin.app/guides/laravel-background-jobs-commands-monitoring-with-palzin-monitor/

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 Palzin Monitor 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(
        [\Palzin\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.

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 Palzin\Laravel\Facades\Palzin;

Palzin::beforeFlush(function ($palzin) {
    // Do something before data are sent.
});

The callback will receive the current Palzin Monitor 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:

<?php

namespace App\Providers;

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

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

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Palzin::beforeFlush(function ($palzin) {
            if ($palzin->currentTransaction()->name === ExampleJob::class) {
                $prob = mt_rand(0, mt_getrandmax() - 1) / mt_getrandmax();
                
                return $prob < 0.7; // Report 70% of the executions
            }
        });
    }
}

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 Palzin\Laravel\Facades\Palzin;

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

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot()
    {
        Palzin::beforeFlush(function ($palzin) {
            $palzin->currentTransaction()
                ->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 Palzin Monitor instance

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

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



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

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

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Palzin\Laravel\Palzin;

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