README

OpenTracing API的PHP库。

必读

为了理解这个库，您必须首先熟悉OpenTracing项目和更具体地规范。

安装

可以通过Composer安装OpenTracing-PHP

composer require opentracing/opentracing

使用

当使用这个库时，您实际上只需关注几个关键抽象：Tracer::startActiveSpan和Tracer::startSpan方法，Span接口，Scope接口，以及将Tracer绑定到启动时。以下是演示一些重要用例的代码片段：

单例初始化

最简单的起点是设置全局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。

以下是一个使用活动span的线性、两级深的span树示例，在PHP代码中看起来是这样的

// 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函数时，底层tracer使用一个称为作用域管理器的抽象来跟踪当前活动的span。

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

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

如前例所示，当前活动span在调用$scope->close()时自动完成。

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

手动指定父级创建子span

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

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

...

$child->finish();

...

$parent->finish();

使用自动活动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,
]);

刷新Span

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();
});

这是可选的，tracer可以决定立即将完成的span发送到后端。flush调用可以实现为对这些tracer的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::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 对数据格式没有假设，除了它属于私有格式，每个追踪器可以按自己的方式处理。

模拟实现

OpenTracing PHP 附带了一个模拟实现，它有三个用途

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

编码风格

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

许可

所有开源贡献都遵循 Apache-2.0 许可协议。