vantt / opentracing-jaeger-php
php opentracing client for jaeger
Requires
- php: ^7.1||^8.0
- packaged/thrift: 0.10.0
- vantt/opentracing-php: ^1.1.0
Requires (Dev)
- phpunit/php-code-coverage: ^6.1||^9.1
- phpunit/phpunit: ^6.5.14 || ^7.0 || ^9.0
Replaces
- jukylin/jaeger-php: ^2.1.3
This package is auto-updated.
Last update: 2024-10-19 16:18:44 UTC
README
jaeger-php
Install
Install via composer.
composer config minimum-stability dev
composer require vantt/opentracing-jaeger-php
Init Jaeger-php
$config = Config::getInstance(); $tracer = $config->initTracer('example', '0.0.0.0:6831');
128bit
$config->gen128bit();
Extracting span context from request header
$rootContext = $tracer->extract(Formats\TEXT_MAP, getallheaders());
Injecting span context into request header
use OpenTracing\Formats; $arrHeader = []; $tracer->inject($span->getContext(), Formats\TEXT_MAP, $arrHeader); $httpClient->request($url, $arrHeader);
Usage
Using SpanBuilder
This library extends the original api to add a new method buildSpan(operationName):SpanBuilderInterface
.
When consuming this library one really only need to worry about the buildSpan(operationName)
on the $tracer
instance: Tracer::buildSpan(operationName)
With SpanBuilder, we can leverage the power of editor to do auto code completion for us with following APIs:
asChildOf($parentContext)
is an object of typeOpenTracing\SpanContext
orOpenTracing\Span
.withStartTimestamp(time())
is a float, int or\DateTime
representing a timestamp with arbitrary precision.withTag(key,val)
is an array with string keys and scalar values that represent OpenTracing tags.ignoreActiveSpan(bool)
finishSpanOnClose()
is a boolean that determines whether a span should be finished or not when the scope is closed.addReference()
Here are code snippets demonstrating some important use cases:
$rootContext = $tracer->extract(Formats\TEXT_MAP, getallheaders()); $span = $tracer->buildSpan('my_span') ->asChildOf($rootContext) ->withTag('foo', 'bar') ->withStartTimestamp(time()) ->start(); $scope = $tracer->buildSpan('my_span') ->asChildOf($rootContext) ->withTag('foo', 'bar') ->withStartTimestamp(time()) ->startActive();
Creating a Span given an existing Request
To start a new Span
, you can use the startSpan
method.
use OpenTracing\Formats; use OpenTracing\GlobalTracer; ... // extract the span context $spanContext = GlobalTracer::get()->extract( Formats\TEXT_MAP, getallheaders() ); function doSomething() { ... // start a new span called 'my_span' and make it a child of the $spanContext $span = GlobalTracer::get()->buildSpan('my_operation_span_name') ->start(); ... // add some logs to the span $span->log([ 'event' => 'soft error', 'type' => 'cache timeout', 'waiter.millis' => 1500, ]); // finish the the span $span->finish(); }
Starting a new trace by creating a "root span"
It's always possible to create a "root" Span
with no parent or other causal reference.
$span = $tracer->buildSpan('my_first_span')->start(); ... $span->finish();
Active Spans and Scope Manager
For most use cases, it is recommended that you use the Tracer::startActiveSpan
function for
creating new spans.
An example of a linear, two level deep span tree using active spans looks like this in PHP code:
// At dispatcher level $scope = $tracer->buildSpan('request')->start(); ... $scope->close();
// At controller level $scope = $tracer->buildSpan('controller')->startActive(); ... $scope->close();
// At RPC calls level $scope = $tracer->buildSpan('http')->startActive(); file_get_contents('http://php.net'); $scope->close();
When using the Tracer::startActiveSpan
function the underlying tracer uses an
abstraction called scope manager to keep track of the currently active span.
Starting an active span will always use the currently active span as a parent. If no parent is available, then the newly created span is considered to be the root span of the trace.
Unless you are using asynchronous code that tracks multiple spans at the same
time, such as when using cURL Multi Exec or MySQLi Polling it is recommended that you
use Tracer::startActiveSpan
everywhere in your application.
The currently active span gets automatically finished when you call $scope->close()
as you can see in the previous examples.
If you don't want a span to automatically close when $scope->close()
is called
then you must specify 'finish_span_on_close'=> false,
in the $options
argument of startActiveSpan
.
Creating a child span assigning parent manually
$tracer = GlobalTracer::get(); $parent = $tracer->startSpan('parent'); $child = $tracer->buildSpan('child_operation') ->asChildOf($parent) ->start(); ... $child->finish(); ... $parent->finish();
Creating a child span using automatic active span management
Every new span will take the active span as parent and it will take its spot.
$parent = GlobalTracer::get()->buildSpan('parent')->startActive(); ... /* * 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()->buildSpan('my_second_span')->startActive(); ... $child->close(); ... $parent->close();
Serializing to the wire
use GuzzleHttp\Client; use OpenTracing\Formats; ... $tracer = GlobalTracer::get(); $spanContext = $tracer->extract( Formats\HTTP_HEADERS, getallheaders() ); try { $span = $tracer->buildSpan('my_span')->asChildOf($spanContext)->start(); $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) { ... } ...
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; $tracer = GlobalTracer::get(); $spanContext = $tracer->extract(Formats\TEXT_MAP, getallheaders()); $tracer->buildSpan('my_span')->asChildOf($spanContext)->startActive();
Start Span
$serverSpan = $tracer->startSpan('example HTTP', ['child_of' => $spanContext]);
Distributed context propagation
$serverSpan->addBaggageItem("version", "2.0.0");
Inject into Superglobals
$clientTrace->inject($clientSpan1->spanContext, Formats\TEXT_MAP, $_SERVER);
Tags and Log
// tags are searchable in Jaeger UI $span->setTag('http.status', '200'); // log record $span->log(['error' => 'HTTP request timeout']);
Close Tracer
$config->setDisabled(true);
Zipkin B3 Propagation
no support for Distributed context propagation
$config::$propagator = \Jaeger\Constants\PROPAGATOR_ZIPKIN;
Finish span and flush Tracer
$span->finish(); $config->flush();
Features
-
Transports
- via Thrift over UDP
-
Sampling
- ConstSampler
- ProbabilisticSampler