laravel-integration.md

Integrating Opentelemetry PHP into Laravel Applications

Introduction

Distributed tracing helps developers and management gain insights into how well applications perform in terms of traces, metrics, and logs. This guide shows how developers can integrate OpenTelemetry PHP into their Laravel applications for the above benefits. Our example application visualizes exceptions from a Laravel application using both Jaeger and Zipkin.

To follow this guide you will need:

• PHP Installed; this example uses PHP 7.4.
• Composer for dependency management.
• Docker for bundling our visualization tools. We have setup instructions for docker on this project's readme.

This example uses Laravel version 8.40 .

Step 1 - Creating a Laravel Application

The Laravel framework supports creating applications using composer. To do that, run composer create-project <project-name> . We are naming our project otel-php-laravel-basic-example, so the command is as follows:

composer create-project laravel/laravel otel-php-laravel-basic-example

To confirm that our application works, we can move to the application directory using cd otel-php-laravel-basic-example , then serve the application with php artisan serve .

Let's navigate to http://127.0.0.1:8000 on our browser to see the default Laravel welcome page.

Step 2 - Require OpenTelemetry PHP Package

Starting from version v.0.0.2, the open-telemetry php package allows users to use their preferred HTTP layers for exporting traces. The benefit of this is that users can reuse already existing HTTP configurations for their applications. Hence, there is need to require packages that satisfy both psr/http-client-implementation and psr/http-factory-implementation before requiring the opentelemetry-php package.

By default, the Laravel framework utilizes guzzlehttp/guzzle and this satisfies psr/http-client-implementation, so we need to require the guzzlehttp/psr7 to meet the psr/http-factory-implementation requirement. Let's run composer require guzzlehttp/psr7:2.0.0-rc1.

Note: We are specifying 2.0.0-rc1 as that is the release for guzzlehttp/psr7 that includes HTTP factories as at the time of writing this guide.

Next, let's run composer require open-telemetry/opentelemetry to pull in the openTelemetry-php package.

Step 3 - Bundle Zipkin and Jaeger into the Application

To visualize traces exported from our application, we need to integrate open source tracing tools Zipkin and Jaeger into our setup using docker.

First, we create a docker-compose.yaml file in the root of our project, with content as follows:

version: '3.7'
services:
    zipkin:
        image: openzipkin/zipkin-slim
        ports:
            - 9411:9411
    jaeger:
        image: jaegertracing/all-in-one
        environment:
            COLLECTOR_ZIPKIN_HOST_PORT: 9412

        ports:
            - 9412:9412
            - 16686:16686

Next, we pull in Zipkin and Jaeger by running docker-compose up -d. This might take some time, depending on your internet connection speed.

We can confirm that Zipkin is up by navigating to http://localhost:9411/ on our browser. For Jaeger, navigating to http://localhost:16686/ on our browser should display the Jaeger home page.

Step 5 - Instrument Laravel Application

For this step, we will utilize our OpenTelemetry PHP Library to export traces to both Zipkin and Jaeger.

The default entry point for Laravel applications is the index.php file located in the public folder. If we navigate to public\index.php we can see that the index file autoloads classes from packages within our vendor folder, making them easily useable within our application.

require __DIR__.'/../vendor/autoload.php';

The other parts of the index.php file enable request and response resolution using the application kernel.

$app = require_once __DIR__.'/../bootstrap/app.php';

$kernel = $app->make(Kernel::class);

$response = tap($kernel->handle(
    $request = Request::capture()
))->send();

$kernel->terminate($request, $response);

It is worthy of note that resources(namespaces, classes, variables) created within the index.php file are available within the entire application.

To use open-telemetry specific classes within our application we have to import them at the top of our index file, using the use keyword. This is what our list of open-telemetry imported classes should look like:

use OpenTelemetry\Contrib\Jaeger\Exporter as JaegerExporter;
use OpenTelemetry\Contrib\Zipkin\Exporter as ZipkinExporter;
use OpenTelemetry\Context\Context;
use OpenTelemetry\SDK\Trace\Sampler\AlwaysOnSampler;
use OpenTelemetry\SDK\Trace\SamplingResult;
use OpenTelemetry\SDK\Trace\SpanProcessor\BatchSpanProcessor;
use OpenTelemetry\SDK\Trace\TracerProvider;
use OpenTelemetry\API\Trace as API;
use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;

Remember that these imports should go side by side with the default class imports that come with the index.php file.

Next, we create a sample recording trace using the AlwaysOnSampler class, just before the app instance is created like below:

$sampler = new AlwaysOnSampler();
$samplingResult = $sampler->shouldSample(
    new Context(),
    md5((string) microtime(true)),
    'io.opentelemetry.example',
    API\SpanKind::KIND_INTERNAL
);

Since we are looking to export traces to both Zipkin and Jaeger we have to make use of their exporters;

$jaegerExporter = new JaegerExporter(
    'Hello World Web Server Jaeger',
    'http://localhost:9412/api/v2/spans',
    new Client(),
    new HttpFactory(),
    new HttpFactory()
);

$zipkinExporter = new ZipkinExporter(
    'Hello World Web Server Zipkin',
    'http://localhost:9411/api/v2/spans',
    new Client(),
    new HttpFactory(),
    new HttpFactory()
);

Next, we create a trace then add processors for each trace(One for Jaeger and another for Zipkin). Then we proceed to start and activate a span for each trace. We create a trace only if the RECORD AND SAMPLED sampling result condition passes as follows;

if (SamplingResult::RECORD_AND_SAMPLE === $samplingResult->getDecision()) {

    $jaegerTracer = (new TracerProvider(null, $sampler))
        ->addSpanProcessor(new BatchSpanProcessor($jaegerExporter, Clock::get()))
        ->getTracer('io.opentelemetry.contrib.php');

    $zipkinTracer = (new TracerProvider(null, $sampler))
    ->addSpanProcessor(new BatchSpanProcessor($zipkinExporter, Clock::get()))
    ->getTracer('io.opentelemetry.contrib.php');

    $request = Request::createFromGlobals();
    $jaegerSpan = $jaegerTracer->startAndActivateSpan($request->getUri());
    $zipkinSpan = $zipkinTracer->startAndActivateSpan($request->getUri());

}

Finally, we end the active spans if sampling is complete, by adding the following block at the end of the index.php file;

if (SamplingResult::RECORD_AND_SAMPLE === $samplingResult->getDecision()) {
    $zipkinSpan->end();
    $jaegerSpan->end();
}

Let's confirm that we can see exported traces on both Zipkin and Jaeger. To do that, we need to reload http://127.0.0.1:8000 on our browser;

We also need reload both Zipkin and Jaeger on our browser, using the URLs http://localhost:9411/ and http://localhost:16686/. Do ensure that both your Laravel server and docker instance are running for this step.

For Jaeger under service, you should see a Hello World Web Server Jaeger service. Go ahead and click find traces to see exported traces.

Once we click on Find Traces, you should be able to see traces like below:

We can click on a trace to get more information about the trace.

For Zipkin, we can visualize our trace by clicking on Run Query

Since resources in Laravel's public\index.php file are available to the entire application, we can use any of the already instantiated tracers to further instrument controllers or any other parts of our application.

Let's create a Hello controller to check this out. Run the command php artisan make:controller HelloController

Next we need to add a route for accessing the controller. To do this we need to utilize the HelloController class within our web routes file located in the routes\web.php as follows:

use App\Http\Controllers\HelloController;

Next we need to add a route and method for the controller.

Route::get('/hello', [HelloController::class, 'index']);

The above snippet routes every GET request from the /hello route on the browser to an index method within the HelloController class. For now, this method does not exist, so we have to add it to our controller as follows

public function index(){
    return "hello";
}

Let's confirm that everything works well by visiting the /hello route on our browser.

Now that we have the index method working, we can simulate adding an exception event to our Zipkin trace as follows:

global $zipkinTracer;
if ($zipkinTracer) {
    /** @var Span $span */
    $span = $zipkinTracer->getActiveSpan();
    
    $span->setAttribute('foo', 'bar');
    $span->updateName('New name');

    $childSpan = $zipkinTracer->startAndActivateSpan('Child span');
    try {
        throw new \Exception('Exception Example');
    } catch (\Exception $exception) {
        $span->setSpanStatus($exception->getCode(), $exception->getMessage());
    }
    $childSpan->end();
}

In the above snippet we change the span name and attributes for our Zipkin trace, we also add an exception event to the span.

We need to reload our http://127.0.0.1:8000/hello route, then navigate to Zipkin like before, to see that our span name gets updated to new name and our Exception Example is visible.

Summary

With the above example we have been able to instrument a Laravel application using the OpenTelemetry PHP library. You can fork the example project here.