PHPackages                             quinluong/tracing-php - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Logging & Monitoring](/categories/logging)
4. /
5. quinluong/tracing-php

ActiveLibrary[Logging & Monitoring](/categories/logging)

quinluong/tracing-php
=====================

Distributed tracing wrapper for php

1.0.1(4y ago)02601PHPPHP >=7.0

Since Dec 11Pushed 4y ago1 watchersCompare

[ Source](https://github.com/quinluong/tracing-php)[ Packagist](https://packagist.org/packages/quinluong/tracing-php)[ RSS](/packages/quinluong-tracing-php/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (13)Used By (0)

tracing-php
===========

[](#tracing-php)

Required reading
----------------

[](#required-reading)

In order to understand the library, one must first be familiar with the [OpenTracing project](http://opentracing.io) and [specification](http://opentracing.io/documentation/pages/spec.html) more specifically.

Installation
------------

[](#installation)

This library can be installed via Composer:

```
composer require quinluong/tracing-php
```

Usage
-----

[](#usage)

### Creating new tracer using TracerFactory

[](#creating-new-tracer-using-tracerfactory)

```
use Tracing\TracerFactory;

// This instance will be saved in TracerFactory internally by tracer_name, we can use it later by TracerFactory::getByName
$tracer = TracerFactory::create('tracer_name', [
    'enable' => true,
    'host_port' => 'agent_host:port',
    'sampler_type' => 'const', // const, probabilistic
    'sampler_value' => 1 // const: 0 / 1, probabilistic: 0 -> 1
]);
```

### Extracting span context from request header

[](#extracting-span-context-from-request-header)

```
use OpenTracing\Formats;

$spanOptions = [
    'tags' => [
        'tag_key_1' => 'tag_value_1',
        'tag_key_2' => 'tag_value_2'
    ]
];

// Extract and use it for next span
$spanContext = $tracer->extract(Formats\TEXT_MAP, getallheaders());

if ($spanContext !== null) {
    $spanOptions['child_of'] = $spanContext;
}

$tracer->startActiveSpan('operation_name', $spanOptions);
```

### Injecting span context into request header

[](#injecting-span-context-into-request-header)

```
use OpenTracing\Formats;

$tracer->inject($span->getContext(), Formats\TEXT_MAP, $arrHeader);
```

### Creating span

[](#creating-span)

For most use cases, it is recommended that you use the `TracerInterface::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->startActiveSpan('request');
...
$scope->close();
```

```
// At controller level
$scope = $tracer->startActiveSpan('controller');
...
$scope->close();
```

```
// At RPC calls level
$scope = $tracer->startActiveSpan('http');
file_get_contents('http://php.net');
$scope->close();
```

When using the `TracerInterface::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 `TracerInterface::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.

#### Creating a child span using automatic active span management

[](#creating-a-child-span-using-automatic-active-span-management)

```
$parent = $tracer->startActiveSpan('parent');
...
/*
 * Since the parent span has been created by using startActiveSpan we don't need
 * to pass a reference for this child span
 */
$child = $tracer->startActiveSpan('my_second_span');
...
$child->close();
...
$parent->close();
```

#### Creating a child span assigning parent manually

[](#creating-a-child-span-assigning-parent-manually)

```
$parent = $tracer->startSpan('parent');
...
$child = $tracer->startSpan('child', [
    'child_of' => $parent
]);
...
$child->finish();
...
$parent->finish();
```

### Tags and logs

[](#tags-and-logs)

```
// Tags are searchable in UI
$span->setTag('http.status', '200');
$span->setTag('http.url', 'abc.com/api/endpoint');

$tracer->startActiveSpan('my_span', [
    'tags' => [
        'foo-1' => 'bar-1',
        'foo-2' => 'bar-2'
        ...
    ]
]);
```

```
// Log information
$span->log([
    'error' => 'HTTP request timeout'
    'event' => 'soft error',
    'type' => 'cache timeout',
    'waiter.millis' => 1500
    ...
]);
```

### Flushing spans

[](#flushing-spans)

PHP as a request scoped language has no simple means to pass the collected spans data to a background process without blocking the main request thread/process. The OpenTracing API makes no assumptions about this, but for PHP that might cause problems for Tracer implementations. This is why the PHP API contains a flush method that allows to trigger a span sending out of process.

```
register_shutdown_function(function() {
    $tracer = TracerFactory::getByName('tracer_name');
    // Flush the tracer to the backend
    if ($tracer !== null) {
        $tracer->flush();
    }
});
```

### Pause and resume

[](#pause-and-resume)

```
$tracer->pause();
...
// This function won't be instrumented
doSomething();
...
$tracer->resume();
```

Semantic conventions
--------------------

[](#semantic-conventions)

###  Health Score

27

—

LowBetter than 49% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity55

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 93.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~31 days

Recently: every ~75 days

Total

12

Last Release

1626d ago

Major Versions

0.0.10 → 1.0.02021-10-28

PHP version history (2 changes)0.0.1PHP >=7.2

0.0.9PHP >=7.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/4dbbedcee406f004f224b3f00c99e0239bf29cceed8a74918b59586af6315ea1?d=identicon)[quinluong](/maintainers/quinluong)

---

Top Contributors

[![quyluongthanh](https://avatars.githubusercontent.com/u/6750222?v=4)](https://github.com/quyluongthanh "quyluongthanh (15 commits)")[![quinluong](https://avatars.githubusercontent.com/u/15945820?v=4)](https://github.com/quinluong "quinluong (1 commits)")

### Embed Badge

![Health badge](/badges/quinluong-tracing-php/health.svg)

```
[![Health](https://phpackages.com/badges/quinluong-tracing-php/health.svg)](https://phpackages.com/packages/quinluong-tracing-php)
```

###  Alternatives

[psr/log

Common interface for logging libraries

10.4k1.2B9.1k](/packages/psr-log)[itsgoingd/clockwork

php dev tools in your browser

5.9k27.6M94](/packages/itsgoingd-clockwork)[graylog2/gelf-php

A php implementation to send log-messages to a GELF compatible backend like Graylog2.

41838.2M137](/packages/graylog2-gelf-php)[bugsnag/bugsnag-psr-logger

Official Bugsnag PHP PSR Logger.

32132.5M2](/packages/bugsnag-bugsnag-psr-logger)[consolidation/log

Improved Psr-3 / Psr\\Log logger based on Symfony Console components.

15462.2M7](/packages/consolidation-log)[datadog/php-datadogstatsd

An extremely simple PHP datadogstatsd client

19124.6M15](/packages/datadog-php-datadogstatsd)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)