README

OpenTracing 的 PHP 库。

必读内容

为了理解这个库，首先需要熟悉 OpenTracing 项目以及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()`时会自动完成，如前例所示。

如果你不希望在调用`$scope->close()`时自动关闭 Span，则必须在`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 作为父级，并占据其位置。

$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 调用可以实现为一个 NO-OP，对于这些 tracer。

使用`StartSpanOptions`

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

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

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

传播格式

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

Tracer::FORMAT_TEXT_MAP 应将跨度上下文表示为键值映射。没有关于上下文来源和发送到的地方的语义假设。
Tracer::FORMAT_HTTP_HEADERS 应将跨度上下文表示为数组列表中的 HTTP 头行。对于两个上下文细节 "Span-Id" 和 "Trace-Id"，结果将是 ['Span-Id: abc123', 'Trace-Id: def456']。此定义可以直接传递给 curl 和 file_get_contents。
Tracer::FORMAT_BINARY 对数据格式没有假设，除了它是专有的，并且每个跟踪器都可以按自己的方式处理它。

模拟实现

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

帮助完善 API。
作为参考实现。
增强了无供应商单元测试，因为它允许开发者检查跟踪对象，以便对其进行断言。

编码风格

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

许可

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

mix / opentracing

维护者

详细信息