PHPackages                             whitemerry/phpkin - 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. [Utility & Helpers](/categories/utility)
4. /
5. whitemerry/phpkin

ActiveLibrary[Utility & Helpers](/categories/utility)

whitemerry/phpkin
=================

PHP Zipkin implementation

1.2.7(8y ago)7726.5k18[7 issues](https://github.com/whitemerry/phpkin/issues)[1 PRs](https://github.com/whitemerry/phpkin/pulls)3MITPHPPHP >=5.3.0

Since May 5Pushed 5y ago3 watchersCompare

[ Source](https://github.com/whitemerry/phpkin)[ Packagist](https://packagist.org/packages/whitemerry/phpkin)[ RSS](/packages/whitemerry-phpkin/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (1)Versions (12)Used By (3)

phpkin
======

[](#phpkin)

[![Software License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265 "Software License")](LICENSE)[![Latest Stable Version](https://camo.githubusercontent.com/8cb827eef03cede3eabed7a9b16a7ac1c0aca336a1bfc7ef7dc55ab6c326744f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f77686974656d657272792f7068706b696e2e7376673f7374796c653d666c61742d737175617265266c6162656c3d737461626c65 "Latest Stable Version")](https://packagist.org/packages/whitemerry/phpkin) [![OpenTracing Badge](https://camo.githubusercontent.com/0c34d42089573bfc38911b30f4fd5c7d3ef20dd05d0849b390643ccbf19695da/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4f70656e54726163696e672d656e61626c65642d626c75652e737667)](http://opentracing.io)[![Maintainability](https://camo.githubusercontent.com/134ca25fff306e48115d84a4dfcd39f29aadb702711894c2339133066b843253/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f61373835666137386563303639333934623231642f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/whitemerry/phpkin/maintainability)[![Test Coverage](https://camo.githubusercontent.com/f1d1089d4a4e3c8d3fbcbc97f9313da162cac90df2c8c7c7ad461e2bf2a408a3/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f61373835666137386563303639333934623231642f746573745f636f766572616765)](https://codeclimate.com/github/whitemerry/phpkin/test_coverage)

First ***production ready***, simple and full Zipkin implementation without dependencies.

Compatible with both front and back-end applications and respects B3 Propagation.

Installing via Composer
-----------------------

[](#installing-via-composer)

```
$ composer require whitemerry/phpkin
```

Documentation
-------------

[](#documentation)

#### Short implementation information

[](#short-implementation-information)

In this project BinaryAnnotations are Metadata and annotations are replaced by AnnotationBlock witch allow you to create Annotations for Spans faster, and cleaner. All of these methods have more parameters than used here, read PHPDocs and remember, you can change everything by implementing interfaces or extending classes.

#### Let's get started

[](#lets-get-started)

First, very important step is defining your service meta-information for tracer:

```
$endpoint = new Endpoint(
    'My application', // Application name
    '127.0.0.1', // Current application IP address
    '80' // Current application port (default 80)
);
```

Next, define storage for traces - currently two types are supported - SimpleHttpLogger witch automatically sends trace data to Zipkin's service and FileLogger (you can read more about this below):

```
$logger = new SimpleHttpLogger([
    'host' => 'http://192.168.33.11:9411' // Zipkin's API host with schema (http://) and without trailing slash
]);
```

***Now you can initialize Tracer!***

For front-end applications (Source for TraceId, SpanId and Sampled for other microservices):

```
$tracer = new Tracer(
    'http://localhost/login', // Trace name
    $endpoint, // Your application meta-information
    $logger // Logger used to store/send traces
);
$tracer->setProfile(Tracer::FRONTEND);
```

For back-end applications / microservices (Consumer of existing TraceId, SpanId and Sampled)

```
$traceId = null;
if (!empty($_SERVER['HTTP_X_B3_TRACEID'])) {
    $traceId = new TraceIdentifier($_SERVER['HTTP_X_B3_TRACEID']);
}

$traceSpanId = null;
if (!empty($_SERVER['HTTP_X_B3_SPANID'])) {
    $traceSpanId = new SpanIdentifier($_SERVER['HTTP_X_B3_SPANID']);
}

$isSampled = null;
if (!empty($_SERVER['HTTP_X_B3_SAMPLED'])) {
    $isSampled = (bool) $_SERVER['HTTP_X_B3_SAMPLED'];
}

$tracer = new Tracer(
    'http://localhost/login',
    $endpoint,
    $logger,
    $sampled,
    $traceId,
    $traceSpanId
);
$tracer->setProfile(Tracer::BACKEND);
```

All these lines must be initialized as soon as possible, in frameworks bootstrap.php is good place.

There are more parameters with descriptions in ***PHPDocs***! For example, if you are front-end application you can use PercentageSampler, tool for toggling tracing logs (You don't need to log everything).

As last step just trigger trace method from $tracer, for example in shutdown event of your framework, or at the end of index.php

```
$tracer->trace();
```

Now as you can see, you have new entries in the Zipkin's UI! :)

#### Adding spans to trace

[](#adding-spans-to-trace)

As you already now, in Zipkin, you can store and visualize communication between 2 services (for example databases, microservices). So, you need to create Span (Zipkin's block of information about request):

```
// Before request - read current timestamp in zipkin format
$requestStartTimestamp = zipkin_timestamp();
$spanIdentifier = new SpanIdentifier();

/*
...
Request logic
Remember, you need to add B3 headers to your request:
X-B3-TraceId = TracerInfo::getTraceId();
X-B3-SpanId = $spanIdentifier;
X-B3-Sampled = TracerInfo::isSampled();
*/

$endpoint = new Endpoint(
    'Accounts microservice', // Name of service you're connecting with
    '127.0.1.1', // This service Ip
    '8000' // And port
);

$annotationBlock = new AnnotationBlock(
    $endpoint,
    $requestStartTimestamp
);

$span = new Span(
    $spanIdentifier,
    'Authorize user',
    $annotationBlock
);
```

And add to tracer

```
$tracer->addSpan($span);
```

#### Calling tracer statically

[](#calling-tracer-statically)

You can get access to tracer statically, in every place of your project, just init TracerProxy:

```
$tracer = new Tracer(...); // Your tracer instance
TracerProxy::init($tracer);
```

Now you have access to methods like:

```
TracerProxy::addSpan($span);
TracerProxy::trace();
```

#### Where do i have information about this trace?

[](#where-do-i-have-information-about-this-trace)

All meta information are in static class TracerInfo

```
TracerInfo::getTraceId(); // TraceId - X-B3-TraceId
TracerInfo::getTraceSpanId(); // ParentId - X-B3-ParentId
TracerInfo::isSampled(); // Sampled - X-B3-Sampled
```

#### Making requests to other service

[](#making-requests-to-other-service)

Take a look at our [examples](https://github.com/whitemerry/phpkin/tree/master/example). You need to set B3 header by your own in yours rest/api/guzzle client.

#### Differences between loggers

[](#differences-between-loggers)

SimpleHttpLogger - Allows you to try zipkin right away, by uploading logs at the end of user request to webiste. However, it will delay the response back to the user.

FileLogger - Allows you to setup asynchronous reporting to zipkin. While this is a synchronous write to disk, in practice latency impact to callers is minimal, but you need to write *upload to zipkin* tool by your own.

For more info read [this ticket](https://github.com/whitemerry/phpkin/issues/2)!

#### Are logs automatically uploaded to Zipkin?

[](#are-logs-automatically-uploaded-to-zipkin)

For SimpleHttpLogger, short answer, ***yes***

For FileLogger, bit logner answer, you need to upload logs from *zipkin.log* to Zipkin by your own, for example by cron working in background making POST's to the [Zipkin (API)](http://zipkin.io/zipkin-api/#/paths/%252Fspans/post)

Unit tests
----------

[](#unit-tests)

Code Coverage (Generated by PHPUnit):

- Lines: 70.35% (140 / 199)
- Functions and Methods: 52.08% (25 / 48)
- Classes and Traits: 58.33% (7 / 12)

TODO
----

[](#todo)

- AsyncHttpLogger (Based on CURL)
- *Upload to zipkin* cron for FileLogger

---

Inspired by [Tolerance](https://github.com/Tolerance/Tolerance)

###  Health Score

39

—

LowBetter than 86% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity38

Limited adoption so far

Community21

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 94% 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 ~10 days

Recently: every ~22 days

Total

10

Last Release

3208d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/af2e5909a2abe227362f45afb849e5f174903b022f7476555b4647bce739a76a?d=identicon)[whitemerry](/maintainers/whitemerry)

---

Top Contributors

[![whitemerry](https://avatars.githubusercontent.com/u/18561921?v=4)](https://github.com/whitemerry "whitemerry (47 commits)")[![sokac](https://avatars.githubusercontent.com/u/994028?v=4)](https://github.com/sokac "sokac (2 commits)")[![reimertz](https://avatars.githubusercontent.com/u/625287?v=4)](https://github.com/reimertz "reimertz (1 commits)")

---

Tags

opentracingphp-zipkintracingzipkintracingzipkinopenzipkin

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/whitemerry-phpkin/health.svg)

```
[![Health](https://phpackages.com/badges/whitemerry-phpkin/health.svg)](https://phpackages.com/packages/whitemerry-phpkin)
```

###  Alternatives

[openzipkin/zipkin

A Zipkin instrumentation for PHP

2774.3M36](/packages/openzipkin-zipkin)[napp/xray-laravel

AWS X-Ray for Laravel applications.

61407.3k](/packages/napp-xray-laravel)[vinelab/tracing-laravel

Distributed tracing for Laravel made easy

80118.7k1](/packages/vinelab-tracing-laravel)

PHPackages © 2026

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