README

OpenTracing API 的 Laravel 实现，包括用于应用程序日志记录的无服务器本地追踪器。

有关更多信息，请参阅 OpenTracing。

支持客户端

当前支持的客户端

• 本地：主要用于将跟踪 ID 添加到日志中的无操作追踪器。
• Jaeger：开源、端到端分布式追踪。请参阅 Jaeger 和 Jonah George 的 Jaeger Client PHP。

安装

使用以下命令安装最新版本：

composer require wizofgoz/laravel-opentracing

如果您想通过运行以下命令来更改默认配置文件，请将其复制到您的应用程序中。请注意，如果文件已存在，则必须使用 --force。

php artisan vendor:publish --provider="LaravelOpenTracing\TracingServiceProvider"

基本用法

示例设置

示例 bootstrap/app.php 文件

<?php

// Create the application.
$app = new \Illuminate\Foundation\Application(realpath(__DIR__ . '/../'));

// Bind important interfaces.
// ...

// Register important providers.
$app->register(\LaravelOpenTracing\TracingServiceProvider::class);

// Enable tracing span context in log messages.
$app->configureMonologUsing(function (\Monolog\Logger $logger) {
    $logger->pushProcessor(new \LaravelOpenTracing\Log\Processors\TracingProcessor());
});

// Return the application.
return $app;

追踪

要追踪应用程序中的特定进程，您可以使用提供的门面将进程包装在跟踪闭包中，如下所示。这将负责在闭包返回或抛出时启动新的跟踪范围并关闭它。

<?php

$items = \LaravelOpenTracing\Facades\Tracing::trace(
    'todo.get_list_items',
    function () {
        return \App\Models\TodoListItem::get();
    }
);

嵌套跟踪也是可能的，如下所示。它将自动处理范围子父级关系。

<?php

function a() {
    // We don't care about tracing this specifically.
    doSomething();

    \LaravelOpenTracing\Facades\Tracing::trace(
        'app.do_something_else',
        function () {
            doSomethingElse();
        }
    );
}

\LaravelOpenTracing\Facades\Tracing::trace(
    'app.do_stuff',
    function () {
        a();
    }
);

如果您想向范围添加上下文信息或标记，可以像下面这样操作。

<?php

$title = 'Make more coffee';

$item = \LaravelOpenTracing\Facades\Tracing::trace(
    'todo.store_item',
    function () use ($title) {
        return \App\Models\TodoListItem::create(['title' => $title]);
    },
    ['tags' => ['title' => $title]]
);

为门面上的所有函数提供了辅助函数。

<?php

trace(
    'todo.store_item',
    function () use ($title) {
        return \App\Models\TodoListItem::create(['title' => $title]);
    },
    ['tags' => ['title' => $title]]
);

常见标记

此软件包提供了解决器，可以从给定的上下文中解析常见标记，例如 Eloquent 查询构建器、请求对象或响应对象。这些可以在配置中覆盖，如下所示。

/*
 * Resolvers used for generating tags for spans.
 */
'tags' => [
    'middleware' => [
        'request' => \LaravelOpenTracing\Resolvers\RequestTagResolver::class,
        'response' => \LaravelOpenTracing\Resolvers\ResponseTagResolver::class,
    ],
    'query' => \LaravelOpenTracing\Resolvers\QueryTagResolver::class,
],

根据当前配置，有可用于从上下文中推导标记的辅助函数。

<?php
/** @var \Illuminate\Database\Query\Builder $builder */
$tags = query_tags($builder);

/** @var \Illuminate\Http\Request $request */
$tags = request_tags($request);

/** @var \Illuminate\Http\Response $response */
$tags = response_tags($response);

追踪作业

可以通过在配置文件中使用 enable_jobs 布尔值来自动追踪所有作业，或为特定作业进行追踪，请将提供的中间件附加到您希望追踪的作业上。

<?php

// Add to job classes

/**
 * Get the middleware the job should pass through.
 *
 * @return array
 */
public function middleware()
{
    return [new \LaravelOpenTracing\Jobs\Middleware\Tracing];
}

跨服务边界追踪

可以轻松地在服务之间使用跟踪上下文。如果您的应用程序启动了跟踪上下文，则可以将该上下文携带到具有 OpenTracing 兼容实现的另一个服务中。

要自动接受来自其他服务的跟踪上下文，请将跟踪中间件添加到应用程序中，如下所示将其添加到您的 app/Http/Kernel.php 文件中。

<?php

class Kernel extends HttpKernel
{
    protected $middleware = [
        \LaravelOpenTracing\Http\Middleware\Tracing::class,
    ];
}

假设您的应用程序使用 GuzzleHttp 向外部服务发送请求，则可以在创建客户端时使用提供的跟踪处理程序，如下所示。这将自动将必要的跟踪上下文头信息与 HTTP 请求一起发送到外部服务。

<?php

new \GuzzleHttp\Client(
    [
        'handler' => new \LaravelOpenTracing\Propagators\GuzzlePropagator(),
        'headers' => [
            'cache-control' => 'no-cache',
            'content-type' => 'application/json',
        ],
        'base_uri' => 'https:///api/myservice',
        'http_errors' => false
    ]
);

测试

docker run --rm -it -v $(pwd):/app php:7.3-cli-alpine /bin/sh -c 'apk add --no-cache $PHPIZE_DEPS && pecl install xdebug-2.7.2 && cd app && php -dzend_extension=xdebug.so vendor/bin/phpunit'

关于

要求

• PHP 7.3 或更高版本。

贡献

问题和功能请求在 GitHub 上跟踪。

许可

Laravel 的 OpenTracing 在 Apache-2.0 许可下发布。有关详细信息，请参阅 LICENSE 文件。