From 53ef6398fee2f411a462992a66655fb03edaa76b Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Tue, 3 Feb 2026 14:17:55 +0100 Subject: [PATCH 1/5] feat(native): Add metrics documentation Document metrics support for the Native SDK being added in getsentry/sentry-native#1498. Co-Authored-By: Claude --- docs/platforms/native/metrics/index.mdx | 30 +++++++ .../metrics/default-attributes/native.mdx | 10 +++ platform-includes/metrics/options/native.mdx | 34 ++++++++ .../metrics/requirements/native.mdx | 1 + platform-includes/metrics/usage/native.mdx | 87 +++++++++++++++++++ 5 files changed, 162 insertions(+) create mode 100644 docs/platforms/native/metrics/index.mdx create mode 100644 platform-includes/metrics/default-attributes/native.mdx create mode 100644 platform-includes/metrics/options/native.mdx create mode 100644 platform-includes/metrics/requirements/native.mdx create mode 100644 platform-includes/metrics/usage/native.mdx diff --git a/docs/platforms/native/metrics/index.mdx b/docs/platforms/native/metrics/index.mdx new file mode 100644 index 0000000000000..88f1d492f0d0a --- /dev/null +++ b/docs/platforms/native/metrics/index.mdx @@ -0,0 +1,30 @@ +--- +title: Set Up Metrics +sidebar_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." +sidebar_order: 5756 +beta: true +--- + +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 + + + +## Usage + + + +## Options + + + +## Default Attributes + + diff --git a/platform-includes/metrics/default-attributes/native.mdx b/platform-includes/metrics/default-attributes/native.mdx new file mode 100644 index 0000000000000..9843fc2025bde --- /dev/null +++ b/platform-includes/metrics/default-attributes/native.mdx @@ -0,0 +1,10 @@ +Sentry automatically attaches these attributes to every metric: + +| Attribute | Description | +| -------------------- | ------------------------------- | +| `sentry.environment` | Environment from SDK config | +| `sentry.release` | Release version from SDK config | +| `sentry.sdk.name` | SDK name | +| `sentry.sdk.version` | SDK version | + +Metrics are also automatically associated with the current trace context when available. diff --git a/platform-includes/metrics/options/native.mdx b/platform-includes/metrics/options/native.mdx new file mode 100644 index 0000000000000..3d0ec3f7da104 --- /dev/null +++ b/platform-includes/metrics/options/native.mdx @@ -0,0 +1,34 @@ +### 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); +``` + +Return the metric to send it, or free it with `sentry_value_decref()` and return `sentry_value_new_null()` to discard it. + +### Disable Metrics + +To disable metrics collection entirely, set the `enable_metrics` option to `false`: + +```c +sentry_options_t *options = sentry_options_new(); +sentry_options_set_enable_metrics(options, false); +``` diff --git a/platform-includes/metrics/requirements/native.mdx b/platform-includes/metrics/requirements/native.mdx new file mode 100644 index 0000000000000..dcc2160db50fb --- /dev/null +++ b/platform-includes/metrics/requirements/native.mdx @@ -0,0 +1 @@ +Metrics for Native are supported in Sentry Native SDK version [X.X.X](https://github.com/getsentry/sentry-native/releases/tag/X.X.X) and above. diff --git a/platform-includes/metrics/usage/native.mdx b/platform-includes/metrics/usage/native.mdx new file mode 100644 index 0000000000000..58d4d0a882804 --- /dev/null +++ b/platform-includes/metrics/usage/native.mdx @@ -0,0 +1,87 @@ +To enable metrics, set the `enable_metrics` option during SDK initialization: + +```c +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 + +| Type | Use For | +| -------------- | -------------------------------------------- | +| `count` | Events (orders, clicks, API calls) | +| `gauge` | Current values (queue depth, connections) | +| `distribution` | Value ranges (response times, payload sizes) | + +### Counters + +Track the number of times something happens: + +```c +sentry_metrics_count("api.requests", 1, sentry_value_new_null()); +``` + +### Gauges + +Track current values that can go up or down: + +```c +sentry_metrics_gauge("active_connections", 42, NULL, sentry_value_new_null()); +``` + +### 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 + +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 + +For `gauge` and `distribution` metrics, specify a unit to help Sentry display values in a human-readable format. The SDK provides predefined unit constants: + +| Constant | Unit | +| ------------------------- | ----------- | +| `SENTRY_UNIT_NANOSECOND` | nanosecond | +| `SENTRY_UNIT_MICROSECOND` | microsecond | +| `SENTRY_UNIT_MILLISECOND` | millisecond | +| `SENTRY_UNIT_SECOND` | second | +| `SENTRY_UNIT_MINUTE` | minute | +| `SENTRY_UNIT_HOUR` | hour | +| `SENTRY_UNIT_DAY` | day | +| `SENTRY_UNIT_WEEK` | week | +| `SENTRY_UNIT_BYTE` | byte | +| `SENTRY_UNIT_KILOBYTE` | kilobyte | +| `SENTRY_UNIT_MEGABYTE` | megabyte | +| `SENTRY_UNIT_GIGABYTE` | gigabyte | +| `SENTRY_UNIT_TERABYTE` | terabyte | + +Example: + +```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()); +``` + +Pass `NULL` as the unit when not needed (counters, or when no specific unit applies). From 6170271d607acc1a49069e49292b605c11693969 Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Tue, 3 Feb 2026 15:10:58 +0100 Subject: [PATCH 2/5] fix(native): Simplify metrics documentation - Remove disable metrics section (not enabled by default) - Simplify units section (fewer examples) - Use shared include for default attributes Co-Authored-By: Claude --- .../metrics/default-attributes/native.mdx | 9 ++------ platform-includes/metrics/options/native.mdx | 9 -------- platform-includes/metrics/usage/native.mdx | 22 +------------------ 3 files changed, 3 insertions(+), 37 deletions(-) diff --git a/platform-includes/metrics/default-attributes/native.mdx b/platform-includes/metrics/default-attributes/native.mdx index 9843fc2025bde..1cbf6be26c862 100644 --- a/platform-includes/metrics/default-attributes/native.mdx +++ b/platform-includes/metrics/default-attributes/native.mdx @@ -1,10 +1,5 @@ -Sentry automatically attaches these attributes to every metric: +The Native SDK automatically attaches the following attributes to every metric: -| Attribute | Description | -| -------------------- | ------------------------------- | -| `sentry.environment` | Environment from SDK config | -| `sentry.release` | Release version from SDK config | -| `sentry.sdk.name` | SDK name | -| `sentry.sdk.version` | SDK version | + Metrics are also automatically associated with the current trace context when available. diff --git a/platform-includes/metrics/options/native.mdx b/platform-includes/metrics/options/native.mdx index 3d0ec3f7da104..0e0a0c32871c9 100644 --- a/platform-includes/metrics/options/native.mdx +++ b/platform-includes/metrics/options/native.mdx @@ -23,12 +23,3 @@ sentry_options_set_before_send_metric(options, before_send_metric_callback, NULL ``` Return the metric to send it, or free it with `sentry_value_decref()` and return `sentry_value_new_null()` to discard it. - -### Disable Metrics - -To disable metrics collection entirely, set the `enable_metrics` option to `false`: - -```c -sentry_options_t *options = sentry_options_new(); -sentry_options_set_enable_metrics(options, false); -``` diff --git a/platform-includes/metrics/usage/native.mdx b/platform-includes/metrics/usage/native.mdx index 58d4d0a882804..a3f382f70c4f5 100644 --- a/platform-includes/metrics/usage/native.mdx +++ b/platform-includes/metrics/usage/native.mdx @@ -59,29 +59,9 @@ 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 predefined unit constants: - -| Constant | Unit | -| ------------------------- | ----------- | -| `SENTRY_UNIT_NANOSECOND` | nanosecond | -| `SENTRY_UNIT_MICROSECOND` | microsecond | -| `SENTRY_UNIT_MILLISECOND` | millisecond | -| `SENTRY_UNIT_SECOND` | second | -| `SENTRY_UNIT_MINUTE` | minute | -| `SENTRY_UNIT_HOUR` | hour | -| `SENTRY_UNIT_DAY` | day | -| `SENTRY_UNIT_WEEK` | week | -| `SENTRY_UNIT_BYTE` | byte | -| `SENTRY_UNIT_KILOBYTE` | kilobyte | -| `SENTRY_UNIT_MEGABYTE` | megabyte | -| `SENTRY_UNIT_GIGABYTE` | gigabyte | -| `SENTRY_UNIT_TERABYTE` | terabyte | - -Example: +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()); ``` - -Pass `NULL` as the unit when not needed (counters, or when no specific unit applies). From 50039da373e4f980cbef76719e8504b9366dcc89 Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Thu, 5 Feb 2026 12:55:12 +0100 Subject: [PATCH 3/5] feat(native): Set minimum SDK version for metrics to 0.12.6 Co-Authored-By: Claude --- platform-includes/metrics/requirements/native.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform-includes/metrics/requirements/native.mdx b/platform-includes/metrics/requirements/native.mdx index dcc2160db50fb..3d6ce67ae2226 100644 --- a/platform-includes/metrics/requirements/native.mdx +++ b/platform-includes/metrics/requirements/native.mdx @@ -1 +1 @@ -Metrics for Native are supported in Sentry Native SDK version [X.X.X](https://github.com/getsentry/sentry-native/releases/tag/X.X.X) and above. +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. From ac39242e66a609f0ea4b85db37db10da593448ff Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Thu, 5 Feb 2026 13:06:54 +0100 Subject: [PATCH 4/5] fix(native): Sync metrics docs with logs Co-Authored-By: Claude --- platform-includes/metrics/default-attributes/native.mdx | 2 +- platform-includes/metrics/options/native.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/platform-includes/metrics/default-attributes/native.mdx b/platform-includes/metrics/default-attributes/native.mdx index 1cbf6be26c862..de3788ce95f18 100644 --- a/platform-includes/metrics/default-attributes/native.mdx +++ b/platform-includes/metrics/default-attributes/native.mdx @@ -2,4 +2,4 @@ The Native SDK automatically attaches the following attributes to every metric: -Metrics are also automatically associated with the current trace context when available. + diff --git a/platform-includes/metrics/options/native.mdx b/platform-includes/metrics/options/native.mdx index 0e0a0c32871c9..f434f21980e9d 100644 --- a/platform-includes/metrics/options/native.mdx +++ b/platform-includes/metrics/options/native.mdx @@ -22,4 +22,4 @@ before_send_metric_callback(sentry_value_t metric, void *user_data) sentry_options_set_before_send_metric(options, before_send_metric_callback, NULL); ``` -Return the metric to send it, or free it with `sentry_value_decref()` and return `sentry_value_new_null()` to discard it. +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. From 9e54304acc5ae0d985980524b1ca6408f6b83918 Mon Sep 17 00:00:00 2001 From: J-P Nurmi Date: Thu, 5 Feb 2026 13:47:36 +0100 Subject: [PATCH 5/5] Update docs/product/explore/metrics/getting-started/index.mdx --- docs/product/explore/metrics/getting-started/index.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/product/explore/metrics/getting-started/index.mdx b/docs/product/explore/metrics/getting-started/index.mdx index 914a9ba59bc53..367eb29662534 100644 --- a/docs/product/explore/metrics/getting-started/index.mdx +++ b/docs/product/explore/metrics/getting-started/index.mdx @@ -301,6 +301,14 @@ To set up Sentry Metrics, use the links below for supported SDKs. After it's bee url="/platforms/go/metrics/" /> +### Native + +- + ## Upcoming SDKs We're actively working on adding Metrics functionality to additional SDKs. Check out these GitHub issues for the latest updates: