reimertz / opentracing-php

PHP library for the OpenTracing's API

OpenTracing API for PHP

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.

API overview for those adding instrumentation

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 OtherOpenTracingImplementation\Tracer;
    
    GlobalTracer::setGlobalTracer(Tracer::create());

Note that the GlobalTracer is a singleton itself but all the rest public methods are static so it can be perfectly injected on any DI approach.

Creating a Span given an existing Request

To start a new Span, you can use the StartSpanFromContext method.

    use Psr\Http\Message\RequestInterface;

    ...

    $spanContext = GlobalTracer::globalTracer()->extract(
        Propagator::HTTP_HEADERS,
        HttpHeaders::withHeaders($request->getHeaders())
    );
    
    function doSomething(SpanContext $spanContext, ...) {
        ...
        
        $span = GlobalTracer::globalTracer()->startSpan('operation_name', ChildOf::withContext($spanContext), null);
        
        ...
        
        $span->logFields(
            Log::asString('event', 'soft error'),
            Log::asString('type', 'cache timeout'),
            Log::asInt('waited.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('operation_name');
    ...
    $span->finish();

Creating a (child) Span given an existing (parent) Span

    use OpenTracing\SpanReference\ChildOf;

    function xyz(Span $parentSpan, ...) {
        ...
        $span = GlobalTracer::globalTracer()->startSpan(
            'operation_name',
            ChildOf::withContext($span->context())
        );
        
        $span->finish();
        ...
    }

Serializing to the wire

    use OpenTracing\Carriers\HttpHeaders as HttpHeadersCarrier;
    use OpenTracing\Context;
    use OpenTracing\GlobalTracer;
    
    ...
    
    $tracer = GlobalTracer::globalTracer(); 
    
    $spanContext = $tracer->extract(
        Propagator::HTTP_HEADERS,
        HttpHeaders::withHeaders($request->getHeaders())
    );
    
    try {
        $span = $tracer->startSpan('operation_name', ChildOf::withContext($spanContext), null);

        $client = new GuzzleHttp\Client;
        
        $request = new \GuzzleHttp\Psr7\Request('GET', 'http://myservice');
        
        $tracer->inject(
            $span->context(),
            Propagator::HTTP_HEADERS,
            HttpHeadersCarrier::withHeaders($request->getHeaders())
        )

        $client->send($request);
        ...
    } catch (Exception $e) {
        ...
    }
    ...