README

此包不再维护。请使用 https://github.com/arkaitzgarro/elastic-apm-laravel

PHP Elastic APM for Laravel & Lumen

Laravel 包，基于 nipwaayoni/elastic-apm-php-agent 库，自动处理事务和错误/异常。如果使用 Illuminate\Support\Facades\Auth，将用户 ID 添加到上下文中。已在 Laravel 5.6.* 和 nipwaayoni/elastic-apm-php-agent 版本 7.1.* 上测试。

此包是 philkra 在 philkra/elastic-apm-laravel 上所做优秀工作的延续。

安装

composer require nipwaayoni/elastic-apm-laravel

nipwaayoni/elastic-apm-php-agent 不再包含 http 客户端。您必须确保有可用的 PSR-18 兼容实现。有关更多信息，请参阅代理安装指南。

服务提供者

Laravel

如果使用 Laravel >=5.5，则通过 package discovery 自动进行注册。

此包未在 Laravel <5.5 上进行测试或断言其可以工作。

Lumen

在 bootstrap/app.php 中注册 \Nipwaayoni\ElasticApmLaravel\Providers\ElasticApmServiceProvider::class 作为服务提供者。

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

中间件

Laravel

注册为（例如）全局中间件，以便在每次请求时调用。请参阅 https://laravel.net.cn/docs/5.6/middleware#global-middleware

在 app/Http/Kernel.php 中注册中间件。

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

自定义事务

提供的中间件会将请求和响应上下文数据添加到事务中。如果现有行为不符合您的需求，您可以通过覆盖类来提供自己的中间件。有关更多信息，请参阅 自定义事务 的文档。

Lumen

在 bootstrap/app.php 中注册 Nipwaayoni\ElasticApmLaravel\Middleware\RecordTransaction::class 作为中间件。

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

事件

Elastic APM 服务支持多种事件类型。此包目前仅支持此处所述的子集。

事务事件

RecordTransaction 中间件会自动为当前的 HTTP 请求启动一个新的事务。所有额外的事件都将作为此事务的后代。

目前尚无管理额外事务事件的设置，也无法处理非 HTTP 请求的流程。我们希望在未来的版本中解决这些问题。

自定义事务上下文

虽然 RecordTransaction 中间件在创建事务时设置了支持的 APM 上下文，但您可能希望根据完成的请求/响应自定义上下文。这可以通过扩展 RecordTransaction 中间件并重写上下文方法来实现，具体请参考自定义事务 文档。

排除请求

您可以使用 URI 模式列表来排除请求发送到 APM。例如，您可能希望在开发或测试期间避免发送对 (DebugBar)[https://github.com/barryvdh/laravel-debugbar] 资源请求。

将所需的 URI 模式添加到 elastic-apm 配置中的 except 键。请注意，您必须按照配置文档中的说明发布文件。

如果您已按照自定义事务 文档中的说明扩展了 RecordTransaction 中间件，您可以在那里设置 except 列表类成员。

跨度事件

跨度发生在事务内部。跨度表示事务内的事件。通过 Laravel 的数据库层进行的查询将自动添加到事务中。您可以使用此包中的 EventTimer 类添加自己的跨度事件。请参阅创建跨度 文档。

该包目前不支持嵌套跨度。

错误事件

APM 服务将异常事件定义为有效类型。您可以将应用程序中的异常发送到 APM，除了任何常规异常处理之外。请参阅异常 文档。

代理配置

您可以使用许多环境设置来影响此包的行为。至少，您必须设置 APM 服务器 URL 以及（如果适用）密钥令牌。

有关更多信息，请参阅配置文档。

HTTP 客户端定制

现在无法通过APM PHP Agent配置来提供HTTP客户端选项。如果您需要自定义HTTP客户端，您必须实现并配置一个合适的客户端对象，并将其提供给AgentBuilder。请参阅“HTTP客户端配置”部分（[配置文档](https://github.com/nipwaayoni/elastic-apm-laravel/blob/HEAD/docs/configuration.md)）。

Laravel测试设置

Laravel提供了类来支持使用PHPUnit运行单元测试和功能测试。在大多数情况下，您可能希望在测试期间明确禁用APM，因为它默认是启用的。请参阅Laravel文档以获取更多信息（[测试文档](https://laravel.net.cn/docs/5.7/testing)）。

由于APM代理使用严格的布尔类型来检查其活动状态，您必须确保您的APM_ACTIVE值是一个布尔值false，而不是一个假值。完成此操作的最佳方法是创建一个.env.testing文件，并包括APM_ACTIVE=false，以及您的测试所需的任何其他环境设置。此文件应该可以安全地包含在您的源代码管理中。