split jvm and android profiling

Author: lbloder

.cursor/rules/overview_dev.mdc

@@ -53,15 +53,21 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
   - `SentryMetricsEvent`, `SentryMetricsEvents`
   - `SentryOptions.getMetrics()`, `beforeSend` callback
 
-- **`profiling`**: Use when working with:
-  - Continuous profiling (`sentry-async-profiler` module)
-  - `IContinuousProfiler`, `JavaContinuousProfiler`, `AndroidContinuousProfiler`
-  - `ProfileChunk`, chunk rotation and sending
+- **`profiling_jvm`**: Use when working with:
+  - JVM continuous profiling (`sentry-async-profiler` module)
+  - `IContinuousProfiler`, `JavaContinuousProfiler`
+  - `ProfileChunk`, chunk rotation, JFR file handling
   - `ProfileLifecycle` (MANUAL vs TRACE modes)
-  - `profilesSampleRate`, `profilingTracesHz`, `profileLifecycle` options
-  - Integration with rate limiting, offline caching, scopes
-  - JFR file handling, async-profiler integration
-  - Platform differences (JVM vs Android profiling)
+  - async-profiler integration, ServiceLoader discovery
+  - Rate limiting, offline caching, scopes integration
+
+- **`profiling_android`**: Use when working with:
+  - Android profiling (`sentry-android-core`)
+  - `AndroidContinuousProfiler`, `AndroidProfiler`, `AndroidTransactionProfiler`
+  - `Debug.startMethodTracingSampling()`, trace files
+  - Frame metrics, CPU, memory measurement collectors
+  - `SentryFrameMetricsCollector`, `SpanFrameMetricsCollector`
+  - App start profiling, `AndroidOptionsInitializer` setup
 
 ### Integration & Infrastructure
 - **`opentelemetry`**: Use when working with:
@@ -94,4 +100,5 @@ Use the `fetch_rules` tool to include these rules when working on specific areas
    - System test/e2e/sample → `e2e_tests`
    - Feature flag/addFeatureFlag/flag evaluation → `feature_flags`
    - Metrics/count/distribution/gauge → `metrics`
-   - Profiling/profiler/ProfileChunk/JFR → `profiling`
+   - JVM profiling/async-profiler/JFR/ProfileChunk → `profiling_jvm`
+   - Android profiling/AndroidProfiler/frame metrics/method tracing → `profiling_android`

.cursor/rules/profiling_android.mdc

@@ -0,0 +1,83 @@
+---
+alwaysApply: false
+description: Android Profiling (sentry-android-core)
+---
+# Android Profiling
+
+Android profiling lives in `sentry-android-core` and uses `Debug.startMethodTracingSampling()` for trace collection, with additional measurement collectors for frames, CPU, and memory.
+
+## Key Classes
+
+### `AndroidContinuousProfiler`
+- Implements `IContinuousProfiler` for continuous profiling across app lifecycle
+- Delegates to `AndroidProfiler` for actual trace collection
+- 60-second chunk duration (`MAX_CHUNK_DURATION_MILLIS`)
+- Platform: "android"
+- Maintains `rootSpanCounter` for TRACE mode, `profilerId` and `chunkId` per session/chunk
+- Collects measurements via `CompositePerformanceCollector` and `SentryFrameMetricsCollector`
+- Thread-safe with `lock` and `payloadLock`
+
+### `AndroidProfiler`
+- Low-level wrapper around `Debug.startMethodTracingSampling()`
+- Buffer size: 3MB, timeout: 30 seconds (for transaction profiling)
+- `start()`: Calls `Debug.startMethodTracingSampling(path, bufferSize, intervalUs)` and registers frame metrics listener
+- `endAndCollect()`: Stops tracing, collects measurements, returns `ProfileEndData` with trace file and measurements
+
+### `AndroidTransactionProfiler`
+- Implements `ITransactionProfiler` for per-transaction profiling (legacy)
+- `start()` / `bindTransaction()` / `onTransactionFinish()` lifecycle
+- Returns `ProfilingTraceData` on finish
+
+## Measurement Collectors
+
+- **`SentryFrameMetricsCollector`**: Frame metrics via `Window.OnFrameMetricsAvailableListener`
+  - Uses `Choreographer` reflection for frame start timestamps
+  - Tracks slow frames (> expected duration at refresh rate) and frozen frames (> 700ms)
+- **`AndroidMemoryCollector`**: Heap (`Runtime`) and native memory (`Debug.getNativeHeapSize()`)
+- **`AndroidCpuCollector`**: CPU usage from `/proc/self/stat`
+- **`SpanFrameMetricsCollector`**: Per-span frame metrics with interpolation
+
+## Measurements Included in Profile Chunks
+
+| Measurement | Unit | Source |
+|---|---|---|
+| Slow frame renders | nanoseconds | `SentryFrameMetricsCollector` |
+| Frozen frame renders | nanoseconds | `SentryFrameMetricsCollector` |
+| Screen frame rates | Hz | `SentryFrameMetricsCollector` |
+| CPU usage | percent | `AndroidCpuCollector` |
+| Memory footprint | bytes | `AndroidMemoryCollector` (heap) |
+| Native memory footprint | bytes | `AndroidMemoryCollector` (native) |
+
+## Configuration
+
+Same base options as JVM profiling (`profilesSampleRate`, `profileLifecycle`, `profilingTracesHz`), plus:
+- `profilingTracesDirPath` set automatically from app cache directory
+- Frame metrics collector initialized with Android `Context`
+- Setup in `AndroidOptionsInitializer.installDefaultIntegrations()`
+
+## Profiling Flow
+
+**Start**: `AndroidContinuousProfiler.start()` -> `AndroidProfiler.start()` -> `Debug.startMethodTracingSampling()` + register frame metrics listener + schedule 60s timeout
+
+**Chunk Rotation** (every 60s): Stop tracing -> collect measurements -> create `ProfileChunk.Builder` with measurements and trace file -> queue in `payloadBuilders` -> restart profiler
+
+**Sending**: `sendChunks()` builds each `ProfileChunk.Builder` and calls `scopes.captureProfileChunk()`
+
+**Lifecycle modes**: Same as JVM - MANUAL (explicit start/stop) and TRACE (`rootSpanCounter` for automatic lifecycle)
+
+## Initialization
+
+In `AndroidOptionsInitializer`:
+- `AndroidContinuousProfiler` created with `AndroidProfiler`, `BuildInfoProvider`, `SentryFrameMetricsCollector`
+- Profiler may already be running from app start profiling before SDK init
+- If already running at init, existing chunk ID is preserved
+
+## Code Locations
+
+- `sentry-android-core/src/main/java/io/sentry/android/core/AndroidContinuousProfiler.java`
+- `sentry-android-core/src/main/java/io/sentry/android/core/AndroidProfiler.java`
+- `sentry-android-core/src/main/java/io/sentry/android/core/AndroidTransactionProfiler.java`
+- `sentry-android-core/src/main/java/io/sentry/android/core/AndroidMemoryCollector.java`
+- `sentry-android-core/src/main/java/io/sentry/android/core/AndroidCpuCollector.java`
+- `sentry-android-core/src/main/java/io/sentry/android/core/SpanFrameMetricsCollector.java`
+- `sentry-android-core/src/main/java/io/sentry/android/core/internal/util/SentryFrameMetricsCollector.java`

