README

Elastic APM代理，用于v2 intake API。兼容Laravel 6及以上版本。

先决条件

您需要完成以下步骤来安装此包。

HTTP客户端

为了最小化潜在的依赖冲突，此包不指定用于向APM发送数据的HTTP客户端。相反，您的项目必须包含一个合适的PSR-18兼容实现。最简单的方法是使用GuzzleHTTP的php-http适配器。根据您的具体需求，需要使用guzzle6或guzzle7适配器。

    # 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

安装

使用Composer要求此包

# Laravel 8+ and PHP 8+
composer require arkaitzgarro/elastic-apm-laravel

# Laravel 6+
composer require arkaitzgarro/elastic-apm-laravel:^3.0

# Laravel 5.5 - 5.8
composer require arkaitzgarro/elastic-apm-laravel:^2.0

Laravel的提供者自动发现应该能够找到包的ServiceProvider。否则，将ServiceProvider类添加到config/app.php中的提供者数组中

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

从现在开始，我们将根据您的配置来处理所有事情。代理和中间件将被注册，事务将被发送到Elastic。

代理配置

从本包的2.0版本开始，可以使用环境变量来配置底层的APM代理。将ELASTIC_APM_*变量放置在您的.env文件中或使用任何其他适当的方法使其对项目可用。

请注意，本处可能没有记录代理的功能，您应参考nipwaayoni/elastic-apm-php-agent 项目文档以了解完整的功能集。

以下选项仍由本包支持，如果存在，则将优先于它们的ELASTIC_APM_*对应项。

上述APM_*变量可能在未来的版本中删除。

Laravel选项

以下环境变量在默认配置中受支持

您还可以发布elastic-apm-laravel.php配置文件来更改其他设置

php artisan vendor:publish --tag=config

一旦发布，打开config/elastic-apm-laravel.php文件并查看各种设置。

日志记录

您的Laravel应用程序使用的Monolog实例将自动提供给代理进行日志记录。代理包的日志级别独立于您的Laravel应用程序的日志级别。这允许您仅在有用时包含代理消息。使用APM_LOG_LEVEL环境设置来实现这一点。代理包的默认日志级别为info。

收集器

默认收集器通常会监听事件以衡量请求的部分，例如框架加载、数据库查询或作业。

特别是SpanCollector允许您通过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');

要记录作业执行周围的附加span，您可以包含提供的作业中间件

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

注意 当使用dispatchNow()方法创建作业时，作业中间件将不会运行。在作业内显式创建的span仍将被收集，但整个作业span将不会包括在内。

添加其他事件的收集器

您可以为监听您自己的应用程序事件或Laravel事件（例如Illuminate\Mail\Events\MessageSending）添加额外的收集器。我们创建了一个基收集器，它已经包括用于衡量事件的功能，您可以从中扩展

// 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());
        });
    }
}

应用启动时，别忘了注册您的收集器

// app/Providers/AppServiceProvider.php

use AG\ElasticApmLaravel\Facades\ApmCollector;

use YourApp\Collectors\MailMessageCollector;

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

或者，您现在可以在容器中简单地为您的收集器打上标签，它就会被发现。请注意，收集器 必须 在从容器中首次解析出 Agent 之前进行标记，通常是在您的提供者的 boot 方法中。

// app/Providers/AppServiceProvider.php

use YourApp\Collectors\MailMessageCollector;

public function boot()
{
    $this->app->tag(MailMessageCollector::class, \AG\ElasticApmLaravel\ServiceProvider::COLLECTOR_TAG);
}

注意 事件收集受 APM_MAXTRACEITEMS 设置的限制。如果您的收集器在请求完成之前延迟添加事件，并且总事件数超过最大跟踪项数，您的事件数量可能会比预期多。您应该尽力在请求处理过程中事件发生时收集事件。使用 EventDataCollector::startMeasure() 方法可以在停止测量时将事件标记为收集，即使最大跟踪项数已经达到。

分布式跟踪

分布式跟踪 允许您将 Laravel 应用程序中的事务与您的应用程序所消费的服务中的事务关联起来。例如，如果您的 Laravel 应用程序在处理请求时调用 REST 资源，则 REST 事务细节将显示在 Elastic APM 中的应用程序事务中。您通过在应用程序向另一个服务发出的 http 请求中包含适当的头来实现分布式跟踪。例如

$request = new Request(
    'PUT',
    '/some/backend/resource',
    [
        'Content-Type' => 'application/json',
    ],
    json_encode(...)
);

$request = \AG\ElasticApmLaravel\Facades\ApmAgent::addTraceParentHeader($request);

$this->client->send($request);

如果您不是处理 RequestInterface 对象，您可以使用当前的事务并使用 数组或字符串方法 获取 traceparent。

$transaction = ApmAgent::getCurrentTransaction();

$headerArray = $transaction->traceHeaderAsArray();
$headerString = $transaction->traceHeaderAsString();

开发

获取 Composer。按照官方 Composer 页面 上的说明操作，或者如果您使用 homebrew，只需运行

brew install composer

安装项目依赖

composer install

运行单元测试套件

php vendor/bin/codecept run

请遵循 PSR-2 和 Symfony 编码标准。在推送代码之前运行以下命令

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

与运行中的应用程序集成

为了能够使用本地运行的应用程序测试您的更改，使用 Composer 的功能从本地路径要求包。在您的项目中添加一个本地存储库，只需确保 elastic-apm-laravel 文件夹的路径正确即可

composer config repositories.local '{"type": "path", "url": "../elastic-apm-laravel"}' --file composer.json

然后从源安装包

composer require arkaitzgarro/elastic-apm-laravel:@dev --prefer-source

您应该会看到一个消息表示已将包作为符号链接安装

- Installing arkaitzgarro/elastic-apm-laravel (dev-chore/branch-name): Symlinking from ../elastic-apm-laravel