README

A Zkteko distributed tracing library for Laravel applications. This package provides easy integration with Zipkin for tracing HTTP requests and custom operations in your Laravel application.

Installation

Install the package via Composer:

composer require anascloud/zkteko

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=zkteko-config

This will create a config/zkteko.php file where you can configure the package:

return [
    'enabled' => env('ZKTEKO_ENABLED', true),
    
    'service_name' => env('ZKTEKO_SERVICE_NAME', env('APP_NAME', 'laravel')),
    
    'transport' => [
        'type' => env('ZKTEKO_TRANSPORT', 'http'),
        'host' => env('ZKTEKO_COLLECTOR_HOST', 'localhost'),
        'port' => env('ZKTEKO_COLLECTOR_PORT', 9411),
        'scheme' => env('ZKTEKO_COLLECTOR_SCHEME', 'http'),
        'socket_timeout' => env('ZKTEKO_SOCKET_TIMEOUT', 1000),
    ],
    
    'endpoint' => [
        'ip' => env('ZKTEKO_ENDPOINT_IP'),
        'port' => env('ZKTEKO_ENDPOINT_PORT', 0),
    ],
];

Environment Variables

Add the following to your .env file:

ZKTEKO_ENABLED=true
ZKTEKO_SERVICE_NAME=my-laravel-app
ZKTEKO_COLLECTOR_HOST=localhost
ZKTEKO_COLLECTOR_PORT=9411
ZKTEKO_COLLECTOR_SCHEME=http
ZKTEKO_SOCKET_TIMEOUT=1000

Usage

Automatic Request Tracing

Add the middleware to your app/Http/Kernel.php (Laravel 9 and below) or bootstrap/app.php (Laravel 10+):

// For Laravel 9 and below
protected $middleware = [
    // ...
    \Anascloud\Zkteko\Middleware\ZktekoMiddleware::class,
];

// For Laravel 10+
->withMiddleware(function (Middleware $middleware) {
    $middleware->append(\Anascloud\Zkteko\Middleware\ZktekoMiddleware::class);
})

This will automatically trace all HTTP requests to your application.

Manual Tracing

Use the facade to manually trace specific operations:

use Anascloud\Zkteko\Facades\Zkteko;

Zkteko::trace('database-query', function () {
    // Your code here
    return User::all();
});

Creating Custom Traces

use Anascloud\Zkteko\Facades\Zkteko;
use Anascloud\Zkteko\Models\Annotation;

$trace = Zkteko::createTrace('custom-operation');
$trace->record(
    Annotation::string('operation.type', 'export'),
    Annotation::string('user.id', '123')
);

Zkteko::pushTrace($trace);
// ... perform operation
Zkteko::popTrace();

Accessing Current Trace

use Anascloud\Zkteko\Facades\Zkteko;

$currentTrace = Zkteko::getCurrentTrace();
if ($currentTrace) {
    $currentTrace->record(Annotation::string('custom.key', 'custom.value'));
}

Nested Tracing

Zkteko::trace('parent-operation', function () {
    // This will be a child span
    Zkteko::trace('child-operation', function () {
        // Nested operation
    });
});

API Reference

Facade Methods

• trace(string $name, callable $callback) - Execute a callback within a trace span
• getCurrentTrace(): ?Trace - Get the current active trace
• createTrace(string $name, ?int $traceId = null, ?int $spanId = null, ?int $parentSpanId = null): Trace - Create a new trace
• pushTrace(Trace $trace): void - Push a trace to the stack
• popTrace(): ?Trace - Pop a trace from the stack
• getEndpoint(): Endpoint - Get the configured endpoint
• isEnabled(): bool - Check if Zkteko tracing is enabled

Annotation Types

The following annotation types are available:

• Annotation::timestamp(string $name, ?int $timestamp = null) - Create a timestamp annotation
• Annotation::serverSend(?int $timestamp = null) - Server send annotation
• Annotation::serverRecv(?int $timestamp = null) - Server receive annotation
• Annotation::clientSend(?int $timestamp = null) - Client send annotation
• Annotation::clientRecv(?int $timestamp = null) - Client receive annotation
• Annotation::string(string $name, string $value) - String annotation
• Annotation::bytes(string $name, string $value) - Bytes annotation

Zipkin Server Setup

To use this package, you need a Zipkin server running. You can start one using Docker:

docker run -d -p 9411:9411 openzipkin/zipkin

Then access the Zipkin UI at http://localhost:9411

License

This package is open-sourced software licensed under the Apache License, Version 2.0.