README

PHP 的 OpenTracing API 库。

必读

为了理解库，首先必须熟悉 OpenTracing 项目 以及具体的 规范。

安装

可以通过 Composer 安装 OpenTracing-PHP。

composer require opentracing/opentracing

使用

当使用此库时，你实际上只需要关注几个关键抽象：`Tracer::startActiveSpan` 和 `Tracer::startSpan` 方法，`Span` 接口，`Scope` 接口，以及在引导时绑定 `Tracer`。以下是一些重要用例的代码片段

单例初始化

最简单的起点是设置全局追踪器。尽可能早地执行

use OpenTracing\GlobalTracer;

GlobalTracer::set(new MyTracerImplementation());

根据现有请求创建 Span

要启动新的 `Span`，可以使用 `startSpan` 方法。

use OpenTracing\Formats;
use OpenTracing\GlobalTracer;

...

// extract the span context
$spanContext = GlobalTracer::get()->extract(
    Formats\HTTP_HEADERS,
    getallheaders()
);

function doSomething() {
    ...

    // start a new span called 'my_span' and make it a child of the $spanContext
    $span = GlobalTracer::get()->startSpan('my_span', ['child_of' => $spanContext]);

    ...
    
    // add some logs to the span
    $span->log([
        'event' => 'soft error',
        'type' => 'cache timeout',
        'waiter.millis' => 1500,
    ])

    // finish the the span
    $span->finish();
}

通过创建“根 Span”来启动新的跟踪

始终可以创建一个没有任何父级或其他因果引用的“根”`Span`。

$span = $tracer->startSpan('my_first_span');
...
$span->finish();

活动 Span 和范围管理器

对于大多数用例，建议使用 `Tracer::startActiveSpan` 函数来创建新的 Span。

在 PHP 代码中，使用活动 Span 的线性、两层深的 Span 树的示例如下

// At dispatcher level
$scope = $tracer->startActiveSpan('request');
...
$scope->close();

// At controller level
$scope = $tracer->startActiveSpan('controller');
...
$scope->close();

// At RPC calls level
$scope = $tracer->startActiveSpan('http');
file_get_contents('https://php.ac.cn');
$scope->close();

当使用 `Tracer::startActiveSpan` 函数时，底层追踪器使用一个称为范围管理器的抽象来跟踪当前活动 Span。

启动活动 Span 总是使用当前活动 Span 作为父级。如果没有父级可用，则新创建的 Span 被认为是跟踪的根 Span。

除非您正在使用跟踪多个 Span 的异步代码，例如在使用 cURL Multi Exec 或 MySQLi Polling 时，否则建议您在应用程序的每个地方都使用 `Tracer::startActiveSpan`。

当调用 `$scope->close()` 时，当前活动 Span 会自动完成，就像在前面的示例中看到的那样。

如果您不希望 Span 在调用 `$scope->close()` 时自动关闭，则必须在 `startActiveSpan` 的 `$options` 参数中指定 `‘finish_span_on_close’ => false`。

手动分配父span创建子span

$parent = GlobalTracer::get()->startSpan('parent');

$child = GlobalTracer::get()->startSpan('child', [
    'child_of' => $parent
]);

...

$child->finish();

...

$parent->finish();

使用自动活动span管理创建子span

每个新的span都会将活动span作为父span，并占据其位置。

$parent = GlobalTracer::get()->startActiveSpan('parent');

...

/*
 * Since the parent span has been created by using startActiveSpan we don't need
 * to pass a reference for this child span
 */
$child = GlobalTracer::get()->startActiveSpan('my_second_span');

...

$child->close();

...

$parent->close();

序列化到线路上

use GuzzleHttp\Client;
use OpenTracing\Formats;

...

$tracer = GlobalTracer::get();

$spanContext = $tracer->extract(
    Formats\HTTP_HEADERS,
    getallheaders()
);

try {
    $span = $tracer->startSpan('my_span', ['child_of' => $spanContext]);

    $client = new Client;

    $headers = [];

    $tracer->inject(
        $span->getContext(),
        Formats\HTTP_HEADERS,
        $headers
    );

    $request = new \GuzzleHttp\Psr7\Request('GET', 'http://myservice', $headers);
    $client->send($request);
    ...

} catch (\Exception $e) {
    ...
}
...

从线路上反序列化

当使用http头进行上下文传播时，可以使用Request或$_SERVER变量。

use OpenTracing\GlobalTracer;
use OpenTracing\Formats;

$tracer = GlobalTracer::get();
$spanContext = $tracer->extract(Formats\HTTP_HEADERS, getallheaders());
$tracer->startSpan('my_span', [
    'child_of' => $spanContext,
]);

刷新Spans

PHP作为一个请求作用域的语言，没有简单的方法在阻塞主请求线程/进程的情况下将收集到的span数据传递给后台进程。OpenTracing API对此没有假设，但对于PHP来说，这可能会对Tracer实现造成问题。这就是为什么PHP API包含一个flush方法，允许触发一个span发送出进程。

use OpenTracing\GlobalTracer;

$application->run();

register_shutdown_function(function() {
    /* Flush the tracer to the backend */
    $tracer = GlobalTracer::get();
    $tracer->flush();
});

这是可选的，tracers可以决定立即将完成的span发送到后端。对于这些tracers，flush调用可以实施为NO-OP。

使用StartSpanOptions

传递选项可以使用数组或SpanOptions包装对象。以下键是有效的

• start_time是一个浮点数、整数或表示任意精度时间戳的\DateTime。
• child_of是类型为OpenTracing\SpanContext或OpenTracing\Span的对象。
• references是OpenTracing\Reference数组。
• tags是一个具有字符串键和标量值的数组，表示OpenTracing标签。
• finish_span_on_close是一个布尔值，用于确定当作用域关闭时是否应该完成span。

$span = $tracer->startActiveSpan('my_span', [
    'child_of' => $spanContext,
    'tags' => ['foo' => 'bar'],
    'start_time' => time(),
]);

传播格式

传播格式应在所有tracer中一致实现。如果您想实现自己的格式，请不要重用现有的常量。如果tracer无法处理请求的格式，则会抛出异常。

• Tracer::FORMAT_TEXT_MAP应将span上下文表示为一个键值映射。没有关于上下文来自何处和发送到何处的语义假设。

• Tracer::FORMAT_HTTP_HEADERS应将span上下文表示为HTTP头行数组。对于两个上下文细节"Span-Id"和"Trace-Id"，结果将是['Span-Id: abc123', 'Trace-Id: def456']。此定义可以直接传递给curl和file_get_contents。

• Tracer::FORMAT_BINARY对数据格式没有假设，除了它是专有的并且每个tracer都可以按照自己的方式处理它。

模拟实现

OpenTracing PHP附带了一个模拟实现，它有三个目的

1. 帮助完善API。
2. 作为一个参考实现。
3. 增强了无厂商依赖的单元测试，因为它允许开发者检查追踪对象，以便对它们进行断言。

编码风格

OpenTracing PHP 遵循 PSR-2 编码标准和 PSR-4 自动加载标准。

许可证

所有开源贡献均受 Apache-2.0 许可证 的约束。