feat(metrics): [Trace Metrics 21] Add AI rules files for Metrics (and update feature flags rule)

.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
+---
+# Java SDK Metrics
+
+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).