Set Up Metrics

With Sentry Metrics, you can send counters, gauges, and distributions from your applications to Sentry. Once in Sentry, these metrics can be viewed alongside relevant errors, and searched using their individual attributes.

Requirements

Metrics for Native are supported in Sentry Native SDK version 0.12.6 and above.

Usage

To enable metrics, set the enable_metrics option during SDK initialization:

sentry_options_t *options = sentry_options_new();
sentry_options_set_enable_metrics(options, true);
// set other options
sentry_init(options);

Once enabled, you can send metrics using the sentry_metrics_*() APIs.

Metric Types

Counters

Track the number of times something happens:

sentry_metrics_count("api.requests", 1, sentry_value_new_null());

Gauges

Track current values that can go up or down:

sentry_metrics_gauge("active_connections", 42, NULL, sentry_value_new_null());

Distributions

Track a range of values (e.g., response times):

sentry_metrics_distribution("response.time", 150.5, SENTRY_UNIT_MILLISECOND, sentry_value_new_null());

Custom Attributes

Add attributes to filter and group metrics in Sentry:

sentry_value_t attributes = sentry_value_new_object();
sentry_value_set_by_key(attributes, "endpoint",
    sentry_value_new_attribute(sentry_value_new_string("/api/orders"), NULL));
sentry_value_set_by_key(attributes, "region",
    sentry_value_new_attribute(sentry_value_new_string("us-west"), NULL));

sentry_metrics_count("api.calls", 1, attributes);

When no custom attributes are needed, pass sentry_value_new_null().

Units

For gauge and distribution metrics, specify a unit to help Sentry display values in a human-readable format. The SDK provides SENTRY_UNIT_* constants for common units like SENTRY_UNIT_MILLISECOND, SENTRY_UNIT_BYTE, etc. Pass NULL when no specific unit applies.

sentry_metrics_gauge("memory.usage", 1024, SENTRY_UNIT_BYTE, sentry_value_new_null());
sentry_metrics_distribution("latency", 42.5, SENTRY_UNIT_MILLISECOND, sentry_value_new_null());

Options

before_send_metric

To filter metrics or modify them before they are sent to Sentry, use the before_send_metric option:

static sentry_value_t
before_send_metric_callback(sentry_value_t metric, void *user_data)
{
    (void)user_data;

    // Drop metrics with specific attributes
    sentry_value_t attributes = sentry_value_get_by_key(metric, "attributes");
    if (!sentry_value_is_null(sentry_value_get_by_key(attributes, "debug"))) {
        sentry_value_decref(metric);
        return sentry_value_new_null();
    }

    // Return the metric to send it
    return metric;
}

sentry_options_set_before_send_metric(options, before_send_metric_callback, NULL);

The before_send_metric function receives a metric object and optional user_data, and should return the metric object if you want it to be sent to Sentry, or it should free the metric using sentry_value_decref(metric) and return a sentry_value_new_null() if you want to discard it.

Default Attributes

The Native SDK automatically attaches the following attributes to every metric:

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.
• 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.

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.