README

允许您轻松地将您的 Laravel 应用程序与 Jaeger (OpenTracing) 集成的库。

安装

可以使用 composer 进行安装。

composer require umbrellio/jaravel

使用

Jaravel 能够跟踪您的 incoming http 请求、控制台命令、对其他服务的 guzzle 请求以及您的队列作业。

您可以在 jaravel.php 中检查您的配置。所有配置都在注释块中描述。

您可以为每种类型的 span 配置 span 名称或标签

// config/jaravel.php
...
'http' => [
        'span_name' => fn (Request $request) => 'App: ' . $request->path(),
        'tags' => fn (Request $request, Response $response) => [
            'type' => 'http',
            'request_host' => $request->getHost(),
            'request_path' => $path = $request->path(),
            'request_method' => $request->method(),
            'response_status' => $response->getStatusCode(),
            'error' => !$response->isSuccessful() && !$response->isRedirection(),
        ],
...
    'guzzle' => [
        'span_name' => Umbrellio\Jaravel\Configurations\Guzzle\SpanNameResolver::class,
        'tags' => Umbrellio\Jaravel\Configurations\Guzzle\TagsResolver::class,
    ],
...

您可以使用任何可调用项或完全限定的类名，该类名指向具有 __invoke 方法的类（它将通过 Service Container 进行初始化，因此您可以在构造函数中注入任何您想要的项）。如果您使用 `config:cache` Artisan 命令，则这是首选方法，因为闭包无法序列化。传递给可调用项的参数取决于 span 的类型（http、控制台等）。

跟踪 incoming http 请求

要启用跟踪 incoming http 请求，您需要将中间件 HttpTracingMiddleware 添加到特定路由或全局，例如。

请求可以通过 'allow_request' 或 'deny_request' 可调用项进行过滤。如果定义了 'allow_request'，则只有当此可调用项返回 true 时，才会跟踪 http 请求。在 'allow_request' 之后，Jaravel 会检查 'deny_request' 可调用项，如果它返回 false，则不会进行跟踪。如果您不想过滤任何请求，则可以跳过此设置。

例如，如果您只想跟踪路径中包含 '/api' 的请求

// config/jaravel.php
...
'http' => [
        'allow_request' => fn (Request $request) => str_contains($request->path(), '/api'),
...

如果配置了 'trace_id_header'，则会在响应中添加带有跟踪 ID 的头。

跟踪控制台命令

默认启用。

它能够通过 'filter_commands' 过滤命令，这些命令不会进行跟踪。

// config/jaravel.php
...
'console' => [
        'filter_commands' => ['schedule:run'],
...

跟踪作业

要开始跟踪您的作业并将它们与父 span 关联，只需将 JobTracingMiddleware 添加到作业中即可。

<?php
declare(strict_types=1);

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\InteractsWithQueue;
use Umbrellio\Jaravel\Middleware\JobTracingMiddleware;

class JaravelTestJob implements ShouldQueue
{
    use InteractsWithQueue;

    public function handle()
    {
        ...
    }

    public function middleware()
    {
        return [new JobTracingMiddleware()];
    }
}

建议使用 InteractsWithQueue 特性，因为使用此特性，您可以在为作业标记 span 时使用 Job 实例的方法。

// config/jaravel.php
...
'job' => [
    'tags' => fn ($realJob, ?Job $job) => [
        'type' => 'job',
        'job_class' => get_class($realJob),
        'job_id' => optional($job)
            ->getJobId(),
        'job_connection_name' => optional($job)
            ->getConnectionName(),
        'job_name' => optional($job)
            ->getName(),
        'job_queue' => optional($job)
            ->getQueue(),
        'job_attempts' => optional($job)
            ->attempts(),
    ],
],
...

跟踪使用 Guzzle 的 outgoing http 请求

要开始跟踪您的 Guzzle 请求，只需将中间件添加到您的 Guzzle 客户端即可。

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use Umbrellio\Jaravel\HttpTracingMiddlewareFactory;

$stack = HandlerStack::create();
$stack->push(HttpTracingMiddlewareFactory::create());
$client = new Client(['handler' => $stack]);

要为所有请求添加跟踪，您可以将上述客户端绑定到您的 Service Provider 中的 GuzzleHttp\Client。

创建自己的 spans

如果您需要创建自己的 span，可以参考以下示例

use App\Services\MyService;
use OpenTracing\Tracer;
use Umbrellio\Jaravel\Services\Span\SpanCreator;
use Umbrellio\Jaravel\Services\Span\SpanTagHelper;

// You should use dependency injection in your code, it`s just an example 
$spanCreator = app(SpanCreator::class);  
$myService = app(MyService::class);
$tracer = app(Tracer::class);

// First you need to create a span. It will be a child of current active span, if active span exists
$span = $spanCreator->create('Call MyService');

// Do something 
$myService->doSomething();

// Close active scope (span will be finished automatically) and flush tracer.
optional($tracer->getScopeManager()->getActive())->close();
$tracer->flush();

如果您需要检索当前跟踪 ID，可以使用： Umbrellio\Jaravel\Services\Span\ActiveSpanTraceIdRetriever::retrieve()

许可证

在 MIT 许可证下发布。

作者

由 Vitaliy Lazeev 创建。

贡献

• 将其叉（ https://github.com/umbrellio/jaravel ）
• 创建您的功能分支（git checkout -b feature/my-new-feature）
• 提交您的更改（git commit -am 'Add some feature'）
• 将分支推送到远程（git push origin feature/my-new-feature）
• 创建新的 Pull Request