moolex / opentracing
OpenTracing API for PHP
Requires
- php: ^5.6||^7.0
Requires (Dev)
- phpunit/phpunit: ~5.7.19
- squizlabs/php_codesniffer: 3.*
This package is auto-updated.
Last update: 2024-10-17 20:45:22 UTC
README
PHP library for the OpenTracing's API.
Required Reading
In order to understand the library, one must first be familiar with the OpenTracing project and specification more specifically.
Installation
OpenTracing-PHP can be installed via Composer:
composer require opentracing/opentracing
Usage
When consuming this library one really only need to worry about a couple of key
abstractions: the Tracer::startSpan
method, the Span
interface, and binding
a Tracer
at bootstrap time. Here are code snippets demonstrating some important
use cases:
Singleton initialization
The simplest starting point is to set the global tracer. As early as possible, do:
use OpenTracing\GlobalTracer; use AnOpenTracingImplementation\MyTracer; GlobalTracer::set(new MyTracer());
Creating a Span given an existing Request
To start a new Span
, you can use the StartSpanFromContext
method.
use OpenTracing\Formats; use OpenTracing\GlobalTracer; ... $spanContext = GlobalTracer::get()->extract( Formats\HTTP_HEADERS, $request->getHeaders() ); function doSomething(SpanContext $spanContext, ...) { ... $span = GlobalTracer::get()->startSpan('my_span', [ 'child_of' => $spanContext, ]); ... $span->log([ 'event' => 'soft error', 'type' => 'cache timeout', 'waiter.millis' => 1500, ]) $span->finish(); }
Starting an empty trace by creating a "root span"
It's always possible to create a "root" Span
with no parent or other causal
reference.
$span = $tracer->startSpan('my_span'); ... $span->finish();
Creating a (child) Span given an existing (parent) Span
function xyz(Span $parentSpan, ...) { ... $span = GlobalTracer::get()->startSpan( 'my_span', [ 'child_of' => $parentSpan, ] ); $span->finish(); ... }
Serializing to the wire
use OpenTracing\GlobalTracer; use OpenTracing\Formats; ... $tracer = GlobalTracer::get(); $spanContext = $tracer->extract( Formats\HTTP_HEADERS, $request->getHeaders() ); try { $span = $tracer->startSpan('my_span', ['child_of' => $spanContext]); $client = new GuzzleHttp\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) { ... } ...
Deserializing from the wire
When using http header for context propagation you can use either the Request
or the $_SERVER
variable:
use OpenTracing\GlobalTracer; use OpenTracing\Formats; $request = Request::createFromGlobals(); $tracer = GlobalTracer::get(); $spanContext = $tracer->extract(Formats\HTTP_HEADERS, $request->getHeaders()); $tracer->startSpan('my_span', [ 'child_of' => $spanContext, ]);
Flushing Spans
PHP as a request scoped language has no simple means to pass the collected spans
data to a background process without blocking the main request thread/process.
The OpenTracing API makes no assumptions about this, but for PHP that might
cause problems for Tracer implementations. This is why the PHP API contains a
flush
method that allows to trigger a span sending out of process.
use OpenTracing\GlobalTracer; // Do application work, buffer spans in memory $application->run(); fastcgi_finish_request(); $tracer = GlobalTracer::get(); $tracer->flush(); // release buffer to backend
This is optional, tracers can decide to immediately send finished spans to a backend. The flush call can be implemented as a NO-OP for these tracers.
Using Span Options
Passing options to the pass can be done using either an array or the SpanOptions wrapper object. The following keys are valid:
start_time
is a float, int or\DateTime
representing a timestamp with arbitrary precision.child_of
is an object of typeOpenTracing\SpanContext
orOpenTracing\Span
.references
is an array ofOpenTracing\Reference
.tags
is an array with string keys and scalar values that represent OpenTracing tags.
$span = $tracer->createSpan('my_span', [ 'child_of' => $spanContext, 'tags' => ['foo' => 'bar'], 'start_time' => time(), ]);
Propagation Formats
The propagation formats should be implemented consistently across all tracers. If you want to implement your own format, then don't reuse the existing constants. Tracers will throw an exception if the requested format is not handled by them.
-
Tracer::FORMAT_TEXT_MAP
should represents the span context as a key value map. There is no assumption about the semantics where the context is coming from and sent to. -
Tracer::FORMAT_HTTP_HEADERS
should represent the span context as HTTP header lines in an array list. For two context details "Span-Id" and "Trace-Id", the result would be['Span-Id: abc123', 'Trace-Id: def456']
. This definition can be passed directly tocurl
andfile_get_contents
. -
Tracer::FORMAT_BINARY
makes no assumptions about the data format other than it is proprietary and each Tracer can handle it as it wants.
Coding Style
Opentracing PHP follows the PSR-2 coding standard and the PSR-4 autoloading standard.