.cursor/rules/profiling.mdc .cursor/rules/profiling_jvm.mdc.cursor/rules/profiling.mdc renamed to .cursor/rules/profiling_jvm.mdc

@@ -1,10 +1,10 @@
 ---
 alwaysApply: false
-description: Java SDK Profiling
+description: JVM Continuous Profiling (sentry-async-profiler)
 ---
-# Java SDK Profiling
+# JVM Continuous Profiling
 
-The Sentry Java SDK provides continuous profiling through the `sentry-async-profiler` module, which integrates async-profiler for low-overhead CPU profiling.
+The `sentry-async-profiler` module integrates async-profiler for low-overhead CPU profiling on JVM.
 
 ## Module Structure
 
@@ -25,9 +25,10 @@ The Sentry Java SDK provides continuous profiling through the `sentry-async-prof
 ### `JavaContinuousProfiler` (sentry-async-profiler)
 - Wraps native async-profiler library
 - Writes JFR files to `profilingTracesDirPath`
-- Rotates chunks periodically (`MAX_CHUNK_DURATION_MILLIS`)
+- Rotates chunks periodically (`MAX_CHUNK_DURATION_MILLIS`, default 10s)
 - Implements `RateLimiter.IRateLimitObserver` for rate limiting
 - Maintains `rootSpanCounter` for TRACE mode lifecycle
+- Platform: "java", Chunk ID always `EMPTY_ID`
 
 ### `ProfileChunk`
 - Contains profiler ID (session-level, persists across chunks), chunk ID, JFR file reference
@@ -40,12 +41,11 @@ The Sentry Java SDK provides continuous profiling through the `sentry-async-prof
 
 ## Configuration
 
-- **`profilesSampleRate`**: Sample rate (0.0 to 1.0). If set with `tracesSampleRate`, enables transaction profiling. If set alone, enables continuous profiling.
+- **`profilesSampleRate`**: Sample rate (0.0 to 1.0)
 - **`profileLifecycle`**: `ProfileLifecycle.MANUAL` (default) or `ProfileLifecycle.TRACE`
 - **`cacheDirPath`**: Directory for JFR files (required)
 - **`profilingTracesHz`**: Sampling frequency in Hz (default: 101)
 
-Example:
 ```java
 options.setProfilesSampleRate(1.0);
 options.setCacheDirPath("/tmp/sentry-cache");
@@ -85,7 +85,7 @@ options.setProfileLifecycle(ProfileLifecycle.MANUAL);
 
 ## TRACE Mode Lifecycle
 - `rootSpanCounter` incremented when sampled root span starts
-- `rootSpanCounter` decremented when root span finishes  
+- `rootSpanCounter` decremented when root span finishes
 - Profiler runs while counter > 0
 - Allows multiple concurrent transactions to share profiler session
 
@@ -106,19 +106,6 @@ options.setProfileLifecycle(ProfileLifecycle.MANUAL);
 - Sent when SDK comes online, files deleted after successful send
 - Profiler can start before SDK initialized - chunks buffered until scopes available (`initScopes()`)
 
-## Platform Differences
-
-### JVM (sentry-async-profiler)
-- Native async-profiler library
-- Platform: "java"
-- Chunk ID always `EMPTY_ID`
-
-### Android (sentry-android-core)
-- `AndroidContinuousProfiler` with `Debug.startMethodTracingSampling()`
-- Longer chunk duration (60s vs 10s for JVM)
-- Includes measurements (frames, memory)
-- Platform: "android"
-
 ## Extending
 
 Implement `IContinuousProfiler` and `JavaContinuousProfilerProvider`, register in `META-INF/services/io.sentry.profiling.JavaContinuousProfilerProvider`.