bethinkpl/elastic-apm-laravel

A package to integrate Elastic APM 7.x into Laravel

7.6.0 2021-02-26 12:12 UTC

Requires

• php: >= 7.2
• guzzlehttp/guzzle: ~6.0
• illuminate/database: ^6.0|^7|^8
• illuminate/http: ^6.0|^7|^8
• illuminate/routing: ^6.0|^7|^8
• illuminate/support: ^6.0|^7|^8
• philkra/elastic-apm-php-agent: 7.0.0-rc3
• psr/http-message: ^1.0
• ramsey/uuid: ^3.0|^4.0

Requires (Dev)

• phpunit/phpunit: 6.*

MIT

• Philip Krauss
• George Boot

• debug
• monitoring
• laravel
• elastic
• apm
• lumen

README

Laravel package of the https://github.com/philkra/elastic-apm-php-agent library, automatically handling transactions and errors/exceptions. If using Illuminate\Support\Facades\Auth the user Id added to the context. Tested with Laravel 6.* and the philkra/elastic-apm-php-agent version 7.x.

Install

composer require bethinkpl/elastic-apm-laravel

Use local code in wnl-platform instead of a released package

cd wnl-platform/vendor/bethinkpl/
rm -rf elastic-apm-laravel
ln -s ../../../elastic-apm-laravel ./elastic-apm-laravel

Make sure to use absolute paths.

Additional features

• X-Requested-By HTTP request header value is set as labels.requested_by APM transaction field (end-user-ajax value is used when X-Requested-With: XMLHttpRequest is set)
• sampling of transactions reported to APM
• tracking of HTTP requests performed using GuzzleHttp library. Simply add the following middleware to your Guzzle client:

<?php

use PhilKra\ElasticApmLaravel\Providers\ElasticApmServiceProvider;
use GuzzleHttp\HandlerStack;

$handler = HandlerStack::create();
$handler->push(ElasticApmServiceProvider::getGuzzleMiddleware());

// create your client with 'handler' option passed

Middleware

Laravel

Register as (e.g.) global middleware to be called with every request. https://laravel.com/docs/5.6/middleware#global-middleware

Register the middleware in app/Http/Kernel.php

protected $middleware = [
    // ... more middleware
    \PhilKra\ElasticApmLaravel\Middleware\RecordTransaction::class,
];

Lumen

In bootstrap/app.php register PhilKra\ElasticApmLaravel\Middleware\RecordTransaction::class as middleware:

$app->middleware([
    PhilKra\ElasticApmLaravel\Middleware\RecordTransaction::class
]);

Service Provider

Laravel

No need to register service provider manually. It is registered automatically by package discovery.

Lumen

In bootstrap/app.php register \PhilKra\ElasticApmLaravel\Providers\ElasticApmServiceProvider::class as service provider:

$app->register(\PhilKra\ElasticApmLaravel\Providers\ElasticApmServiceProvider::class);

Spans

Laravel

A Transaction object is made available via the dependency container and can be used to start a new span at any point in the application. The Span will automatically add itself to the Transaction when it is ended.

// Use any normal Laravel method of resolving the dependency
$transaction = app(\PhilKra\ElasticApmLaravel\Apm\Transaction::class);

$span = $transaction->startNewSpan('My Span', 'app.component_name');

// do some stuff

$span->end();

Lumen

pending

Error/Exception Handling

Laravel

In app/Exceptions/Handler, add the following to the report method:

ElasticApm::captureThrowable($exception);
ElasticApm::send();

Make sure to import the facade at the top of your file:

use ElasticApm;

Lumen

not tested yet.

Agent Configuration

Laravel

The following environment variables are supported in the default configuration:

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

php artisan vendor:publish --tag=config

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

Laravel Test Setup

Laravel provides classes to support running unit and feature tests with PHPUnit. In most cases, you will want to explicitly disable APM during testing since it is enabled by default. Refer to the Laravel documentation for more information (https://laravel.com/docs/5.7/testing).

Because the APM agent checks it's active status using a strict boolean type, you must ensure your APM_ACTIVE value is a boolean false rather than simply a falsy value. The best way to accomplish this is to create an .env.testing file and include APM_ACTIVE=false, along with any other environment settings required for your tests. This file should be safe to include in your SCM.