Tracer

This class provides static functions to give you access to the current request's singleton tracer. You should use this class to instrument your code.

The first step, is to configure and start your Tracer. Calling start will collect trace data during your request and report the results at the request using the provided reporter.

Example:

use OpenCensus\Trace\Tracer;
use OpenCensus\Trace\Exporter\EchoExporter;

$reporter = new EchoExporter();
Tracer::start($reporter);

In the above example, every request is traced. This is not advised as it will add some latency to each request. We provide a sampling mechanism via the OpenCensus\Trace\Sampler\SamplerInterface. To add sampling to your request tracer, provide the "sampler" option:

// $cache is a PSR-6 cache implementation
$sampler = new QpsSampler($cache, ['rate' => 0.1]);
Tracer::start($reporter, [
    'sampler' => $sampler
]);

The above uses a query-per-second sampler at 0.1 requests/second. The implementation requires a PSR-6 cache. See OpenCensus\Trace\Sampler\QpsSampler for more information. You may provide your own implementation of OpenCensus\Trace\Sampler\SamplerInterface or use one of the provided.

To trace code, you can use static OpenCensus\Trace\Tracer::inSpan() helper function:

Tracer::start($reporter);
Tracer::inSpan(['name' => 'outer'], function () {
    // some code
    Tracer::inSpan(['name' => 'inner'], function () {
        // some code
    });
    // some code
});

You can also start and finish spans independently throughout your code.

Explicitly tracing spans:

// Creates a detached span
$span = Tracer::startSpan(['name' => 'expensive-operation']);

// Opens a scope that attaches the span to the current context
$scope = Tracer::withSpan($span);
try {
    $pi = calculatePi(1000);
} finally {
    // Closes the scope (ends the span)
    $scope->close();
}

It is recommended that you use the OpenCensus\Trace\Tracer::inSpan() method where you can.