feat(metrics): [Trace Metrics 5] Add batch processor for Metrics

[adinauer]

📜 Description

💡 Motivation and Context

💚 How did you test it?

📝 Checklist

• I added GH Issue ID & Linear ID
• I added tests to verify the changes.
• No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
• I updated the docs if needed.
• I updated the wizard if needed.
• Review from the native team if needed.
• No breaking change or entry added to the changelog.
• No breaking change for hybrid SDKs or communicated to hybrid SDKs.

🔮 Next steps

[adinauer]

• feat(metrics): [Trace Metrics 27] Automatically use SentryOptions.Metrics.BeforeSendMetricCallback Spring beans #5021 : 2 dependent PRs (#5022 , #5024 )
• feat(metrics): [Trace Metrics 26] SentryMetricsParameters create shortcut for attributes map #5020
• feat(metrics): [Trace Metrics 25] Add Hint to Metrics #5019
• feat(metrics): [Trace Metrics 24] PR Feedback #5013
• feat(metrics): [Trace Metrics 23] Add E2E tests for Metrics #5011
• feat(metrics): [Trace Metrics 22] Close and flush MetricsBatchProcessor from SentryClient #5010
• Use uv for managing python version #5009
• feat(metrics): [Trace Metrics 21] Add AI rules files for Metrics (and update feature flags rule) #5008
• feat(metrics): [Trace Metrics 20] Add device and OS attributes to metrics #5007
• feat(metrics): [Trace Metrics 19] Create SentryMetricsParameters for Metrics #5006
• feat(metrics): [Trace Metrics 18] Add unit tests for Metrics #5005
• feat(metrics): [Trace Metrics 17] Remove Experimental Annotation from Metrics Options #4996
• feat(metrics): [Trace Metrics 16] Only send user attributes if sendDefaultPii is true #4995
• feat(metrics): [Trace Metrics 15] Android Metrics batch processor and factory #4994
• feat(metrics): [Trace Metrics 14] Metrics Manifest options for Android #4993
• feat(metrics): [Trace Metrics 13] Metrics external options #4992
• feat(metrics): [Trace Metrics 12] Record client report for discarded metrics envelope item #4991
• feat(metrics): [Trace Metrics 11] Metrics Envelope item deserialization #4990
• feat(metrics): [Trace Metrics 10] Metrics Gauge API #4989
• feat(metrics): [Trace Metrics 9] Metrics Distribution API #4988
• feat(metrics): [Trace Metrics 8] Metrics Count API #4987
• feat(metrics): [Trace Metrics 7] Metrics counter basic API #4986
• feat(metrics): [Trace Metrics 6] Implement SentryClient for Metrics #4985
• feat(metrics): [Trace Metrics 5] Add batch processor for Metrics #4984 👈 (View in Graphite)
• feat(metrics): [Trace Metrics 4] Add transport types for metrics #4983
• feat(metrics): [Trace Metrics 3] Enable metrics by default #4982
• feat(metrics): [Trace Metrics 2] MetricsApi stub #4981
• feat(metrics): [Trace Metrics 1] Metrics Options #4980
• feat/trace-metrics

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

	Fails
🚫	Please consider adding a changelog entry for the next release.

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

Instructions and example for changelog

Please add an entry to CHANGELOG.md to the "Unreleased" section. Make sure the entry includes this PR's number.

Example:

## Unreleased

### Features

- [Trace Metrics 5] Add batch processor for Metrics ([#4984](https://github.com/getsentry/sentry-java/pull/4984))

If none of the above apply, you can opt out of this check by adding #skip-changelog to the PR description or adding a skip-changelog label.

Generated by 🚫 dangerJS against ff0fe29

[markushi]

Looking good, just one concern within MetricsBatchProcessor.close() which I would like to discuss before merging.

[markushi]

h: Hmm if we have some customer emitting metrics in an endless loop, and the app/sdk gets closed - wouldn't this continue to call flushBatch()? Maybe it makes sense to have a isClosed flag to guard against that and early exit here + within add()

[adinauer]

in MetricsApi there's a check that should prevent adding anything after the SDK has closed down:

      if (!scopes.isEnabled()) {
        options
            .getLogger()
            .log(SentryLevel.WARNING, "Instance is disabled and this 'metrics' call is a no-op.");
        return;
      }

There might be an issue where this loops and the SDK can't set enabled to false, gonna verify.

[markushi]

Looks like this is the only place where hasScheduled is being used outside the scheduleLock, for consistency it could make sense to move this inside.

Suggested change

	if (hasScheduled && !forceSchedule) {
	return;
	}
	try (final @NotNull ISentryLifecycleToken ignored = scheduleLock.acquire()) {
	final @Nullable Future<?> latestScheduledFlush = scheduledFlush;
	try (final @NotNull ISentryLifecycleToken ignored = scheduleLock.acquire()) {
	if (hasScheduled && !forceSchedule) {
	return;
	}
	final @Nullable Future<?> latestScheduledFlush = scheduledFlush;

[adinauer]

The idea here was to avoid waiting for the lock when scheduling has already happened anyways.

The code checks whether queue is empty before hasScheduled = false.
Do you think ensuring this check is correct warrants the performance hit from acquiring the lock for each metric added?

[markushi]

Do you think ensuring this check is correct warrants the performance hit from acquiring the lock for each metric added?

No not at all 😅 I totally overlooked this is being called as part of every metric emission, all good then!

[cursor]

Static lock shared across instances causes concurrency issues

Medium Severity

The scheduleLock field is declared as static final, meaning all instances of MetricsBatchProcessor share the same lock. However, the fields it protects (scheduledFlush, hasScheduled) are instance variables. When multiple processor instances exist (e.g., after SDK reinitialization), one instance's lock acquisition blocks another independent instance, and the hasScheduled state can become incorrectly coordinated across unrelated instances.

 

[adinauer]

@sentry review