Elastic APM agent for v2 intake API. Compatible with Laravel 6+.
Transactions list | Transaction detail |
---|---|
![]() |
![]() |
You are responsible for completing the following as part of installing this package.
In order to minimize potential dependency conflicts, this package does not dictate the HTTP client which will be used to send data to APM. Instead, your project must include a suitable PSR-18 compatible implementation. The easiest way to do this is using the php-http adapter for GuzzleHTTP. Require either the guzzle6 or guzzle7 adapter, depending on your specific needs.
# if you are using guzzlehttp/guzzle version 6
# note that you must use >=2.0 of the guzzle6-adapter
composer require php-http/guzzle6-adapter
# if you are using guzzlehttp/guzzle version 7
composer require php-http/guzzle7-adapter
Require this package with composer:
# Laravel 6+
composer require arkaitzgarro/elastic-apm-laravel
# Laravel 5.5 - 5.8
composer require arkaitzgarro/elastic-apm-laravel:^2.0
Laravel's provider auto-discover should find the package ServiceProvider. Otherwise, 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.
The underlying APM Agent may be configured using environment variables as of version 2.0 of this package. Place the ELASTIC_APM_*
variables in your .env
file or use any other appropriate means to make them available to your project.
Note that features of the Agent may not be documented here and you should refer to the nipwaayoni/elastic-apm-php-agent
project documentation for the full feature set.
The following options are still supported by this package and will take precedence over their ELASTIC_APM_*
counterparts if present.
Variable | Alternative | Description |
---|---|---|
APM_ACTIVE | ELASTIC_APM_ENABLED | true or false defaults to true . If false , the agent will collect, but not send, transaction data; span collection will also be disabled. |
APM_APPNAME | ELASTIC_APM_SERVICE_NAME | Name of the app as it will appear in APM. Invalid special characters will be replaced with a hyphen. |
APM_APPVERSION | ELASTIC_APM_SERVICE_VERSION | Version of the app as it will appear in APM. |
APM_SERVERURL | ELASTIC_APM_SERVER_URL | URL to the APM intake service. |
APM_SECRETTOKEN | ELASTIC_APM_SECRET_TOKEN | Secret token, if required. |
APM_BACKTRACEDEPTH | ELASTIC_APM_STACK_TRACE_LIMIT | Defaults to 0 (unlimited). Depth of backtrace in query span. |
The APM_*
variables listed above may be removed in a future release.
The following environment variables are supported in the default configuration:
Variable | Description |
---|---|
APM_LOG_LEVEL | Log level for the APM Agent package. Must be PSR-3 compliant. Defaults to error . |
APM_ACTIVE_CLI | true or false defaults to true . If false , the agent will not collect or send transaction or span data for non-HTTP requests but HTTP requests will still follow ELASTIC_APM_ENABLED. When ELASTIC_APM_ENABLED is false , this will have no effect. |
APM_USEROUTEURI | true or false defaults to true . The default behavior is to record the URL as defined in your routes configuration. Set to false to record the requested URL, but keep in mind that this can result in excessive unique entries in APM. |
APM_IGNORE_PATTERNS | Ignore specific routes or jobs by transaction name. Should be a regular expression, and will match multiple patterns via pipe | in the regex. Note that 4 backslashes should be used to match a single backslash. Example: "/\/health-check|^OPTIONS |Foo\\\\Bar\\\\Job/" |
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 . |
APM_MAXTRACEITEMS | Defaults to 1000 . Max number of child items displayed when viewing trace details. |
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.
The Monolog instance used by your Laravel application will be automatically given to the Agent for logging. The log level for the Agent package is independent of the log level for your Laravel application. This allows you to only include Agent messages when they are useful. Use the APM_LOG_LEVEL
environment setting for this. The default log level for the agent package is info
.
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:
public function middleware()
{
return [
app(\AG\ElasticApmLaravel\Jobs\Middleware\RecordTransaction::class),
];
}
Note Job middleware is not run when a job is created with the dispatchNow()
method. Spans explicitly created within the job will still be collected, but the overall job span will not be included.
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);
}
Alternatively, you can now simply tag your collector in the container and it will be discovered. Note that the collector must be tagged before the Agent
is first resolved from the container, normally in the boot
method of your provider.
// app/Providers/AppServiceProvider.php
use YourApp\Collectors\MailMessageCollector;
public function boot()
{
$this->app->tag(MailMessageCollector::class, \AG\ElasticApmLaravel\ServiceProvider::COLLECTOR_TAG);
}
Note Collecting events is subject to the APM_MAXTRACEITEMS
setting. If your collector defers adding events until the request is complete, and the total event count exceeds the max trace items, a higher than expected number of your events may be dropped. You should make every effort to collect events at the point they occur during the request processing. Using the EventDataCollector::startMeasure()
method will flag an event for collection even if the max trace items has been reached when the measure is stopped.
Distributed tracing allows you to associate transactions in your Laravel application with transactions in services your application consumes. For example, if your Laravel application calls REST resources as part of handling a request, the REST transaction details will appear within your application transaction in Elastic APM. You enable distributed tracing by including an appropriate header in the http request your application makes to another service. For example:
$request = new Request(
'PUT',
'/some/backend/resource',
[
'Content-Type' => 'application/json',
],
json_encode(...)
);
$request = \AG\ElasticApmLaravel\Facades\ApmAgent::addTraceParentHeader($request);
$this->client->send($request);
If you are not dealing with a RequestInterface
object, you can get the current transaction and use the array or string methods to get the traceparent
.
$transaction = ApmAgent::getCurrentTransaction();
$headerArray = $transaction->traceHeaderAsArray();
$headerString = $transaction->traceHeaderAsString();
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
Please adhere to PSR-2 and Symfony coding standard. Run the following commands before pushing your code:
php ./vendor/bin/php-cs-fixer fix
To be able to test your changes with a locally running application, use Composer's functionality to require packages from local paths. On your project, add a local repository, just make sure the path to elastic-apm-laravel
folder is correct:
composer config repositories.local '{"type": "path", "url": "../elastic-apm-laravel"}' --file composer.json
Then install the package from the source:
composer require arkaitzgarro/elastic-apm-laravel:@dev --prefer-source
You should see a message indicating that the package has been installed as symlink:
- Installing arkaitzgarro/elastic-apm-laravel (dev-chore/branch-name): Symlinking from ../elastic-apm-laravel