opencensus/opencensus

OpenCensus Trace Client for PHP

Warning, _(*1)

OpenCensus and OpenTracing have merged to form OpenTelemetry, which serves as the next major version of OpenCensus and OpenTracing., _(*2)

OpenTelemetry has now reached feature parity with OpenCensus, with tracing and metrics SDKs available in .NET, Golang, Java, NodeJS, and Python. All OpenCensus Github repositories, except census-instrumentation/opencensus-python, will be archived on July 31st, 2023. We encourage users to migrate to OpenTelemetry by this date., _(*3)

To help you gradually migrate your instrumentation to OpenTelemetry, bridges are available in Java, Go, Python, and JS. Read the full blog post to learn more., _(*4)

OpenCensus for PHP - A stats collection and distributed tracing framework

Census for PHP. Census provides a framework to measure a server's resource usage and collect performance stats. This repository contains PHP related utilities and supporting software needed by Census., _(*5)

, _(*6)

• API Documentation
• Integration Documentation

Installation & basic usage

1. Install the opencensus/opencensus package using composer:, _(*7)

   $ composer require opencensus/opencensus:~0.2
   

   IMPORTANT: Please ensure your version is >= 0.2.0. There is a potential security vulnerability in < 0.2.0., _(*8)

2. [Optional]: Install the opencensus extension from PECL:, _(*9)

   $ pecl install opencensus-alpha
   

   Enable the extension in your php.ini:, _(*10)

   extension=opencensus.so
   

3. Initialize a tracer for your application:, _(*11)

   use OpenCensus\Trace\Tracer;
   use OpenCensus\Trace\Exporter\EchoExporter;
   
   Tracer::start(new EchoExporter());
   

Usage

To add tracing to a block of code, you can use the closure/callable form or explicitly open and close spans yourself., _(*12)

Closure/Callable (preferred)

$pi = Tracer::inSpan(['name' => 'expensive-operation'], function() {
    // some expensive operation
    return calculatePi(1000);
});

$pi = Tracer::inSpan(['name' => 'expensive-operation'], 'calculatePi', [1000]);

Explicit Span Management

// 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();
}

Customization

Samplers

You can specify different samplers when initializing a tracer. The default sampler is the AlwaysSampleSampler which will attempt to trace all requests., _(*13)

The provided samplers are:, _(*14)

If you would like to provide your own sampler, create a class that implements SamplerInterface., _(*15)

Exporters

You can choose different exporters to send the collected traces to., _(*16)

The provided exporters are:, _(*17)

If you would like to provide your own reporter, create a class that implements ExporterInterface., _(*18)

Versioning

, _(*19)

This library follows Semantic Versioning., _(*20)

Please note it is currently under active development. Any release versioned 0.x.y is subject to backwards incompatible changes at any time., _(*21)

GA: Libraries defined at a GA quality level are stable, and will not introduce backwards-incompatible changes in any minor or patch releases. We will address issues and requests with the highest priority., _(*22)

Beta: Libraries defined at a Beta quality level are expected to be mostly stable and we're working towards their release candidate. We will address issues and requests with a higher priority., _(*23)

Alpha: Libraries defined at an Alpha quality level are still a work-in-progress and are more likely to get backwards-incompatible updates., _(*24)

Current Status: Alpha, _(*25)

Contributing

Contributions to this library are always welcome and highly encouraged., _(*26)

See CONTRIBUTING for more information on how to get started., _(*27)

Releasing

See RELEASING for more information on releasing new versions., _(*28)

License

Apache 2.0 - See LICENSE for more information., _(*29)

Disclaimer

This is not an official Google product., _(*30)