PHP Transactions

Types of transactions
Timing
Metadata
- Environment
- HTTP
- Hostname
- User
- Custom metadata

Types of transactions

At the beginning of every APM trace a transaction must be started. There are three types of supported transactions:

request for tracing HTTP requests
job for tracing background jobs
custom for all other traces

Request

Apm::startRequest();

You may optionally pass $method and $url to the startRequest method. By default these are gathered from $_SERVER (see HTTP metadata below).

Apm::startRequest('POST', '/posts/:id');

For best practice the URL should be parameterized to not include dynamic parts of a path that change often but represent the same requests. For example, instad of /posts/24 set the URL to be /posts/:id

Job

For background jobs, cron jobs, CLI commands, etc. you can use the job transaction type

Apm::startJob('job-name');

Custom

For all other transaction types you can use the custom type

Apm::startCustom('name');

Only one transaction may be traced at a time. If you call startRequest and then later call startJob, the current transaction will be changed to the type job.

Timing

The start time of a transaction is set to when the transaction is created by default. Similarly the end time is set to the time a transaction is finished and sent.

// Start time set at the time startRequest is called
Apm::startRequest('POST', '/url');

// End time set at the time finish is called
Apm::finish();

To set a custom start/end time

// Time should be a unix timestamp in milliseconds
$time = microtime(true) * 1000;

Apm::setStartTime($time);
Apm::setEndTime($time);

finish() will not overwrite the end time if it's been manually set

Metadata

Environment

The environment can be optionally passed as a third argument to init()

Apm::init('...token', 'service-name', 'production');

or it can be set through the service metadata

Apm::service()->setEnvironment('production');

HTTP

HTTP metadata is collected by default from the $_SERVER superglobal, but can be customized as needed

Apm::http()
    ->setMethod('PUT')
    ->setUrl('/some/path/:id')
    ->setUrlParams(['id' => 22])
    ->setHeaders(['x-forwarded-for' => 'example.com']);

For best practice the URL should be normalized to not include dynamic parts that change often but represent the same request. For example, instead of /posts/24, set the URL to be /posts/:id, and then send a URL param metadata with the ID of 24 instead.*

Hostname

To customize the hostname for a transaction

Apm::system()->setHostname('host-123');

User

User information can be attached to a transaction when known

Apm::user()->setId(24);
Apm::user()->setEmail('user@example.com');

Custom metadata

Any key/value pair can be set to pass custom metadata for a transaction

Apm::tags()
    ->set('version', '2.4')
    ->set('variation', 'b');