feat(metrics): Trace Metrics (#5026)

* Metrics Options

* MetricsApi stub

* Add transport types for metrics

* Enable metrics by default

* Format code

* Add batch processor for Metrics

* Wire up Metrics parts

* Metrics counter basic API

* Metrics Count API

* Metrics Distribution API

* Metrics Gauge API

* Metrics Envelope item deserialization

* Record client report for discarded metrics envelope item

* Metrics external options

* Metrics Manifest options for Android

* Android Metrics batch processor and factory

* Only send user attributes if sendDefaultPii is true

* Remove Experimental Annotation from Metrics Options

* Add unit tests for Metrics

* Create SentryMetricsParameters for Metrics

* Use uv for managing python version

* fix

* Add device and OS attributes to metrics

* Add AI rules files for Metrics (and update feature flags rule)

* Close and flush MetricsBatchProcessor from SentryClient

* fix

* Add E2E tests for Metrics

* Final keyword in Metrics methods

* Add Hint to Metrics

* SentryMetricsParameters create shortcut for attributes map

* Automatically use SentryOptions.Metrics.BeforeSendMetricCallback Spring beans

* Rename sample API param, remove sleep

* Create MetricsUnit constants

* Format code

* Metrics Options (#4980)

* feat(metrics): [Trace Metrics 2] MetricsApi stub (#4981)

* Metrics Options

* MetricsApi stub

* More PR review changes (#5028)

* Some more PR review changes

* Format code

---------

Co-authored-by: Sentry Github Bot <[email protected]>

* changelog

* non nullable trace id

* error log now says metric instead of log

---------

Co-authored-by: Sentry Github Bot <[email protected]>
Co-authored-by: lcian <[email protected]>

Author: 3 people

.cursor/rules/feature_flags.mdc

@@ -10,15 +10,35 @@ There is a scope based and a span based API for tracking feature flag evaluation
 
 The `addFeatureFlag` method can be used to track feature flag evaluations. It exists on `Sentry` static API as well as `IScopes` and `IScope`.
 
+When using static API, `IScopes` or COMBINED scope type, Sentry will also invoke `addFeatureFlag` on the current span. This does not happen, when directly invoking `addFeatureFlag` on `IScope` (except for COMBINED scope type).
+
 The `maxFeatureFlags` option controls how many flags are tracked per scope and also how many are sent to Sentry as part of events.
 Scope based feature flags can also be disabled by setting the value to 0. Defaults to 100 feature flag evaluations.
 
 Order of feature flag evaluations is important as we only keep track of the last {maxFeatureFlag} items.
 
-When a feature flag evluation with the same name is added, the previous one is removed and the new one is stored so that it'll be dropped last.
+When a feature flag evaluation with the same name is added, the previous one is removed and the new one is stored so that it'll be dropped last.
+Refer to `FeatureFlagBuffer` fore more details. `FeatureFlagBuffer` has been optimized for storing scope based feature flag evaluations, especially clone performance.
 
-When sending out an error event, feature flag buffers from all three scope types (global, isolation and current scope) are merged, chosing the newest {maxFeatureFlag} entries across all scope types. Feature flags are sent as part of the `flags` context.
+When sending out an error event, feature flag buffers from all three scope types (global, isolation and current scope) are merged, choosing the newest {maxFeatureFlag} entries across all scope types. Feature flags are sent as part of the `flags` context.
 
 ## Span Based API
 
-tbd
+It's also possible to use the `addFeatureFlag` method on `ISpan` (and by extension `ITransaction`). Feature flag evaluations tracked this way
+will not be added to the scope and thus won't be added to error events.
+
+Each span has its own `SpanFeatureFlagBuffer`. When starting a child span, feature flag evaluations are NOT copied from the parent. Each span starts out with an empty buffer and has its own limit.
+`SpanFeatureFlagBuffer` has been optimized for storing feature flag evaluations on spans.
+
+Spans have a hard coded limit of 10 feature flag evaluations. When full, new entries are rejected. Updates to existing entries are still allowed even if full.
+
+## Integrations
+
+We offer integrations that automatically track feature flag evaluations.
+
+Android:
+- LaunchDarkly (`SentryLaunchDarklyAndroidHook`)
+
+JVM (non Android):
+- LaunchDarkly (`SentryLaunchDarklyServerHook`)
+- OpenFeature (`SentryOpenFeatureHook`)

.cursor/rules/metrics.mdc

@@ -0,0 +1,26 @@
+---
+alwaysApply: false
+description: Metrics API
+---
+# Java SDK Metrics API
+
+Metrics are enabled by default.
+
+API has been namespaced under `Sentry.metrics()` and `IScopes.metrics()` using the `IMetricsApi` interface and `MetricsApi` implementation.
+
+Options are namespaced under `SentryOptions.getMetrics()`.
+
+Three different APIs exist:
+- `count`: Counters are one of the more basic types of metrics and can be used to count certain event occurrences.
+- `distribution`: Distributions help you get the most insights from your data by allowing you to obtain aggregations such as p90, min, max, and avg.
+- `gauge`: Gauges let you obtain aggregates like min, max, avg, sum, and count. They can be represented in a more space-efficient way than distributions, but they can't be used to get percentiles. If percentiles aren't important to you, we recommend using gauges.
+
+Refer to `SentryMetricsEvent` for details about available fields.
+
+`MetricsBatchProcessor` handles batching (`MAX_BATCH_SIZE`), automatic sending of metrics after a timeout (`FLUSH_AFTER_MS`) and rejecting if `MAX_QUEUE_SIZE` has been hit.
+
+The flow is `IMetricsApi` -> `IMetricsBatchProcessor` -> `SentryClient.captureBatchedMetricsEvents` -> `ITransport`.
+
+Each `SentryMetricsEvent` goes through `SentryOptions.metrics.beforeSend` (if configured) and can be modified or dropped.
+
+For sending, a batch of `SentryMetricsEvent` objects is sent inside a `SentryMetricsEvents` object.

.cursor/rules/overview_dev.mdc

@@ -37,10 +37,21 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
 - **`feature_flags`**: Use when working with:
   - Feature flag tracking and evaluation
   - `addFeatureFlag()`, `getFeatureFlags()` methods
-  - `FeatureFlagBuffer`, `FeatureFlag` protocol
+  - `FeatureFlagBuffer`, `SpanFeatureFlagBuffer`, `FeatureFlag` protocol
   - `maxFeatureFlags` option and buffer management
   - Feature flag merging across scope types
   - Scope-based vs span-based feature flag APIs
+  - Scope-based API: `Sentry`, `IScopes`, `IScope` APIs
+  - Span-based API: `ISpan`, `ITransaction` APIs
+  - Integrations: LaunchDarkly (Android/JVM), OpenFeature (JVM)
+
+- **`metrics`**: Use when working with:
+  - Metrics API (`Sentry.metrics()`, `IScopes.metrics()`)
+  - `IMetricsApi`, `MetricsApi` implementation
+  - Metrics types: `count`, `distribution`, `gauge`
+  - `MetricsBatchProcessor`, batching and queue management
+  - `SentryMetricsEvent`, `SentryMetricsEvents`
+  - `SentryOptions.getMetrics()`, `beforeSend` callback
 
 ### Integration & Infrastructure
 - **`opentelemetry`**: Use when working with:
@@ -72,3 +83,4 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
    - Cache/offline/network → `offline`
    - System test/e2e/sample → `e2e_tests`
    - Feature flag/addFeatureFlag/flag evaluation → `feature_flags`
+   - Metrics/count/distribution/gauge → `metrics`

.cursor/rules/scopes.mdc

@@ -49,6 +49,15 @@ Data is also passed on to newly forked child scopes but not to parents.
 
 Current scope can be retrieved from `Scopes` via `getScope`.
 
+### Combined Scope
+
+This is a special scope type that combines global, isolation and current scope.
+
+Refer to `CombinedScopeView` for each field of interest to see whether values from the three individual scopes are merged,
+whether a specific one is used or whether we're simply using the first one that has a value.
+
+Also see the section about `defaultScopeType` further down.
+
 ## Storage of `Scopes`
 
 `Scopes` are stored in a `ThreadLocal` by default (NOTE: this is different for OpenTelemetry, see opentelemetry.mdc).

.envrc

@@ -1,2 +1,3 @@
-export VIRTUAL_ENV=".venv"
-layout python3
+export VIRTUAL_ENV="${PWD}/.venv"
+devenv sync
+PATH_add "${PWD}/.venv/bin"

.gitignore

@@ -27,3 +27,4 @@ spring-server.txt
 spy.log
 .kotlin
 **/tomcat.8080/webapps/
+**/__pycache__

.python-version

@@ -0,0 +1 @@
+3.13.3

CHANGELOG.md

@@ -20,6 +20,13 @@
 - Add a Tombstone integration that detects native crashes without relying on the NDK integration, but instead using `ApplicationExitInfo.REASON_CRASH_NATIVE` on Android 12+. ([#4933](https://github.com/getsentry/sentry-java/pull/4933))
   - Currently exposed via options as an _internal_ API only.
   - If enabled alongside the NDK integration, crashes will be reported as two separate events. Users should enable only one; deduplication between both integrations will be added in a future release.
+- Add Sentry Metrics to Java SDK ([#5026](https://github.com/getsentry/sentry-java/pull/5026))
+  - Metrics are enabled by default
+  - APIs are namespaced under `Sentry.metrics()`
+  - We offer the following APIs:
+    - `count`: A metric that increments counts
+    - `gauge`: A metric that tracks a value that can go up or down
+    - `distribution`: A metric that tracks the statistical distribution of values
 
 ## 8.29.0
 

devenv/config.ini

@@ -0,0 +1,16 @@
+[devenv]
+minimum_version = 1.22.1
+
+[uv]
+darwin_arm64 = https://github.com/astral-sh/uv/releases/download/0.8.2/uv-aarch64-apple-darwin.tar.gz
+darwin_arm64_sha256 = 954d24634d5f37fa26c7af75eb79893d11623fc81b4de4b82d60d1ade4bfca22
+darwin_x86_64 = https://github.com/astral-sh/uv/releases/download/0.8.2/uv-x86_64-apple-darwin.tar.gz
+darwin_x86_64_sha256 = ae755df53c8c2c1f3dfbee6e3d2e00be0dfbc9c9b4bdffdb040b96f43678b7ce
+linux_arm64 = https://github.com/astral-sh/uv/releases/download/0.8.2/uv-aarch64-unknown-linux-gnu.tar.gz
+linux_arm64_sha256 = 27da35ef54e9131c2e305de67dd59a07c19257882c6b1f3cf4d8d5fbb8eaf4ca
+linux_x86_64 = https://github.com/astral-sh/uv/releases/download/0.8.2/uv-x86_64-unknown-linux-gnu.tar.gz
+linux_x86_64_sha256 = 6dcb28a541868a455aefb2e8d4a1283dd6bf888605a2db710f0530cec888b0ad
+# used for autoupdate
+# NOTE: if using uv-build as a build backend, you'll have to make sure the versions match
+version = 0.8.2
+

devenv/sync.py

@@ -0,0 +1,23 @@
+from devenv import constants
+from devenv.lib import config, proc, uv
+import os
+
+def main(context: dict[str, str]) -> int:
+    reporoot = context["reporoot"]
+    cfg = config.get_repo(reporoot)
+
+    uv.install(
+        cfg["uv"]["version"],
+        cfg["uv"][constants.SYSTEM_MACHINE],
+        cfg["uv"][f"{constants.SYSTEM_MACHINE}_sha256"],
+        reporoot,
+    )
+
+    # reporoot/.venv is the default venv location
+    print(f"syncing .venv ...")
+    if not os.path.exists(".venv"):
+        proc.run(("uv", "venv", "--seed"))
+    proc.run(("uv", "sync", "--frozen", "--quiet"))
+
+    return 0
+