README

该包自动追踪您的 Laravel 应用程序，并将其发送到 AWS X-Ray。

什么是 X-Ray？

X-Ray 是一个用于生产应用的分布式追踪系统。AWS X-Ray 会追踪用户请求如何在您的整个应用程序中传播。它聚合了构成您的应用程序的各个服务和资源的生成数据，为您提供应用程序性能的端到端视图。

Laravel 的 X-Ray

此包可以自动追踪应用程序的重要部分，如 HTTP 请求、数据库查询、视图和队列作业。这些部分将被追踪并发送到 AWS X-Ray，以便您改进性能。

以下是一个包含数据库查询的简单 HTTP 请求示例。此查询非常慢，可能需要优化或缓存。

每个元素都有额外的信息，例如数据库查询堆栈跟踪。

安装

通过 composer 安装包

composer require napp/xray-laravel

在 App\Http\Kernel.php 中将中间件添加到全局中间件顶部。

protected $middleware = [
    \Napp\Xray\Middleware\RequestTracing::class, // here

    \App\Http\Middleware\TrustProxies::class,
    \App\Http\Middleware\CheckForMaintenanceMode::class,
    // ...
];

在 config/app.php 中将 XrayServiceProvider 添加到提供者顶部。

'providers' => [
    /*
     * Laravel Framework Service Providers...
     */
    Napp\Xray\XrayServiceProvider::class, // here

    Illuminate\Auth\AuthServiceProvider::class,
    Illuminate\Broadcasting\BroadcastServiceProvider::class,
    // ...
];

可选地，您可以在 config/app.php 中添加外观。

'aliases' => [
    // ...
    'Xray' => \Napp\Xray\Facades\Xray::class,
],

编辑 AWS 执行角色以包含 X-Ray 权限。

您可以从 AWS AWSXrayWriteOnlyAccess 添加现有的策略，或者创建自己的

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "xray:PutTraceSegments",
                "xray:PutTelemetryRecords",
                "xray:GetSamplingRules",
                "xray:GetSamplingTargets",
                "xray:GetSamplingStatisticSummaries"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

前往 AWS 控制台，转到 Lambda 并找到您的函数。激活 X-Ray 追踪。

手动使用追踪器

假设您想追踪代码的特定部分以深入了解其对性能的影响。

Xray::addSegment('MyCustomLogic');

// run your code

Xray::endSegment('MyCustomLogic');

另一个用例是检查一些繁重的 PHP 数据解析。

use Napp\Xray\Facades\Xray;

class XMLParser
{
    public function handle($file)
    {
        // adding some metadata to the segment
        Xray::addSegment('XMLParser', null, [
            'file' => $file->name()
        ]);
        $this->parse($file);
        Xray::endSegment('XMLParser');
    }
    
    private function parse($xml): array 
    {
        Xray::addSegment('XMLParser parse');
        $output = $this->getAttributeList();
        // some more code
        Xray::endSegment('XMLParser parse');

        return $output;
    }
    
    private function getAttributeList(): array 
    {
        Xray::addSegment('XMLParser getAttributeList');
        // your code
        Xray::endSegment('XMLParser getAttributeList');

        return [];
    }
}

上述操作会产生以下结果

请求过滤

可能有一些您希望在 Amazon X-Ray 中不追踪的请求。为了过滤掉这些请求，您可以在 Xray 外观上调用 addRequestFilterCallback 函数。此函数接受一个回调作为参数。该回调接受一个 Symfony\Component\HttpFoundation\Request 作为参数，并期望返回一个布尔值。

请注意，此函数调用需要在您的 AppServiceProvider 的 register 函数中完成。您还应该保持检查相对简单，因为大多数应用程序服务提供者在调用过滤回调时不会启动。

当 LaravelXray 启动时，请求将与每个已注册的回调进行核对。如果没有返回 false，则请求将被捕获。否则，它不会被捕获。

use Symfony\Component\HttpFoundation\Request;
use Napp\Xray\Facades\Xray;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        Xray::addRequestFilterCallback(function(Request $request) {
            /* some conditions */
            return true;
        });
    }
}

守护进程支持

在 Lambda 环境中自动运行 X-Ray 守护进程。使用此功能代替默认的 Napp\Xray\Submission\APISegmentSubmitter 以将请求中继到 Amazon X-Ray。

首先发布 X-Ray 配置，然后更新 config/xray.php 中的提交者到 \Napp\Xray\Submission\DaemonSegmentSubmitter::class

php artisan vendor:publish --tag=xray-config

# config/xray.php
...
 'submitter' => \Napp\Xray\Submission\DaemonSegmentSubmitter::class,
...

守护进程提交者将获取 _AWS_XRAY_DAEMON_ADDRESS 和 _AWS_XRAY_DAEMON_PORT。如果您使用像 Laravel Vapor 这样的服务，这些环境变量将为您注入。

禁用追踪器

如果您想禁用追踪器，只需将其添加到 .env 文件中。

XRAY_ENABLED=false

支持哪些追踪器

Composer 自动加载
框架启动
路由匹配
HTTP请求
数据库查询
队列任务
Blade视图渲染
缓存请求
命令

许可协议

MIT许可协议（MIT）。更多信息请参阅许可文件。

napp / xray-laravel

维护者

详情