Propagation
You are viewing the English version of this page because it has not yet been fully translated. Interested in helping out? See Contributing.
通过上下文传播,信号可以彼此关联,而不受其生成位置的限制。尽管上下文传播并不限于链路跟踪, 但它允许链路在跨越进程和网络边界的任意分布式服务之间构建系统的因果关系信息。
在绝大多数用例中,原生支持 OpenTelemetry 的库或插桩库会自动为你在服务之间传播跟踪上下文。 只有在极少数情况下,你才需要手动传播上下文。
要了解更多,请参阅上下文传播。
Propagation is the mechanism that moves data between services and processes. Although not limited to tracing, propagation allows traces to build causal information about a system across services that are arbitrarily distributed across process and network boundaries.
OpenTelemetry provides a text-based approach to propagate context to remote services using the W3C Trace Context HTTP headers.
Automatic context propagation
Auto-instrumentation exists for some of the most popular frameworks, libraries, and PHP extensions. Many of them perform incoming and/or outgoing context propagation, and can be discovered through the Registry or Packagist.
Use auto-instrumentation or instrumentation libraries to propagate context. Although you can propagate context manually, the PHP auto-instrumentation and instrumentation libraries are well-tested and easier to use.
Incoming requests
Context propagation can be automatically handled in a number of ways:
- by using a supported PHP Framework (for example: Laravel, Symfony, Slim) along with its corresponding auto-instrumentation package
- by implementing the PSR-15
RequestHandlerInterface
in your code, along with its corresponding auto-instrumentation package - by using the experimental auto root span feature
Outgoing requests
Auto-instrumentation packages for HTTP clients and interfaces automatically inject W3C tracecontext headers to outgoing HTTP requests include.
Manual context propagation
In some cases, it is not possible to propagate context using an instrumentation library. There might not be an instrumentation library that matches a library you’re using to have services communicate with each other. Or you might have requirements that instrumentation libraries cannot fulfill, even if they exist.
When you must propagate context manually, use the context API.
The following snippet shows an example of an outgoing HTTP request:
$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();
}
Similarly, use the text-based approach to read the W3C Trace Context from incoming requests. The following presents an example of processing an incoming HTTP request:
$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();
}
Next steps
To learn more about propagation, read the Propagators API specification.
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!