Skip to content
A stats collection and distributed tracing framework
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci OpenCensus Stats implementation (#220) Jan 26, 2019
config Build versioned docs (#172) Apr 18, 2018
daemon OpenCensus Stats implementation (#220) Jan 26, 2019
docs
examples OpenCensus Stats implementation (#220) Jan 26, 2019
ext improved opencensus-php dockerfile adding composer+git for easy usage ( Feb 10, 2019
scripts Switch to Circle CI version 2.0 (#176) Apr 19, 2018
src OpenCensus Stats implementation (#220) Jan 26, 2019
tests OpenCensus Stats implementation (#220) Jan 26, 2019
.editorconfig Initial import Aug 1, 2017
.gitignore OpenCensus Stats implementation (#220) Jan 26, 2019
.travis.yml Build versioned docs (#172) Apr 18, 2018
AUTHORS Add comment header to AUTHORS file about looking at revision history (#… May 1, 2018
CODE_OF_CONDUCT.md Initial import Aug 1, 2017
CONTRIBUTING.md Update Contributing instructions (#162) Apr 5, 2018
LICENSE Initial import Aug 1, 2017
README.md Extract exporters (#175) Apr 25, 2018
RELEASING.md Add Version::VERSION constant. StackdriverExporter reports version at… Apr 5, 2018
composer.json OpenCensus Stats implementation (#220) Jan 26, 2019
phpcs-ruleset.xml
phpunit.xml.dist

README.md

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.

CircleCI Packagist PHP-Version

Installation & basic usage

  1. Install the opencensus/opencensus package using composer:

    $ 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.

  2. [Optional]: Install the opencensus extension from PECL:

    $ pecl install opencensus-alpha

    Enable the extension in your php.ini:

    extension=opencensus.so
  3. Initialize a tracer for your application:

    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.

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.

The provided samplers are:

Class Description
NeverSampleSampler Never trace any requests
AlwaysSampleSampler Trace all requests
MultiSampler Check multiple samplers
QpsSampler Trace X requests per second. Requires a PSR-6 cache implementation
ProbabilitySampler Trace X percent of requests.

If you would like to provide your own sampler, create a class that implements SamplerInterface.

Exporters

You can choose different exporters to send the collected traces to.

The provided exporters are:

Class Description Dependency
EchoExporter Output the collected spans to stdout
FileExporter Output JSON encoded spans to a file
JaegerExporter Report traces to Jaeger server via Thrift over UDP opencensus/opencensus-exporter-jaeger
LoggerExporter Exporter JSON encoded spans to a PSR-3 logger
NullExporter No-op
OneLineEchoExporter Output the collected spans to stdout with one-line
StackdriverExporter Report traces to Google Cloud Stackdriver Trace opencensus/opencensus-exporter-stackdriver
ZipkinExporter Report collected spans to a Zipkin server opencensus/opencensus-exporter-zipkin

If you would like to provide your own reporter, create a class that implements ExporterInterface.

Versioning

Packagist

This library follows Semantic Versioning.

Please note it is currently under active development. Any release versioned 0.x.y is subject to backwards incompatible changes at any time.

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.

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.

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

Current Status: Alpha

Contributing

Contributions to this library are always welcome and highly encouraged.

See CONTRIBUTING for more information on how to get started.

Releasing

See RELEASING for more information on releasing new versions.

License

Apache 2.0 - See LICENSE for more information.

Disclaimer

This is not an official Google product.

You can’t perform that action at this time.