Laravel 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

The Laravel integration automatically starts the transaction and sets its type to request by default. In a future release the job type will be set and started for queue jobs, cron jobs, etc. automatically as well.

Manually change the type and name

By default the type is set to request and the name is a representation of METHOD + ROUTE. You may manually adjust the transaction type and name at any point.

use Tail\Apm\Transaction;

app('tail')->transaction()->setType(Transaction::TYPE_JOB);
app('tail')->transaction()->setName('some-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.

To set a custom start/end time

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

app('tail')->transaction()->setStartTime($time);
app('tail')->transaction()->setEndTime($time);

Metadata

Environment

To customize the environment tag on a transaction

app('tail')->transaction()->service()->setEnvironment('production');

HTTP

HTTP metadata is collected by default from the $_SERVER superglobal and Laravel's router, but can be customized as needed

app('tail')->transaction()->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

app('tail')->transaction()->system()->setHostname('host-123');

User

User information can be attached to a transaction when known

app('tail')->transaction()->user()->setId(24);
app('tail')->transaction()->user()->setEmail('user@example.com');

Custom metadata

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

app('tail')->transaction()->tags()
    ->set('version', '2.4')
    ->set('variation', 'b');