feat: metrics by jpnurmi · Pull Request #1498 · getsentry/sentry-native

jpnurmi · 2026-01-29T11:59:48Z

Summary

Implements the Sentry Metrics feature for the native SDK, allowing applications to record counter, gauge, and distribution metrics that are batched and sent to Sentry: https://develop.sentry.dev/sdk/telemetry/metrics/.

Closes #1453

Features

Three metric types: counter, gauge, and distribution
Batching: Metrics are buffered and sent in batches (same logic as logs - every 100 items or 5 seconds)
Attributes: Automatic default attributes (environment, release, SDK info) plus custom user attributes
Trace context: Metrics are automatically associated with the current trace/span
Hook: before_send_metric callback for filtering or modifying metrics before sending
Unit constants: Pre-defined SENTRY_UNIT_* constants for common telemetry units (byte, kilobyte, millisecond, second, etc.)
Parallel flush/close: Logs and metrics flush and shutdown operations run in parallel for faster sentry_flush() and sentry_close()

Public API

// Enable metrics
sentry_options_set_enable_metrics(options, true);

// Record metrics
sentry_metrics_count("api.requests", 1, sentry_value_new_null());
sentry_metrics_gauge("memory.usage", 1024, SENTRY_UNIT_BYTE, sentry_value_new_null());
sentry_metrics_distribution("response.time", 150.5, SENTRY_UNIT_MILLISECOND, attributes);

Considerations

The current API requires passing sentry_value_new_null() when no custom attributes are needed. An alternative would be to provide simplified variants without the attributes parameter (e.g., sentry_metrics_count()) alongside explicit variants (e.g., sentry_metrics_count_with_attributes()). Feedback welcome on which approach is preferred.

Dependencies

Test plan

Unit tests for all metric types (tests/unit/test_metrics.c)
Integration tests for HTTP transport (tests/test_integration_http.py)
Tests for custom attributes, before_send_metric hook, and disabled state
Crash-safe flush behavior tested

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Per the Sentry metrics specification, counter metrics should use 64-bit signed integers. This is consistent with sentry_value_new_int64 / sentry_value_as_int64 in sentry.h. Also refactored internal record_metric to pass sentry_value_t instead of double, allowing proper type preservation. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

The value parameter was not being decremented when metrics were disabled, causing a memory leak. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

SDKs "should offer constants or similar that help customers send in units we support" as specified in the developer docs. See: - https://develop.sentry.dev/sdk/telemetry/metrics/ - https://develop.sentry.dev/sdk/telemetry/attributes/#units Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Per the developer docs, units are only used for distribution and gauge metrics, not counters. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Split blocking shutdown and force_flush operations into begin (non-blocking trigger) and wait (blocking completion) phases. This allows logs and metrics operations to run in parallel in sentry_flush() and sentry_close(). Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add metrics integration tests to match the existing logs test coverage: - test_metrics_threaded: concurrent metrics from 50 threads - test_metrics_global_and_local_attributes_merge: global + local attributes - test_metrics_discarded_on_crash_no_backend: metrics discarded without backend - test_metrics_on_crash: parameterized test for inproc/breakpad backends Also refactor thread creation in example.c into a shared run_threads() helper function used by both logs-threads and metrics-threads commands. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Allow reusing attribute objects across multiple log calls, as documented. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Global attributes set via sentry_set_attribute() were not being merged into metrics. Now scope attributes are merged with user attributes having priority on conflicts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

github-actions · 2026-02-02T16:02:44Z

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against ca4a0e6

src/sentry_batcher.c

src/sentry_envelope.c

src/sentry_batcher.c

src/sentry_envelope.c

tests/test_integration_http.py

The split of force_flush into _begin() + _wait() introduced a race where _begin() wakes the batcher thread, but _wait() could return early if the batcher thread wins the race to acquire the flushing lock. This could cause sentry_flush() to return before data was actually sent. Fix by making sentry__batcher_flush return bool indicating success, and loop in _wait() until a flush actually completes. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Document metrics support for the Native SDK being added in getsentry/sentry-native#1498. Co-Authored-By: Claude <noreply@anthropic.com>

tustanivsky · 2026-02-04T08:45:36Z

include/sentry.h

