README

Elastic APM agent for v2 intake API. Compatible with Laravel 5.5+.

Installation

Require this package with composer:

composer require shifudeen/elastic-apm-laravel

Add the ServiceProvider class to the providers array in config/app.php:

'providers' => [
    // ... more providers
    \AG\ElasticApmLaravel\ServiceProvider::class,
],

From here, we will take care of everything based on your configuration. The agent and the middleware will be registered, and transactions will be sent to Elastic.

Agent configuration

The following environment variables are supported in the default configuration:

You may also publish the elastic-apm-laravel.php configuration file to change additional settings:

php artisan vendor:publish --tag=config

Once published, open the config/elastic-apm-laravel.php file and review the various settings.

Collectors

The default collectors typically listen on events to measure portions of the request such as framework loading, database queries, or jobs.

The SpanCollector in particular allows you to measure any section of your own code via the ApmCollector Facade:

use AG\ElasticApmLaravel\Facades\ApmCollector;

ApmCollector::startMeasure('my-custom-span', 'custom', 'measure', 'My custom span');

// do something amazing

ApmCollector::stopMeasure('my-custom-span');

To record an additional span around your job execution, you may include the provided job middleware (Laravel 6+ only https://laravel.com/docs/6.x/queues#job-middleware):

public function middleware()
{
    return [
        app(\AG\ElasticApmLaravel\Jobs\Middleware\RecordTransaction::class),
    ];
}

Add a collector for other events

You can add extra collector(s) to listen to your own application events or Laravel events like Illuminate\Mail\Events\MessageSending for example. We created a base collector that already includes functionality to measure events, that you can extend from:

// app/Collectors/MailMessageCollector.php

namespace YourApp\Collectors;

use AG\ElasticApmLaravel\Contracts\DataCollector;
use AG\ElasticApmLaravel\Collectors\EventDataCollector;

use Illuminate\Mail\Events\MessageSending;
use Illuminate\Mail\Events\MessageSent;

class MailMessageCollector extends EventDataCollector implements DataCollector
{
    public function getName(): string
    {
        return 'mail-message-collector';
    }

    protected function registerEventListeners(): void
    {
        $this->app->events->listen(MessageSending::class, function (\Swift_Message $message) {
            $this->startMeasure(
                'mail #' . $message->getId(),
                'mail.delivery',
            );
        });

        $this->app->events->listen(MessageSent::class, function (\Swift_Message $message) {
            $this->stopMeasure('mail #' . $message->getId());
        });
    }
}

Don't forget to register your collector when the application starts:

// app/Providers/AppServiceProvider.php

use AG\ElasticApmLaravel\Facades\ApmCollector;

use YourApp\Collectors\MailMessageCollector;

public function boot()
{
    // ...
    ApmCollector::addCollector(MailMessageCollector::class);
}

Development

Get Composer. Follow the instructions defined on the official Composer page, or if you are using homebrew, just run:

brew install composer

Install project dependencies:

composer install

Run the unit test suite:

php vendor/bin/codecept run unit

Please adhere to PSR-2 and Symfony coding standard. Run the following commands before pushing your code:

php ./vendor/bin/php-cs-fixer fix --config .php_cs

shifudeen / elastic-apm-laravel

Maintainers

Details