---
title: "Metrics"
description: "Metrics allow you to send, view and query counters, gauges and measurements from your Sentry-configured apps to track application health and drill down into related traces, logs, and errors."
url: https://docs.sentry.io/platforms/native/metrics/
---

# Set Up Metrics | Sentry for Native

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.

This feature is currently in open beta. Features in beta are still in progress and may have bugs.

## [Requirements](https://docs.sentry.io/platforms/native/metrics.md#requirements)

Metrics for Native are supported in Sentry Native SDK version [0.12.6](https://github.com/getsentry/sentry-native/releases/tag/0.12.6) and above.

## [Usage](https://docs.sentry.io/platforms/native/metrics.md#usage)

Metrics are enabled by default. To disable metrics, set the `enable_metrics` option to `false` during SDK initialization:

```c
sentry_options_t *options = sentry_options_new();
sentry_options_set_enable_metrics(options, false);
// set other options
sentry_init(options);
```

You can send metrics using the `sentry_metrics_*()` APIs.

### [Metric Types](https://docs.sentry.io/platforms/native/metrics.md#metric-types)

| Type           | Use For                                      |
| -------------- | -------------------------------------------- |
| `count`        | Events (orders, clicks, API calls)           |
| `gauge`        | Current values (queue depth, connections)    |
| `distribution` | Value ranges (response times, payload sizes) |

### [Counters](https://docs.sentry.io/platforms/native/metrics.md#counters)

Track the number of times something happens:

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

### [Gauges](https://docs.sentry.io/platforms/native/metrics.md#gauges)

Track current values that can go up or down:

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

### [Distributions](https://docs.sentry.io/platforms/native/metrics.md#distributions)

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

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

### [Custom Attributes](https://docs.sentry.io/platforms/native/metrics.md#custom-attributes)

Add attributes to filter and group metrics in Sentry:

```c
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](https://docs.sentry.io/platforms/native/metrics.md#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.

```c
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](https://docs.sentry.io/platforms/native/metrics.md#options)

### [before\_send\_metric](https://docs.sentry.io/platforms/native/metrics.md#before_send_metric)

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

```c
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](https://docs.sentry.io/platforms/native/metrics.md#default-attributes)

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

### [Core Attributes](https://docs.sentry.io/platforms/native/metrics.md#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](https://docs.sentry.io/platforms/native/metrics.md#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.