传播

PHP API 的上下文传播

传播是将数据在服务和进程之间移动的机制。尽管不仅限于跟踪，但它使得跟踪能够在任意分布在进程和网络边界上的服务之间构建系统的因果信息。

OpenTelemetry 提供了一种基于文本的方法，使用W3C Trace Context HTTP headers来传播上下文到远程服务。

使用框架和库进行上下文传播

一些流行的PHP框架（例如Symfony，Laravel和Slim）和HTTP库提供了自动工具，用于传播传入和传出的HTTP请求的上下文。

我们强烈建议您使用自动工具或仪表库来传播上下文。虽然手动传播上下文是可能的，但PHP自动工具和仪表库经过了充分测试，更易于使用。

传入

符合PSR-15 RequestHandlerInterface的框架自动工具将自动提取W3C tracecontext headers，创建一个根跨度，并为根跨度设置一个远程父跨度。

composer require open-telemetry/opentelemetry-auto-psr15

传出

PSR-18自动工具将自动为实现了PSR-18接口的任何库的传出HTTP请求应用W3C tracecontext headers。

composer require open-telemetry/opentelemetry-auto-psr18

手动使用 W3C Trace Context 进行传播

在某些情况下，使用仪表库无法进行上下文传播。您可能没有一个与您使用的库匹配的仪表库，以便服务之间进行通信。或者，即使存在仪表库，您可能也有无法满足的要求。

当您必须手动传播上下文时，可以使用上下文 API。

下面是一个传出 HTTP 请求的示例：

$request = new Request('GET', 'http://localhost:8080/resource');
$outgoing = $tracer->spanBuilder('/resource')->setSpanKind(SpanKind::CLIENT)->startSpan();
$outgoing->setAttribute(TraceAttributes::HTTP_METHOD, $request->getMethod());
$outgoing->setAttribute(TraceAttributes::HTTP_URL, (string) $request->getUri());

$carrier = [];
TraceContextPropagator::getInstance()->inject($carrier);
foreach ($carrier as $name => $value) {
    $request = $request->withAddedHeader($name, $value);
}
try {
    $response = $client->send($request);
} finally {
    $outgoing->end();
}

类似地，可以使用基于文本的方法从传入请求中读取 W3C Trace Context。下面是处理传入 HTTP 请求的示例：

$request = ServerRequestCreator::createFromGlobals();
$context = TraceContextPropagator::getInstance()->extract($request->getHeaders());
$root = $tracer->spanBuilder('HTTP ' . $request->getMethod())
    ->setStartTimestamp((int) ($request->getServerParams()['REQUEST_TIME_FLOAT'] * 1e9))
    ->setParent($context)
    ->setSpanKind(SpanKind::KIND_SERVER)
    ->startSpan();
$scope = $root->activate();
try {
    /* do stuff */
} finally {
    $root->end();
    $scope->detach();
}

最后修改 December 13, 2023: improve glossary translation (46f8201b)