Set Up Metrics

Sentry metrics help you pinpoint and solve issues that impact user experience and app performance by measuring the data points that are important to you. You can track things like processing time, event size, user signups, and conversion rates, then correlate them back to tracing data in order to get deeper insights and solve issues faster.

Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.

Requirements

• Laravel SDK version 4.20.0 or above.

Usage

Metrics are enabled by default in the PHP SDK. After the SDK is initialized, you can send metric data through \Sentry\trace_metrics(), which acts as the entry point for recording counts, gauges, and distributions.

The SDK buffers up to 1000 metric entries at a time. Once that limit is reached, it keeps only the most recent 1000. If you need to retain more than that, flush the metrics periodically before you exceed the buffer.

Emit a Counter

Counters are one of the more basic types of metrics and can be used to count certain event occurrences.

To emit a counter, do the following:

// Record five total button clicks
\Sentry\trace_metrics()->count('button-click', 5, ['browser' => 'Firefox', 'app_version' => '1.0.0']);

Emit a Distribution

Distributions help you get the most insights from your data by allowing you to obtain aggregations such as p90, min, max, and avg.

To emit a distribution, do the following:

use \Sentry\Metrics\Unit;

// Add '15.0' to a distribution used for tracking the loading times per page.
\Sentry\trace_metrics()->distribution('page-load', 15.0, ['page' => '/home'], Unit::millisecond());

Emit a Gauge

Gauges let you obtain aggregates like min, max, avg, sum, and count. Gauges can not be used to represent percentiles. If percentiles aren't important to you, we recommend using gauges.

To emit a gauge, do the following:

use \Sentry\Metrics\Unit;

// Add '15.0' to a gauge used for tracking the loading times per page.
\Sentry\trace_metrics()->gauge('page-load', 15.0, ['page' => '/home'], Unit::millisecond());

Flush

Metrics are flushed and sent to Sentry at the end of each request or command.

If you emit more than 1000 metrics per request or command, make sure to manually flush to prevent losing metrics.

\Sentry\trace_metrics()->flush();

Options

before_send_metric

To filter metrics, or update them before they are sent to Sentry, you can use the before_send_metric option. If the callback returns null, the metric is not emitted. Attributes can also be updated in the callback function.

use \Sentry\Metrics\Types\AbstractType;

\Sentry\init([
    'dsn' => '___PUBLIC_DSN___',
    'before_send_metric' => static function (AbstractType $metric): ?AbstractType {
        if ($metric->getName() === 'removed-metric') {
            return null;
        }
        return $metric;
    }
]);

The before_send_metric function receives a metric object, and should return the metric object if you want it to be sent to Sentry, or null if you want to discard it.

Default Attributes

The PHP SDK automatically sets several default attributes on all metrics to provide context and improve debugging:

Core Attributes

• environment: The environment set in the SDK if defined. This is sent from the SDK as sentry.environment.
• release: The release set in the SDK if defined. This is sent from the SDK as sentry.release.
• trace.parent_span_id: The span ID of the span that was active when the metric was collected (only set if there was an active span). This is sent from the SDK as sentry.trace.parent_span_id.
• sdk.name: The name of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.name.
• sdk.version: The version of the SDK that sent the metric. This is sent from the SDK as sentry.sdk.version.

Server Attributes

• server.address: The address of the server that sent the metric. Equivalent to server_name that gets attached to Sentry errors.

User Attributes

If user information is available in the current scope, the following attributes are added to the metric:

• user.id: The user ID.
• user.name: The username.
• user.email: The email address.