rafaelmilanibarbosa/elastic-apm

A package to integrate Elastic APM into Laravel

0.0.1 2020-03-14 03:47 UTC

Requires

• php: >= 7.0
• illuminate/database: 5.5.x|5.6.x|5.7.x|5.8.x
• illuminate/http: 5.5.x|5.6.x|5.7.x|5.8.x
• illuminate/routing: 5.5.x|5.6.x|5.7.x|5.8.x
• illuminate/support: 5.5.x|5.6.x|5.7.x|5.8.x
• philkra/elastic-apm-php-agent: >=6.5.3
• ramsey/uuid: ^3.0

Requires (Dev)

• phpunit/phpunit: 6.*

MIT

• Rafael Milani Barbosa

• 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 5.6.* and the philkra/elastic-apm-php-agent version 6.2.*.

Install

composer require rafaelmilanibarbosa/elastic-apm

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
    \RafaelMilaniBarbosa\ElasticApm\Middleware\RecordTransaction::class,
];

Lumen

In bootstrap/app.php register RafaelMilaniBarbosa\ElasticApm\Middleware\RecordTransaction::class as middleware:

$app->middleware([
    RafaelMilaniBarbosa\ElasticApm\Middleware\RecordTransaction::class
]);

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:

Variable	Description
APM_ACTIVE	true or false defaults to true. If false, the agent will collect, but not send, transaction data.
APM_APPNAME	Name of the app as it will appear in APM.
APM_APPVERSION	Version of the app as it will appear in APM.
APM_SERVERURL	URL to the APM intake service.
APM_SECRETTOKEN	Secret token, if required.
APM_APIVERSION	APM API version, defaults to v1 (only v1 is supported at this time).
APM_USEROUTEURI	true or false defaults to false. The default behavior is to record the URL as sent in the request. This can result in excessive unique entries in APM. Set to true to have the agent use the route URL instead.
APM_QUERYLOG	true or false defaults to 'true'. Set to false to completely disable query logging, or to auto if you would like to use the threshold feature.
APM_THRESHOLD	Query threshold in milliseconds, defaults to 200. If a query takes longer then 200ms, we enable the query log. Make sure you set APM_QUERYLOG=auto.

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.