Reference implementation of the OpenTracing API for Laravel including a server-less local tracer for application logging purposes.
See OpenTracing for more information.
Currently supported clients:
- Local: No-op tracer used mainly for adding trace ids to logs.
- Jaeger: open source, end-to-end distributed tracing. See Jaeger and Jonah George's Jaeger Client PHP.
Install the latest version using:
composer require wizofgoz/laravel-opentracing
Copy the default configuration file to your application if you want to change it by running the command below. Note
that you have to use --force
if the file already exists.
php artisan vendor:publish --provider="LaravelOpenTracing\TracingServiceProvider"
Example bootstrap/app.php
file:
<?php
// Create the application.
$app = new \Illuminate\Foundation\Application(realpath(__DIR__ . '/../'));
// Bind important interfaces.
// ...
// Register important providers.
$app->register(\LaravelOpenTracing\TracingServiceProvider::class);
// Enable tracing span context in log messages.
$app->configureMonologUsing(function (\Monolog\Logger $logger) {
$logger->pushProcessor(new \LaravelOpenTracing\Log\Processors\TracingProcessor());
});
// Return the application.
return $app;
To trace a specific process in your application you can wrap the process in a trace closure using the provided facade as shown below. This will take care of starting a new trace span and closing it again when the closure either returns or throws.
<?php
$items = \LaravelOpenTracing\Facades\Tracing::trace(
'todo.get_list_items',
function () {
return \App\Models\TodoListItem::get();
}
);
Nested traces are also possible like below. It will automatically take care of the span child/parent relations.
<?php
function a() {
// We don't care about tracing this specifically.
doSomething();
\LaravelOpenTracing\Facades\Tracing::trace(
'app.do_something_else',
function () {
doSomethingElse();
}
);
}
\LaravelOpenTracing\Facades\Tracing::trace(
'app.do_stuff',
function () {
a();
}
);
If you want to add context information or tags to your spans, it is possible like below.
<?php
$title = 'Make more coffee';
$item = \LaravelOpenTracing\Facades\Tracing::trace(
'todo.store_item',
function () use ($title) {
return \App\Models\TodoListItem::create(['title' => $title]);
},
['tags' => ['title' => $title]]
);
Helper functions are provided for all functions available on the facade.
<?php
trace(
'todo.store_item',
function () use ($title) {
return \App\Models\TodoListItem::create(['title' => $title]);
},
['tags' => ['title' => $title]]
);
This package provides resolvers for common tags from a given context such as an Eloquent Query Builder, Request object, or Response object. These can be overridden in configuration like below.
/*
* Resolvers used for generating tags for spans.
*/
'tags' => [
'middleware' => [
'request' => \LaravelOpenTracing\Resolvers\RequestTagResolver::class,
'response' => \LaravelOpenTracing\Resolvers\ResponseTagResolver::class,
],
'query' => \LaravelOpenTracing\Resolvers\QueryTagResolver::class,
],
There are helper functions available for deriving tags from contexts based on the current configuration.
<?php
/** @var \Illuminate\Database\Query\Builder $builder */
$tags = query_tags($builder);
/** @var \Illuminate\Http\Request $request */
$tags = request_tags($request);
/** @var \Illuminate\Http\Response $response */
$tags = response_tags($response);
All jobs can be automatically traced by using the enable_jobs
boolean in the configuration file or for tracing on certain jobs, attach the provided middleware to the ones you wish to trace.
<?php
// Add to job classes
/**
* Get the middleware the job should pass through.
*
* @return array
*/
public function middleware()
{
return [new \LaravelOpenTracing\Jobs\Middleware\Tracing];
}
Trace contexts can easily be used across services. If your application starts a tracing context, that context can be carried over HTTP to another service with an OpenTracing compatible implementation.
To automatically accept trace contexts from other services, add the tracing middleware to your application by adding it
to your app/Http/Kernel.php
file like below:
<?php
class Kernel extends HttpKernel
{
protected $middleware = [
\LaravelOpenTracing\Http\Middleware\Tracing::class,
];
}
Assuming your application uses GuzzleHttp for sending requests to external services, you can use the provided tracing handler when creating the client like below. This will automatically send the necessary trace context headers with the HTTP request to the external service.
<?php
new \GuzzleHttp\Client(
[
'handler' => new \LaravelOpenTracing\Propagators\GuzzlePropagator(),
'headers' => [
'cache-control' => 'no-cache',
'content-type' => 'application/json',
],
'base_uri' => 'http://localhost/api/myservice',
'http_errors' => false
]
);
docker run --rm -it -v $(pwd):/app php:7.3-cli-alpine /bin/sh -c 'apk add --no-cache $PHPIZE_DEPS && pecl install xdebug-2.7.2 && cd app && php -dzend_extension=xdebug.so vendor/bin/phpunit'
- PHP 7.3 or newer.
Bugs and feature requests are tracked on GitHub.
OpenTracing for Laravel is licensed under the Apache-2.0 license. See the LICENSE file for details.