A basic PHP instrumentation library for AWS X-Ray

v1.4.0 2022-01-09 12:20 UTC

This package is auto-updated.

Last update: 2023-09-11 21:30:49 UTC


Build Status Maintainability Test Coverage PHP >=7.1 Packagist


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.


The recommended way to install this library is using Composer:

$ composer require pkerrigan/xray ^1


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;

    ->setTraceHeader($_SERVER['HTTP_X_AMZN_TRACE_ID'] ?? null)

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:

        (new SqlSegment())
            ->setQuery($mySanitisedQuery)    // Make sure to remove sensitive data before passing in a query
// Run your query here

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.

    ->submit(new DaemonSegmentSubmitter());

Features not yet implemented

  • Exception and stack trace support
  • Submission of incomplete segments