Merge branch 'main' into fix/app-start-warm-detection

Author: markushi

.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"

.gitattributes

@@ -1,6 +1,8 @@
 * text eol=lf
 *.png binary
 *.jpg binary
+*.pb binary
+*.gz binary
 
 # These are explicitly windows files and should use crlf
 *.bat           text eol=crlf

.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

@@ -8,14 +8,29 @@
   - **IMPORTANT:** This disables collecting external storage size (total/free) by default, to enable it back
     use `options.isCollectExternalStorageContext = true` or `<meta-data android:name="io.sentry.external-storage-context" android:value="true" />`
 - Fix `NullPointerException` when reading ANR marker ([#4979](https://github.com/getsentry/sentry-java/pull/4979))
-- Improve app start type detection with main thread timing ([#4999](https://github.com/getsentry/sentry-java/pull/4999))
+- Report discarded log in batch processor as `log_byte` ([#4971](https://github.com/getsentry/sentry-java/pull/4971))
+- Fix warm app start type detection for edge cases ([#4999](https://github.com/getsentry/sentry-java/pull/4999))
 
 ### Improvements
 
 - Expose `MAX_EVENT_SIZE_BYTES` constant in SentryOptions ([#4962](https://github.com/getsentry/sentry-java/pull/4962))
 - Discard envelopes on `4xx` and `5xx` response ([#4950](https://github.com/getsentry/sentry-java/pull/4950))
   - This aims to not overwhelm Sentry after an outage or load shedding (including HTTP 429) where too many events are sent at once
 
+### Feature
+
+- 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
+  - For more details, see the Metrics documentation: https://docs.sentry.io/product/explore/metrics/getting-started/
+
 ## 8.29.0
 
 ### Fixes

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
+