PHP custom instrumentation

The AppSignal for PHP package provides out-of-the-box instrumentations for your PHP application. However, sometimes you need fine-grained observability, which requires manual instrumentation. For these cases, use the Appsignal::instrument method and customize the data sent to AppSignal using the helper methods.

Data sent to AppSignal must not contain any personal data, such as names or email addresses. Sanitize your application’s data before sending it to AppSignal. If you need to identify a person, use alternatives like a user ID, hash, or pseudonym.

Creating spans

The Appsignal class provides a helper for creating spans.

`instrument`

Creates and activates a new span. Pass a closure to have the span closed automatically, or omit it to manage the span lifecycle manually.

With a closure

If you use a closure, AppSignal closes the active span automatically.

PHP

Appsignal::instrument(
	name: 'process-order',
	attributes: ['order_id' => $orderId],
	closure: function () {
		// do work here
		Appsignal::setAttributes(['order_status' => 'processed']);
	},
);

Without a closure

Without a closure, the instrument method returns an instance of the ActiveSpan class, a thin wrapper around the OpenTelemetry span and its scope. Close this span manually by calling $span->end().

PHP

$activeSpan = Appsignal::instrument(
	name: 'upload-file',
	attributes: ['file_name' => $filename],
);

try {
    uploadFile($file);
} catch (Throwable $e) {
    Appsignal::setError($e);
} finally {
    $activeSpan->end();
}

Helpers

The base Appsignal class provides helper methods to add custom data to traces or spans. The following sections describe each helper.

The code examples below assume your code is already being instrumented (for example, inside a Laravel or Symfony route handler). If your code is not already instrumented, you must create a root span by calling Appsignal::instrument() and use the helpers inside of it.

`addAttributes`

Add attributes to the current span.

PHP

Appsignal::addAttributes([
    'user_id'   => $user->id,
    'user_plan' => $user->plan,
]);

`addHeaders`

Adds request headers to the current span. If the header name already exists, the value is overwritten. Request headers are shown for sampled traces in AppSignal. See the Request header customization guide for more information.

PHP

Appsignal::addHeaders(['custom-header' => 'some-value']);

`addTags`

Add tags to the current span. Tags appear as filterable metadata in AppSignal and are prefixed with appsignal.tag. internally.

PHP

Appsignal::addTags([
    'locale'  => 'en',
    'version' => '2.1.0',
]);

See the tagging guide for more information on how tags work in AppSignal.

`setAction`

Sets the action name on the current span. AppSignal displays this as the transaction name and uses it to group samples.

PHP

Appsignal::setAction('OrdersController::create');

`setNamespace`

Sets the namespace of the root span.

PHP

Appsignal::setNamespace('admin');

`setParams`

Set the query parameters of the incoming request. The $params must be a value that can be serialized as JSON.

PHP

$params = [
    'param1' => 'value1',
    'param2' => 'value2',
    'nested' => [
        'param3' => 'value3',
        'param4' => 'value4',
    ],
];

Appsignal::setParams($params);

`setPayload`

Set the payload of the incoming request. The $payload must be a value that can be serialized as JSON.

PHP

$payload = [
    'key1' => 'value1',
    'key2' => 'value2',
    'nested' => [
        'key3' => 'value3',
        'key4' => 'value4',
    ],
];

Appsignal::setPayload($payload);

`ActiveSpan`

Appsignal::instrument() returns an ActiveSpan instance that proxies all standard OpenTelemetry API SpanInterface methods. If you need low-level control over the span, use these methods to attach data or events to it directly.

PHP

$activeSpan = Appsignal::instrument('render-report');
$activeSpan->setAttribute('report.type', 'pdf');
$activeSpan->addEvent('rendering-started');

someExpensiveMethod();

$activeSpan->end();

AppSignal for Ruby

AppSignal for Elixir

AppSignal for Node.js

AppSignal for Front-end

AppSignal for Python

AppSignal for Go

AppSignal for Java

AppSignal for PHP

OpenTelemetry

Wrap

Collector

Standalone agent

Creating spans

`instrument`

With a closure

Without a closure

Helpers

`addAttributes`

`addHeaders`

`addTags`

`setAction`

`setNamespace`

`setParams`

`setPayload`

`ActiveSpan`

​Creating spans

​instrument

​With a closure

​Without a closure

​Helpers

​addAttributes

​addHeaders

​addTags

​setAction

​setNamespace

​setParams

​setPayload

​ActiveSpan

Creating spans

`instrument`

With a closure

Without a closure

Helpers

`addAttributes`

`addHeaders`

`addTags`

`setAction`

`setNamespace`

`setParams`

`setPayload`

`ActiveSpan`