whitemerry / phpkin

1.2.7 2017-08-06 10:48 UTC

Requires

• php: >=5.3.0

Requires (Dev)

• phpunit/phpunit: ~5.7

MIT

• Piotr Bugaj

• zipkin
• tracing
• openzipkin

Published on Packagist.org on 2017-08-06 10:51 UTC

README

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

$ composer require whitemerry/phpkin

Upgrading to 2.0

Tracer used to serialize each Span the moment it was added. It now keeps the Span objects and serializes them once, in trace(), which is what makes getSpans() possible. What Zipkin receives is unchanged, but three things behave differently.

addSpan() only accepts Span

Passing anything else throws InvalidArgumentException. Serialization used to happen inside addSpan(), so any object with a toArray() method quietly worked:

// Worked in 1.x by accident, throws in 2.0
$tracer->addSpan($myOwnSpanClass);

If you have such a class, extend Span or build a real Span from it.

Spans are serialized at trace() time

Anything you change on a Span after adding it now ends up in the trace. Sharing one Metadata instance between spans is the case that bites, because Metadata::set() appends:

$metadata = new Metadata();

$metadata->set(Metadata::HTTP_PATH, '/first');
$tracer->addSpan(new Span($firstId, 'First', $firstAnnotations, $metadata));

$metadata->set(Metadata::HTTP_PATH, '/second');
$tracer->addSpan(new Span($secondId, 'Second', $secondAnnotations, $metadata));

In 1.x the first span reported one annotation and the second reported two. In 2.0 both report both. Give each Span its own Metadata to keep the old result.

Tracer::$spans holds Span objects

Only relevant if you extend Tracer and read the protected property - it used to hold arrays. Use getSpans() where you can, and call toArray() yourself if you need the serialized form.

Documentation

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

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

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);

Reading spans back

Spans stay on the tracer, so you can inspect them - handy in tests or when you need to report them somewhere else:

foreach ($tracer->getSpans() as $span) {
    $data = $span->toArray();
}

The span describing the trace itself is built by trace() (its end timestamp is not known before that), so call getSpans() after trace() to get the complete set. When the trace is not sampled nothing is collected and getSpans() stays empty.

Spans are serialized once, by trace(). Anything you change on a Span after addSpan() ends up in the trace - including a Metadata instance shared between spans, which will report every annotation set on it, not only the ones set before that span was added. Give each Span its own Metadata if you don't want that.

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::getSpans();
TracerProxy::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

Take a look at our examples. You need to set B3 header by your own in yours rest/api/guzzle client.

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!

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)

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

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

Inspired by Tolerance