README

Google Trace 库的包装器

仅适用于 psr7 应用程序

安装

$ composer require dkx/google-tracer

基本使用

<?php

use DKX\GoogleTracer\Exporter\GoogleTraceExporter;
use DKX\GoogleTracer\Sampler\AlwaysSampler;
use DKX\GoogleTracer\Tracer;
use Google\Cloud\Trace\TraceClient;

$projectName = 'my-app/production';
$projectVersion = '0.0.1';

$traceClient = new TraceClient();
$exporter = new GoogleTraceExporter($traceClient);
$sampler = new AlwaysSampler();
$tracer = new Tracer($exporter, $sampler, $projectName, $projectVersion);

$trace = $tracer->start();
$request = getCurrentHttpRequestSomehow();

try {
    $response = getCurrentHttpResponseSomehow($request);
    $tracer->finishSuccessfully($trace, $request, $response);
} catch(\Throwable $e) {
    $tracer->finishWithError($trace, $request, $e);
}

创建子跨度

<?php

use DKX\GoogleTracer\Span;

$trace->span('controller', function (Span $span): void {
    $users = $span->span('users.load', function (Span $span): array {
        $users = $span->span('users.load.fromCache', function (Span $span): ?array {
            return tryToLoadUsersFromCache();        
        });
        
        if ($users === null) {
            $users = $span->span('users.load.fromDatabase', function (Span $span): array {
                return loadUsersFromDatabase();
            });

            $span->span('users.load.saveCache', function (Span $span) use ($users): void {
                saveUsersToCache($users);
            });
        }

        return $users;
    });

    var_dump($users);
});

PSR15 中间件

<?php

use DKX\GoogleTracer\Psr15\TracerControllerSpanMiddleware;

$middleware = new TracerControllerSpanMiddleware($trace);

这将自动将 controller 跨度注册到 $trace 中（可以替换为跨度）。创建的跨度将被添加到 HTTP 请求的属性中。

<?php

use DKX\GoogleTracer\Psr15\TracerControllerSpanMiddleware;

/** @var \DKX\GoogleTracer\Span $span */
$span = $request->getAttribute(TracerControllerSpanMiddleware::CONTROLLER_SPAN);
$span->span('inside-of-controller', function (): void {
    // todo: watched span in a controller
});

或者，您可以使用动态中间件，该中间件将从 HTTP 请求属性中加载父跨度或跨度

<?php

use DKX\GoogleTracer\Psr15\TracerControllerSpanDynamicMiddleware;

$request = getCurrentHttpRequestSomehow();
$request->withAttribute('controllerSpanParent', $trace);

$middleware = new TracerControllerSpanDynamicMiddleware('controllerSpanParent');

导出器

• DKX\GoogleTracer\Exporter\GoogleTraceExporter：将跟踪数据保存到 Google Cloud Trace
• DKX\GoogleTracer\Exporter\VoidExporter："什么都不做" 导出器

采样器

• DKX\GoogleTracer\Sampler\AlwaysSampler：保存所有请求的跟踪
• DKX\GoogleTracer\Sampler\NeverSampler：不保存任何跟踪
• DKX\GoogleTracer\Sampler\ProbabilitySampler($rate)：根据概率率（0 <> 1）保存跟踪
• DKX\GoogleTracer\Sampler\QpsSampler($cache, $cacheKey, $rate)：根据每秒查询率（0 <> 1）保存跟踪