fido / php-xray
PHP instrumentation library for AWS X-Ray
Installs: 9 259
Dependents: 0
Suggesters: 0
Security: 0
Stars: 4
Watchers: 3
Forks: 0
Open Issues: 3
Requires
- php: >=8.0.0
- ext-json: *
- ext-sockets: *
- webmozart/assert: ^1.11
Requires (Dev)
- guzzlehttp/guzzle: ^7.0.0
- infection/infection: ^0.25.0 || ^0.26.0
- phpstan/extension-installer: ^1.0.0
- phpstan/phpstan: 1.10.*
- phpstan/phpstan-deprecation-rules: ^1.0.0
- phpstan/phpstan-php-parser: ^1.0.0
- phpstan/phpstan-phpunit: ^1.0.0
- phpstan/phpstan-webmozart-assert: ^1.0.0
- phpunit/phpunit: ^9.0.0
- psr/http-message: ^2.0.0
- slevomat/coding-standard: ^6.0.0 || ^8.0.0
- squizlabs/php_codesniffer: ^3.0.0
This package is auto-updated.
Last update: 2024-10-18 08:05:43 UTC
README
An instrumentation library for AWS X-Ray for PHP 8.x LICENSE CHANGELOG
Installation
To use this package, use Composer:
- From CLI:
composer require fido-id/php-xray
- Or, directly in your
composer.json
:
{ "require": { "fido/php-xray": "^0.2.1", } }
Usage
Start a new trace, create a new segment, add any desired subsegment, close it and submit it.
eg.
$client = new \GuzzleHttp\Client(); $trace = new Trace(name: 'a_new_trace'); $httpSegment = new HttpSegment( name: \uniqid("http_segment_post_500_"), url: 'ifconfig.me/ua', method: 'GET' ); $httpSegment ->closeWithPsrResponse($client->get('ifconfig.me/ua')) $trace->addSubsegment($httpSegment); $trace->end()->submit(new DaemonSegmentSubmitter());
Closing segments is mandatory before submitting, closing a parent segment will automatically close any child segment.
Available built-in segments
Segment
: Default simple segment extended by any other segment in this list.RemoteSegment
: A segment with the$traced
boolean property, extended by the other segment.DynamoSegment
: A segment thought for Dynamo operations with$tableName
,$operation
and$requestId
dynamo related properties.HttpSegment
: A segment thought for operation over HTTP with$url
,$method
and$responseCode
related properties. It also features acloseWithPsrResponse
helper method which allows to populate and close the segment with an object implementing thePsr\Http\Message\ResponseInterface
interface.SqlSegment
: A segment thought for SQL operations with$query
property and$url
,$preparation
,$databaseType
,$databaseVersion
,$driverVersion
and$user
optional properties.
You may want to extend one of the above class to instrument custom segments for metadata, annotation and aws data custom handling (Remember to extend
__construct
andjsonSerialize
methods accordingly).
Fault and error handling
Any segment has the $fault
and $error
boolean properties that can be used accordingly, also you can set the cause with a Cause
object.
eg.
$trace = new Trace(name: 'a_new_trace'); $pdo = new \PDO('a_totally_valid_dsn'); $query = "SELECT * FROM table_name"; $sqlSegment = new SqlSegment( name: \uniqid("subsegment_sql_"), query: $query ); try { $pdo->exec($query); } catch (\Throwable $exception) { $sqlSegment->setError(true); $sqlSegment->setCause(Cause::fromThrowable($exception)); } $trace->addSubsegment($sqlSegment); $trace->end()->submit(new DaemonSegmentSubmitter());
How to test the software
You can run the library test suite with PHPUnit by running composer test
script, you can also run composer mutation
script for mutation testing report.
Known issues
- Segments currently support only
Cause
object but notexception ID
. - Submitting open segment is not supported yet.
Getting help
If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.
Getting involved
Feedbacks and pull requests are very welcome, more on how to contribute on CONTRIBUTING.
Credits and references
This library is inspired by patrickkerrigan/php-xray, initially we thought to fork it but ended up re-writing it from scratch using PHP8 named constructors instead of fluent approach which allow us to have always valid entities instantiated.