PHPackages                             fido/php-xray - 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. fido/php-xray

ActiveLibrary[Logging & Monitoring](/categories/logging)

fido/php-xray
=============

PHP instrumentation library for AWS X-Ray

0.2.2(2y ago)39.3k[1 issues](https://github.com/fido-id/php-xray/issues)[2 PRs](https://github.com/fido-id/php-xray/pulls)MITPHPPHP >=8.0.0

Since Feb 25Pushed 2y ago3 watchersCompare

[ Source](https://github.com/fido-id/php-xray)[ Packagist](https://packagist.org/packages/fido/php-xray)[ RSS](/packages/fido-php-xray/feed)WikiDiscussions master Synced today

READMEChangelog (6)Dependencies (13)Versions (9)Used By (0)

fido-id/php-xray
================

[](#fido-idphp-xray)

[![Build Status](https://github.com/fido-id/php-xray/actions/workflows/main.yaml/badge.svg)](https://github.com/fido-id/php-xray/actions/workflows/main.yaml)[![PHP Version](https://camo.githubusercontent.com/3571a86987b3a8b0b0d13c86369a99d5b7b5a1945a7e624bba32d4c3183eab0a/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d2533453d382e302d626c7565)](https://www.php.net/releases/8.0/en.php)[![Coverage Status](https://camo.githubusercontent.com/b78433777f3bb175bbc223c4564dc46f174bc4b6a601cc36740e2f1272963a9e/68747470733a2f2f636f6465636f762e696f2f67682f6669646f2d69642f7068702d787261792f6272616e63682f6d61737465722f67726170682f62616467652e7376673f746f6b656e3d5953504d474a56503737)](https://app.codecov.io/gh/fido-id/php-xray)

An instrumentation library for [AWS X-Ray](https://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html) for PHP 8.x [LICENSE](LICENSE.md)[CHANGELOG](CHANGELOG-0.x.md)

Installation
------------

[](#installation)

To use this package, use [Composer](https://getcomposer.org/):

- From CLI: `composer require fido-id/php-xray`
- Or, directly in your `composer.json`:

```
{
  "require": {
    "fido/php-xray": "^0.2.1",
  }
}
```

Usage
-----

[](#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

[](#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 a `closeWithPsrResponse` helper method which allows to populate and close the segment with an object implementing the `Psr\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](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-metadata), [annotation](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-annotations) and [aws data](https://docs.aws.amazon.com/xray/latest/devguide/xray-api-segmentdocuments.html#api-segmentdocuments-aws) custom handling (Remember to extend `__construct` and `jsonSerialize` methods accordingly).

### Fault and error handling

[](#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
------------------------

[](#how-to-test-the-software)

You can run the library test suite with [PHPUnit](https://phpunit.de/) by running `composer test` script, you can also run `composer mutation` script for mutation testing report.

Known issues
------------

[](#known-issues)

- Segments currently support only `Cause` object but not `exception ID`.
- Submitting open segment is not supported yet.

Getting help
------------

[](#getting-help)

If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.

Getting involved
----------------

[](#getting-involved)

Feedbacks and pull requests are very welcome, more on *how* to contribute on [CONTRIBUTING](CONTRIBUTING.md).

---

Credits and references
----------------------

[](#credits-and-references)

This library is inspired by [patrickkerrigan/php-xray](https://github.com/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.

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance13

Infrequent updates — may be unmaintained

Popularity22

Limited adoption so far

Community14

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor2

2 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.

###  Release Activity

Cadence

Every ~99 days

Recently: every ~124 days

Total

6

Last Release

1092d ago

PHP version history (2 changes)0.1.0PHP >=8.0

0.1.2PHP >=8.0.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/5d7b74d41d0b4fbccef0593c9374d984459c2cfd48d38e6a23ac6bf34dbbc625?d=identicon)[Fpanina](/maintainers/Fpanina)

---

Top Contributors

[![ranpafin](https://avatars.githubusercontent.com/u/3133626?v=4)](https://github.com/ranpafin "ranpafin (12 commits)")[![mikysan](https://avatars.githubusercontent.com/u/26388056?v=4)](https://github.com/mikysan "mikysan (9 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (7 commits)")[![mauroartizzu](https://avatars.githubusercontent.com/u/567423?v=4)](https://github.com/mauroartizzu "mauroartizzu (3 commits)")[![marcocot](https://avatars.githubusercontent.com/u/1157664?v=4)](https://github.com/marcocot "marcocot (2 commits)")[![sanfo](https://avatars.githubusercontent.com/u/1766026?v=4)](https://github.com/sanfo "sanfo (1 commits)")

---

Tags

awsapmtracingX-RayAWS X-Ray

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/fido-php-xray/health.svg)

```
[![Health](https://phpackages.com/badges/fido-php-xray/health.svg)](https://phpackages.com/packages/fido-php-xray)
```

###  Alternatives

[pkerrigan/xray

A basic PHP instrumentation library for AWS X-Ray

601.6M3](/packages/pkerrigan-xray)[open-telemetry/api

API for OpenTelemetry PHP.

1941.5M276](/packages/open-telemetry-api)[open-telemetry/sdk

SDK for OpenTelemetry PHP.

2328.5M342](/packages/open-telemetry-sdk)[friendsofopentelemetry/opentelemetry-bundle

Traces, metrics, and logs instrumentation within your Symfony application

6511.2k](/packages/friendsofopentelemetry-opentelemetry-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)