pkerrigan / xray
A basic PHP instrumentation library for AWS X-Ray
Installs: 832 939
Dependents: 5
Suggesters: 0
Security: 0
Stars: 63
Watchers: 4
Forks: 26
Open Issues: 2
Requires
- php: >=7.1
- ext-json: *
- ext-sockets: *
Requires (Dev)
- phpunit/phpunit: ^9|^8|^7
This package is auto-updated.
Last update: 2024-11-07 00:02:40 UTC
README
pkerrigan\xray
A basic PHP instrumentation library for AWS X-Ray
Until Amazon releases an official PHP SDK for AWS X-Ray this library allows you to add basic instrumentation to PHP applications and report traces via the AWS X-Ray daemon.
Please note that no automatic instrumentation of popular libraries is provided. In order to instrument SQL queries, HTTP requests and/or other services you'll be required to create your own wrappers which start and end tracing segments as appropriate.
Installation
The recommended way to install this library is using Composer:
$ composer require pkerrigan/xray ^1
Usage
Starting a trace
The Trace
class represents the top-level of an AWS X-Ray trace, and can function as a singleton for easy access from anywhere in your code, including before frameworks and dependency injectors have been initialised.
You should start a trace as early as possible in your request:
use Pkerrigan\Xray\Trace; Trace::getInstance() ->setTraceHeader($_SERVER['HTTP_X_AMZN_TRACE_ID'] ?? null) ->setName('app.example.com') ->setUrl($_SERVER['REQUEST_URI']) ->setMethod($_SERVER['REQUEST_METHOD']) ->begin();
Adding a segment to a trace
You can add as many segments to your trace as necessary, including nested segments. To add an SQL query to your trace, you'd do the following:
Trace::getInstance() ->getCurrentSegment() ->addSubsegment( (new SqlSegment()) ->setName('db.example.com') ->setDatabaseType('PostgreSQL') ->setQuery($mySanitisedQuery) // Make sure to remove sensitive data before passing in a query ->begin() ); // Run your query here Trace::getInstance() ->getCurrentSegment() ->end();
The getCurrentSegment()
method will always return the most recently opened segment, allowing you to nest as deeply as necessary.
Ending a trace
At the end of your request, you'll want to end and submit your trace. By default only submitting via the AWS X-Ray daemon is supported.
Trace::getInstance() ->end() ->setResponseCode(http_response_code()) ->submit(new DaemonSegmentSubmitter());
Features not yet implemented
- Exception and stack trace support
- Submission of incomplete segments