+ * Records a counter metric. Counters track incrementing values like
+ * request counts or error counts.
+ */
+SENTRY_EXPERIMENTAL_API sentry_metrics_result_t sentry_metrics_count(


Android and Cocoa SDKs expose a unit parameter for count metrics - should we add this for native as well?

Good question. Some SDKs have a unit argument for the counter, while others don't. I also added it there at first, but decided to leave it out because it says in the docs:

The unit of measurement (only used for distribution and gauge)

https://develop.sentry.dev/sdk/telemetry/metrics/#method-signatures

The unit argument was removed from Cocoa:

fix(metrics)!: Remove unit from public API for counter sentry-cocoa#7358

During revision of the Method Signatures of the metrics API in the develop docs it was surfaced to me that count metrics do not accept a Metric Unit.

@tustanivsky Are you ok with leaving this as is? See Sentry Cocoa 9.4.0:

Breaking Changes

Sentry.metrics.count(..) does not support units, therefore the API was incorrectly defined. This breaking change applies to a method marked as experimental. (#7358)

JoshuaMoelans

nice work, LGTM! just one small nit on a docstring, and a follow-up for cleaning up our integration test structure

include/sentry.h

JoshuaMoelans · 2026-02-04T12:50:01Z

tests/test_integration_http.py

    split_log_request_cond,
    is_feedback_envelope,
    is_logs_envelope,
+    is_metrics_envelope,


(idea): this integration test file is becoming huge, maybe we should start splitting it up (e.g., additional files for metrics/logs/traces/proxy). I can create a follow-up PR 🧹

Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>

tests/unit/test_metrics.c

src/sentry_metrics.c

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

src/sentry_batcher.c

jpnurmi and others added 3 commits January 29, 2026 16:01

WIP: feat: metrics

65c23aa

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs: add changelog entry for metrics feature

a73c3bc

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs: add metrics to attribute documentation

875c3d9

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jpnurmi force-pushed the jpnurmi/feat/metrics branch from 422c6ad to 875c3d9 Compare January 29, 2026 15:01

jpnurmi changed the title ~~feat: metrics~~ WIP: feat: metrics Jan 29, 2026

jpnurmi and others added 10 commits January 29, 2026 17:18

Merge remote-tracking branch 'upstream/master' into jpnurmi/feat/metrics

0e56ebb

docs(metrics): document attributes ownership transfer

ccc3870

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix(metrics): fix memory leak when metrics disabled

52ff5d6

The value parameter was not being decremented when metrics were disabled, causing a memory leak. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

ref(metrics): remove unit parameter from sentry_metrics_count

941a1fa

Per the developer docs, units are only used for distribution and gauge metrics, not counters. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix(logs): avoid modifying custom per-log attributes (#1500)

8b0c9c6

Allow reusing attribute objects across multiple log calls, as documented. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix(metrics): scope attributes

725b062

Global attributes set via sentry_set_attribute() were not being merged into metrics. Now scope attributes are merged with user attributes having priority on conflicts. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

jpnurmi force-pushed the jpnurmi/feat/metrics branch from 48664ff to 725b062 Compare January 30, 2026 15:14

tustanivsky mentioned this pull request Feb 2, 2026

Add Metrics API support getsentry/sentry-unreal#1214

Draft

jpnurmi added 2 commits February 2, 2026 15:38

Merge remote-tracking branch 'upstream/master' into jpnurmi/feat/metrics

776400e

Update CHANGELOG.md

d9c5e27

jpnurmi marked this pull request as ready for review February 2, 2026 16:02

jpnurmi changed the title ~~WIP: feat: metrics~~ feat: metrics Feb 2, 2026

cursor bot reviewed Feb 2, 2026

View reviewed changes

src/sentry_batcher.c Show resolved Hide resolved

src/sentry_envelope.c Show resolved Hide resolved

jpnurmi added 2 commits February 2, 2026 18:36

fix batcher shutdown split thread lifecycle guard

898c169

consolidate sentry__envelope_add_logs/metrics shared helper

0326af9

sentry bot reviewed Feb 2, 2026

View reviewed changes

src/sentry_batcher.c Outdated Show resolved Hide resolved

cursor bot reviewed Feb 2, 2026

View reviewed changes

src/sentry_envelope.c Outdated Show resolved Hide resolved

tests/test_integration_http.py Outdated Show resolved Hide resolved

jpnurmi and others added 3 commits February 2, 2026 19:38

fix sentry__envelope_add_metrics

d9eec54

clean up unused import

0154bd5

jpnurmi requested review from JoshuaMoelans, mujacica and tustanivsky February 3, 2026 10:30

mujacica approved these changes Feb 3, 2026

View reviewed changes

jpnurmi added a commit to getsentry/sentry-docs that referenced this pull request Feb 3, 2026

feat(native): Add metrics documentation

53ef639

Document metrics support for the Native SDK being added in getsentry/sentry-native#1498. Co-Authored-By: Claude <noreply@anthropic.com>

jpnurmi mentioned this pull request Feb 3, 2026

feat(native): Add metrics documentation getsentry/sentry-docs#16249

Draft

6 tasks

tustanivsky reviewed Feb 4, 2026

View reviewed changes

JoshuaMoelans approved these changes Feb 4, 2026

View reviewed changes

jpnurmi and others added 2 commits February 4, 2026 13:56

Update include/sentry.h

a878869

Co-authored-by: JoshuaMoelans <60878493+JoshuaMoelans@users.noreply.github.com>

Fix formatting

3bff6c7

cursor bot reviewed Feb 4, 2026

View reviewed changes

tests/unit/test_metrics.c Show resolved Hide resolved

Add missing test for batching

9478d36

cursor bot reviewed Feb 4, 2026

View reviewed changes

src/sentry_metrics.c Show resolved Hide resolved

Fix redundant batch_func initialization in batchers

480f943

sentry bot reviewed Feb 4, 2026

View reviewed changes

src/sentry_metrics.c Show resolved Hide resolved

Keep static batch_func initializer

ca4a0e6

cursor bot reviewed Feb 4, 2026

View reviewed changes

src/sentry_batcher.c Show resolved Hide resolved

Uh oh!

Conversation

jpnurmi commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Features

Public API

Considerations

Dependencies

Test plan

Uh oh!

github-actions bot commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tustanivsky Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

jpnurmi Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

jpnurmi Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

jpnurmi Feb 4, 2026

Choose a reason for hiding this comment

Breaking Changes

Uh oh!

JoshuaMoelans left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

JoshuaMoelans Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jpnurmi commented Jan 29, 2026 •

edited

Loading

github-actions bot commented Feb 2, 2026 •

edited

Loading