napp / xray-laravel

AWS X-Ray for Laravel applications.

Stars
6

Aws X-Ray for Laravel

Latest Version on Packagist

The package automatically trace your laravel application and sends to AWS X-Ray.

What is X-Ray?

X-Ray is a distributed tracing system for production apps. AWS X-Ray traces user requests as they travel through your entire application.
It aggregates the data generated by the individual services and resources that make up your application, providing you an end-to-end view of how your application is performing.

X-Ray for Laravel

This package enables automatic tracing of important parts of your application, such as http request, database queries, views and queue jobs. Those parts are being traced and sent to AWS X-Ray for you to improve performance.

Below is a simple example of a http request with a database query. This query is quite slow and could maybe be optimized or cached.

timeline

Each element has extra information, such as the database query stack trace.

db-stack

Installation

  1. Install the package via composer:
composer require napp/xray-laravel
  1. Add middleware to the top of the global middleware in App\Http\Kernel.php.
protected $middleware = [
    \Napp\Xray\Middleware\RequestTracing::class, // here

    \App\Http\Middleware\TrustProxies::class,
    \App\Http\Middleware\CheckForMaintenanceMode::class,
    // ...
];
  1. Add XrayServiceProvider to the very top of providers in config/app.php.
'providers' => [
    /*
     * Laravel Framework Service Providers...
     */
    Napp\Xray\XrayServiceProvider::class, // here

    Illuminate\Auth\AuthServiceProvider::class,
    Illuminate\Broadcasting\BroadcastServiceProvider::class,
    // ...
];

Optionally, you can add the facade in config/app.php.

'aliases' => [
    // ...
    'Xray' => \Napp\Xray\Facades\Xray::class,
],
  1. Head over to AWS Console, to Lambda and find your function. Activate X-Ray Tracing.

Activate

Manually use the Tracer

Lets say you want to trace a specific piece of your code to deeply understand the impact on performance.

Xray::addSegment('MyCustomLogic');

// run your code

Xray::endSegment('MyCustomLogic');

Another use case is to inspect some heavy php side parsing of data.

use Napp\Xray\Facades\Xray;

class XMLParser
{
    public function handle($file)
    {
        // adding some metadata to the segment
        Xray::addSegment('XMLParser', null, [
            'file' => $file->name()
        ]);
        $this->parse($file);
        Xray::endSegment('XMLParser');
    }
    
    private function parse($xml): array 
    {
        Xray::addSegment('XMLParser parse');
        $output = $this->getAttributeList();
        // some more code
        Xray::endSegment('XMLParser parse');

        return $output;
    }
    
    private function getAttributeList(): array 
    {
        Xray::addSegment('XMLParser getAttributeList');
        // your code
        Xray::endSegment('XMLParser getAttributeList');

        return [];
    }
}

The above results in:

XML-example

Disable Tracer

If you want to disable the Tracer, just add to the .env file.

XRAY_ENABLED=false

What Tracers are supported

  • Composer autoload
  • Framework boot
  • Route matching
  • HTTP requests
  • Database queries
  • Queue jobs
  • Blade view render

LICENSE

The MIT License (MIT). Please see License File for more information.