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

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

pkerrigan/xray
==============

A basic PHP instrumentation library for AWS X-Ray

v1.4.1(1y ago)601.4M—7.5%25[1 issues](https://github.com/patrickkerrigan/php-xray/issues)[2 PRs](https://github.com/patrickkerrigan/php-xray/pulls)2BSD-3-ClausePHPPHP >=7.1

Since May 19Pushed 1y ago3 watchersCompare

[ Source](https://github.com/patrickkerrigan/php-xray)[ Packagist](https://packagist.org/packages/pkerrigan/xray)[ RSS](/packages/pkerrigan-xray/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (9)Dependencies (1)Versions (12)Used By (2)

[![Build Status](https://camo.githubusercontent.com/56a1fa8a06b9039ade20a02ef6a089d486062adb2e1472d3a85b4d4cf25e16b8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7061747269636b6b6572726967616e2f7068702d787261792f74657374732e796d6c3f6272616e63683d6d6173746572267374796c653d666c61742d737175617265)](https://github.com/patrickkerrigan/php-xray/actions/workflows/tests.yml) [![Maintainability](https://camo.githubusercontent.com/cacd06d16a995db9091cf41ee73690cf4f35260ee0cedc3859f401dc238c7f33/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f35343861643662376332356265663830303463642f6d61696e7461696e6162696c697479)](https://codeclimate.com/github/patrickkerrigan/php-xray/maintainability) [![Test Coverage](https://camo.githubusercontent.com/0830709319ebaefb8b669707989f9daa0c0fb73b4447fc18c76e2c22a1d611b1/68747470733a2f2f6170692e636f6465636c696d6174652e636f6d2f76312f6261646765732f35343861643662376332356265663830303463642f746573745f636f766572616765)](https://codeclimate.com/github/patrickkerrigan/php-xray/test_coverage) [![PHP >=7.1](https://camo.githubusercontent.com/e124089bc37f05fb115a7d92e727786b6a3622beb3bb9512619757c46c6c6579/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344372e312d626c75652e7376673f7374796c653d666c61742d737175617265)](http://php.net/) [![Packagist](https://camo.githubusercontent.com/0b498478728136d3d7b96be5d39cbf5bdf0ae0607205835d811b9fa63d4a3c4d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f706b6572726967616e2f787261792e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/pkerrigan/xray)

pkerrigan\\xray
===============

[](#pkerriganxray)

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

[](#installation)

The recommended way to install this library is using Composer:

```
$ composer require pkerrigan/xray ^1
```

Usage
-----

[](#usage)

### Starting a trace

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

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

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

[](#features-not-yet-implemented)

- Exception and stack trace support
- Submission of incomplete segments

###  Health Score

49

—

FairBetter than 95% of packages

Maintenance38

Infrequent updates — may be unmaintained

Popularity55

Moderate usage in the ecosystem

Community21

Small or concentrated contributor base

Maturity65

Established project with proven stability

 Bus Factor1

Top contributor holds 94.5% of commits — single point of failure

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 ~297 days

Recently: every ~374 days

Total

9

Last Release

539d ago

PHP version history (2 changes)v1.0.0PHP >=7.0

v1.4.0PHP >=7.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/3968064339c2d1293cff71ca9b0a392d971820a979deb2b0c77070dc5e57595a?d=identicon)[patrickkerrigan](/maintainers/patrickkerrigan)

---

Top Contributors

[![patrickkerrigan](https://avatars.githubusercontent.com/u/20188719?v=4)](https://github.com/patrickkerrigan "patrickkerrigan (69 commits)")[![WaylandAce](https://avatars.githubusercontent.com/u/1263005?v=4)](https://github.com/WaylandAce "WaylandAce (3 commits)")[![willtj](https://avatars.githubusercontent.com/u/465569?v=4)](https://github.com/willtj "willtj (1 commits)")

---

Tags

awsapmtracingX-RayAWS X-Ray

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[open-telemetry/api

API for OpenTelemetry PHP.

1933.0M214](/packages/open-telemetry-api)[open-telemetry/sdk

SDK for OpenTelemetry PHP.

2322.9M248](/packages/open-telemetry-sdk)[friendsofopentelemetry/opentelemetry-bundle

Traces, metrics, and logs instrumentation within your Symfony application

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

PHPackages © 2026

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