PHPackages jonsutherland/xray-laravel - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Logging & Monitoring](/categories/logging) 4. / 5. jonsutherland/xray-laravel ActiveLibrary[Logging & Monitoring](/categories/logging) jonsutherland/xray-laravel ========================== AWS X-Ray for Laravel applications. 013.9k↓14.5%PHP Since Apr 22Pushed 9mo agoCompare [ Source](https://github.com/jonsutherland/xray-laravel)[ Packagist](https://packagist.org/packages/jonsutherland/xray-laravel)[ RSS](/packages/jonsutherland-xray-laravel/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependenciesVersions (2)Used By (0) Aws X-Ray for Laravel ===================== [](#aws-x-ray-for-laravel) [![Latest Version on Packagist](https://camo.githubusercontent.com/dee67ff15b25a767e81748a3f15cad8f2c7e12334bec106e4e4e71f8acae0179/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e6170702f787261792d6c61726176656c2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/napp/xray-laravel) The package automatically trace your laravel application and sends to [AWS X-Ray](https://aws.amazon.com/xray). What is 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 ----------------- [](#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](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/xray-timeline.png)](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/xray-timeline.png) Each element has extra information, such as the database query stack trace. [![db-stack](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/xray-db-stack.png)](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/xray-db-stack.png) Installation ------------ [](#installation) 1. Install the package via composer: ``` composer require napp/xray-laravel ``` 2. 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, // ... ]; ``` 3. 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, ], ``` 4. Edit the AWS Execution role to include X-Ray permissions. Either add the preexisting policy from AWS `AWSXrayWriteOnlyAccess`, or create your own: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "xray:PutTraceSegments", "xray:PutTelemetryRecords", "xray:GetSamplingRules", "xray:GetSamplingTargets", "xray:GetSamplingStatisticSummaries" ], "Resource": [ "*" ] } ] } ``` 5. Head over to AWS Console, to Lambda and find your function. Activate X-Ray Tracing. [![Activate](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/lambda-enable-xray.png)](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/lambda-enable-xray.png) Manually use the Tracer ----------------------- [](#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](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/xray-xml-example.png)](https://raw.githubusercontent.com/Napp/xray-laravel/master/docs/xray-xml-example.png) Request filtering ----------------- [](#request-filtering) There might be some requests you wish not to track in Amazon X-Ray. In order to filter out those requests, you can call the `addRequestFilterCallback` function, on the `Xray` facade. This function takes a callback as a parameter. The callback takes a `Symfony\Component\HttpFoundation\Request` as a parameter and is expected to return a boolean. Please note that this function call needs to be done in the `register` function of your `AppServiceProvider`. You should, also, keep the checks relatively simple, since most of the application service providers won't be booted when calling the filtering callbacks. When LaravelXray is booting, the request is checked against each registered callbacks. If none returns false, the request is captured. Otherwise, it is not. ``` use Symfony\Component\HttpFoundation\Request; use Napp\Xray\Facades\Xray; class AppServiceProvider extends ServiceProvider { /** * Register any application services. * * @return void */ public function register() { Xray::addRequestFilterCallback(function(Request $request) { /* some conditions */ return true; }); } } ``` Daemon support -------------- [](#daemon-support) The X-Ray daemon is automatically run in a Lambda environment. Use this over the default `Napp\Xray\Submission\APISegmentSubmitter` to relay requests to Amazon X-Ray. Firstly, publish the X-Ray config and then update the submitter in `config/xray.php` to `\Napp\Xray\Submission\DaemonSegmentSubmitter::class` ``` php artisan vendor:publish --tag=xray-config ``` ``` # config/xray.php ... 'submitter' => \Napp\Xray\Submission\DaemonSegmentSubmitter::class, ... ``` The daemon submitter will pick up the `_AWS_XRAY_DAEMON_ADDRESS` `_AWS_XRAY_DAEMON_PORT`. These environment variables are injected for you if using a service like [Laravel Vapor](https://vapor.laravel.com/) Disable Tracer -------------- [](#disable-tracer) If you want to disable the Tracer, just add to the `.env` file. ``` XRAY_ENABLED=false ``` What Tracers are supported -------------------------- [](#what-tracers-are-supported) - Composer autoload - Framework boot - Route matching - HTTP requests - Database queries - Queue jobs - Blade view render - Cache requests - Commands LICENSE ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 26 — LowBetter than 43% of packages Maintenance41 Moderate activity, may be stable Popularity27 Limited adoption so far Community16 Small or concentrated contributor base Maturity17 Early-stage or recently created project Bus Factor5 5 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Community Maintainers ![](https://www.gravatar.com/avatar/98cf5d54c71abc3ff8c6cccadc2b22f602e15aca85d956e830e64033d6e20dbb?d=identicon)[jonsutherland](/maintainers/jonsutherland) --- Top Contributors [![StevePorter92](https://avatars.githubusercontent.com/u/12199424?v=4)](https://github.com/StevePorter92 "StevePorter92 (5 commits)")[![umbert-cobiro](https://avatars.githubusercontent.com/u/47525764?v=4)](https://github.com/umbert-cobiro "umbert-cobiro (4 commits)")[![laravel-shift](https://avatars.githubusercontent.com/u/15991828?v=4)](https://github.com/laravel-shift "laravel-shift (3 commits)")[![aran112000](https://avatars.githubusercontent.com/u/3313791?v=4)](https://github.com/aran112000 "aran112000 (2 commits)")[![jonsutherland](https://avatars.githubusercontent.com/u/884351?v=4)](https://github.com/jonsutherland "jonsutherland (2 commits)")[![adrianpaiva1](https://avatars.githubusercontent.com/u/19557611?v=4)](https://github.com/adrianpaiva1 "adrianpaiva1 (2 commits)")[![LorenzoRogai](https://avatars.githubusercontent.com/u/1665768?v=4)](https://github.com/LorenzoRogai "LorenzoRogai (2 commits)")[![nicDamours](https://avatars.githubusercontent.com/u/3102811?v=4)](https://github.com/nicDamours "nicDamours (2 commits)")[![viezel](https://avatars.githubusercontent.com/u/312065?v=4)](https://github.com/viezel "viezel (1 commits)")[![d8vjork](https://avatars.githubusercontent.com/u/2331052?v=4)](https://github.com/d8vjork "d8vjork (1 commits)")[![derekmd](https://avatars.githubusercontent.com/u/823566?v=4)](https://github.com/derekmd "derekmd (1 commits)")[![emaadali](https://avatars.githubusercontent.com/u/3521616?v=4)](https://github.com/emaadali "emaadali (1 commits)")[![Gavrisimo](https://avatars.githubusercontent.com/u/203706?v=4)](https://github.com/Gavrisimo "Gavrisimo (1 commits)")[![junamai2000](https://avatars.githubusercontent.com/u/31193?v=4)](https://github.com/junamai2000 "junamai2000 (1 commits)")[![kimegede](https://avatars.githubusercontent.com/u/870013?v=4)](https://github.com/kimegede "kimegede (1 commits)")[![RobinHoutevelts](https://avatars.githubusercontent.com/u/9056689?v=4)](https://github.com/RobinHoutevelts "RobinHoutevelts (1 commits)") ### Embed Badge ![Health badge](/badges/jonsutherland-xray-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/jonsutherland-xray-laravel/health.svg)](https://phpackages.com/packages/jonsutherland-xray-laravel) ``` ### Alternatives [psr/log Common interface for logging libraries 10.4k1.2B9.2k](/packages/psr-log)[itsgoingd/clockwork php dev tools in your browser 5.9k27.6M94](/packages/itsgoingd-clockwork)[graylog2/gelf-php A php implementation to send log-messages to a GELF compatible backend like Graylog2. 41838.2M138](/packages/graylog2-gelf-php)[bugsnag/bugsnag-psr-logger Official Bugsnag PHP PSR Logger. 32132.5M2](/packages/bugsnag-bugsnag-psr-logger)[consolidation/log Improved Psr-3 / Psr\\Log logger based on Symfony Console components. 15462.2M7](/packages/consolidation-log)[ekino/newrelic-bundle Integrate New Relic into Symfony2 28111.2M8](/packages/ekino-newrelic-bundle) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)