Java Continuous Profiling

docs/platforms/java/common/configuration/options.mdx

@@ -284,3 +284,20 @@ Controls whether the SDK should propagate the W3C `traceparent` HTTP header alon
 Set this boolean to `false` to disable tracing for `OPTIONS` requests. This options default value will likely be changed in the next major version, meaning you will have to set it to `true` if you want to keep tracing `OPTIONS` requests.
 
 </SdkOption>
+
+## Profiling Options
+
+<SdkOption name="profileSessionSampleRate" type="float" availableSince="8.23.0">
+
+A number between `0` and `1`, controlling the percentage chance that the session will be profiled. (`0` represents 0%, `1` represents 100%.) The default is null (disabled).
+
+</SdkOption>
+
+<SdkOption name="profileLifecycle" type="enum" defaultValue="manual" availableSince="8.23.0">
+
+Whether the continuous profiling lifecycle is controlled manually or based on the trace lifecycle. Possible values are:
+
+- `manual`: **default** Profiler must be started and stopped through `Sentry.startProfiler()` and `Sentry.stopProfiler()` APIs
+- `trace`: Profiler is started and stopped automatically whenever a sampled trace starts or finishes
+
+</SdkOption>

docs/platforms/java/common/profiling/index.mdx

@@ -0,0 +1,65 @@
+---
+title: Set Up Java Profiling
+sidebar_title: Profiling
+description: "Learn how to enable profiling in your app if it is not already set up."
+sidebar_order: 5000
+supported:
+  - java
+---
+
+<PlatformContent includePath="profiling/index/preface" />
+<PlatformContent includePath="profiling/index/why-profiling" />
+
+<Alert>
+
+Continuous profiling is available starting in SDK version `8.23.0` for macOS and Linux.
+
+</Alert>
+
+<Alert level="warning">
+Versions < `8.26.0` use [async-profiler](https://github.com/async-profiler/async-profiler) in version 3 and thus only support Java up to JDK 22. Starting with `8.26.0` we upgraded to [async-profiler](https://github.com/async-profiler/async-profiler) 4.2 enabling support for all Java versions up to JDK 25.
+</Alert>
+
+## Install
+
+In addition to your typical Sentry dependencies, you will need to add `sentry-async-profiler` as a dependency:
+
+```groovy {tabTitle:Gradle}
+implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}'
+```
+```xml {tabTitle:Maven}
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-async-profiler</artifactId>
+    <version>{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}</version>
+</dependency>
+```
+
+## Enabling Continuous Profiling
+
+Continuous profiling supports two modes - `manual` and `trace`. The two modes are mutually exclusive, and cannot be used at the same time.
+
+In `manual` mode, the profiling data collection can be managed via calls to `Sentry.startProfiler()` and `Sentry.stopProfiler()`. You are entirely in control of when the profiler runs.
+
+In `trace` mode, the profiler manages its own start and stop calls, which are based on spans: the profiler continues to run while there is at least one active span, and stops when there are no active spans.
+
+<PlatformContent includePath="profiling/automatic-instrumentation-setup" />
+
+### Managing Profile Sampling Rates
+
+Sentry SDK supports an additional `profileSessionSampleRate` that must be set to a non-zero value to enable continuous profiling. This can be used to control session sampling rates at the service level as the sampling decision is evaluated only once at SDK initialization.
+
+This is useful for cases where you deploy your service many times, but would only like a subset of those deployments to be profiled. In a single service environment we recommend to set this to 1.0.
+
+### Manage Storage Location for Profiles
+The files generated by the underlying profiler are temporarily stored. By default we use the directory `System.getProperty("java.io.tmpdir")/profiling_traces`. This path can be configured by setting the `profilingTracesDirPath` option.
+
+## Platform Support
+
+Continuous profiling for Java is currently supported on:
+
+- macOS
+- Linux
+
+The profiler uses [async-profiler](https://github.com/async-profiler/async-profiler) under the hood to collect profiling data. 
+

docs/product/explore/profiling/index.mdx

@@ -34,6 +34,7 @@ Profiling helps you quickly identify performance bottlenecks, enabling you to bu
 - [React Native [beta]](/platforms/react-native/profiling/)
 - [Flutter [experimental, iOS and macOS only]](/platforms/dart/guides/flutter/profiling/)
 - [.NET [experimental]](/platforms/dotnet/profiling/)
+- [JVM (Java and other JVM based languages)](/platforms/java/profiling/)
 
 </Alert>
 

platform-includes/getting-started-config/java.mdx

@@ -1,12 +1,3 @@
-<OnboardingOptionButtons
-  options={[
-    'error-monitoring',
-    'performance',
-    'profiling',
-    'logs',
-  ]}
-/>
-
 <OnboardingOption optionId="opentelemetry" hideForThisOption>
 Configuration should happen as early as possible in your application's lifecycle.
 
@@ -26,6 +17,12 @@ Sentry.init(options -> {
   // We recommend adjusting this value in production.
   options.setTracesSampleRate(1.0);
   // ___PRODUCT_OPTION_END___ performance
+  // ___PRODUCT_OPTION_START___ profiling
+
+  // Enable profiling
+  options.setProfileSessionSampleRate(1.0);
+  options.setProfileLifecycle(ProfileLifecycle.TRACE);
+  // ___PRODUCT_OPTION_END___ profiling
   // ___PRODUCT_OPTION_START___ logs
 
   // Enable logs to be sent to Sentry
@@ -50,6 +47,12 @@ Sentry.init { options ->
   // We recommend adjusting this value in production.
   options.tracesSampleRate = 1.0
   // ___PRODUCT_OPTION_END___ performance
+  // ___PRODUCT_OPTION_START___ profiling
+
+  // Enable profiling
+  options.profileSessionSampleRate = 1.0
+  options.profileLifecycle = ProfileLifecycle.TRACE
+  // ___PRODUCT_OPTION_END___ profiling
   // ___PRODUCT_OPTION_START___ logs
 
   // Enable logs to be sent to Sentry

platform-includes/getting-started-config/java.spring-boot.mdx

@@ -16,6 +16,12 @@ sentry.send-default-pii=true
 # We recommend adjusting this value in production.
 sentry.traces-sample-rate=1.0
 # ___PRODUCT_OPTION_END___ performance
+// ___PRODUCT_OPTION_START___ profiling
+
+# Enable profiling
+sentry.profile-session-sample-rate=1.0
+sentry.profile-lifecycle=TRACE
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```yaml {filename:application.yml}
@@ -32,6 +38,12 @@ sentry:
   # We recommend adjusting this value in production.
   tracesSampleRate: 1.0
   # ___PRODUCT_OPTION_END___ performance
+  // ___PRODUCT_OPTION_START___ profiling
+
+  # Enable profiling
+  profileSessionSampleRate: 1.0
+  profileLifecycle: TRACE
+  // ___PRODUCT_OPTION_END___ profiling
 ```
 
 By default, only unhandled exceptions are sent to Sentry. This behavior can be tuned through configuring the `sentry.exception-resolver-order` property. For example, setting it to `-2147483647` (the value of `org.springframework.core.Ordered#HIGHEST_PRECEDENCE`) ensures exceptions that have been handled by exception resolvers with higher order are sent to Sentry - including ones handled by `@ExceptionHandler` annotated methods.

platform-includes/getting-started-config/java.spring.mdx

@@ -196,5 +196,10 @@ The SDK can be configured using a `sentry.properties` file:
 
 ```properties {filename:sentry.properties}
 traces-sample-rate=1.0
+// ___PRODUCT_OPTION_START___ profiling
+# Enable profiling
+profile-session-sample-rate=1.0
+profile-lifecycle=TRACE
+// ___PRODUCT_OPTION_END___ profiling
 ```
 </OnboardingOption>

platform-includes/getting-started-config/opentelemetry/java.mdx

@@ -10,5 +10,11 @@ send-default-pii=true
 # ___PRODUCT_OPTION_START___ performance
 traces-sample-rate=1.0
 # ___PRODUCT_OPTION_END___ performance
+// ___PRODUCT_OPTION_START___ profiling
+
+# Enable profiling
+profile-session-sample-rate=1.0
+profile-lifecycle=TRACE
+// ___PRODUCT_OPTION_END___ profiling
 ```
 </OnboardingOption>

platform-includes/getting-started-install/java.jul.mdx

@@ -1,5 +1,5 @@
 <OnboardingOptionButtons
-  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}]}
+  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}, "profiling"]}
 />
 
 ```xml {tabTitle:Maven}
@@ -8,14 +8,27 @@
     <artifactId>sentry-jul</artifactId>
     <version>{{@inject packages.version('sentry.java.jul', '4.1.0') }}</version>
 </dependency>
+// ___PRODUCT_OPTION_START___ profiling
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-async-profiler</artifactId>
+    <version>{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}</version>
+</dependency>
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```groovy {tabTitle:Gradle}
 implementation 'io.sentry:sentry-jul:{{@inject packages.version('sentry.java.jul', '4.1.0') }}'
+// ___PRODUCT_OPTION_START___ profiling
+implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}'
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```scala {tabTitle: SBT}
 libraryDependencies += "io.sentry" % "sentry-jul" % "{{@inject packages.version('sentry.java.jul', '4.1.0') }}"
+// ___PRODUCT_OPTION_START___ profiling
+libraryDependencies += "io.sentry" % "sentry-async-profiler" % "{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}"
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 For other dependency managers, see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-jul).

platform-includes/getting-started-install/java.log4j2.mdx

@@ -1,5 +1,5 @@
 <OnboardingOptionButtons
-  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}]}
+  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}, "profiling"]}
 />
 
 ```xml {tabTitle:Maven Plugin}{filename:pom.xml}
@@ -35,6 +35,15 @@
     </execution>
   </executions>
 </plugin>
+// ___PRODUCT_OPTION_START___ profiling
+<dependencies>
+  <dependency>
+      <groupId>io.sentry</groupId>
+      <artifactId>sentry-async-profiler</artifactId>
+      <version>{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}</version>
+  </dependency>
+</dependencies>
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```xml {tabTitle:Maven}
@@ -43,20 +52,38 @@
     <artifactId>sentry-log4j2</artifactId>
     <version>{{@inject packages.version('sentry.java.log4j2', '4.2.0') }}</version>
 </dependency>
+// ___PRODUCT_OPTION_START___ profiling
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-async-profiler</artifactId>
+    <version>{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}</version>
+</dependency>
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```groovy {tabTitle:Gradle Plugin}
 plugins {
   id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.12.0') }}"
 }
+// ___PRODUCT_OPTION_START___ profiling
+dependencies {
+  implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}'
+}
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```groovy {tabTitle:Gradle}
 implementation 'io.sentry:sentry-log4j2:{{@inject packages.version('sentry.java.log4j2', '4.2.0') }}'
+// ___PRODUCT_OPTION_START___ profiling
+implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}'
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```scala {tabTitle: SBT}
 libraryDependencies += "io.sentry" % "sentry-log4j2" % "{{@inject packages.version('sentry.java.log4j2', '4.2.0') }}"
+// ___PRODUCT_OPTION_START___ profiling
+libraryDependencies += "io.sentry" % "sentry-async-profiler" % "{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}"
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 For other dependency managers see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-log4j2).

platform-includes/getting-started-install/java.logback.mdx

@@ -1,5 +1,5 @@
 <OnboardingOptionButtons
-  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}]}
+  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}, "profiling"]}
 />
 
 ```xml {tabTitle:Maven Plugin}{filename:pom.xml}
@@ -35,6 +35,15 @@
     </execution>
   </executions>
 </plugin>
+// ___PRODUCT_OPTION_START___ profiling
+<dependencies>
+  <dependency>
+      <groupId>io.sentry</groupId>
+      <artifactId>sentry-async-profiler</artifactId>
+      <version>{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}</version>
+  </dependency>
+</dependencies>
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```xml {tabTitle:Maven}
@@ -43,20 +52,38 @@
     <artifactId>sentry-logback</artifactId>
     <version>{{@inject packages.version('sentry.java.logback', '4.2.0') }}</version>
 </dependency>
+// ___PRODUCT_OPTION_START___ profiling
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-async-profiler</artifactId>
+    <version>{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}</version>
+</dependency>
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```groovy {tabTitle:Gradle Plugin}
 plugins {
   id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.12.0') }}"
 }
+// ___PRODUCT_OPTION_START___ profiling
+dependencies {
+  implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}'
+}
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```groovy {tabTitle:Gradle}
 implementation 'io.sentry:sentry-logback:{{@inject packages.version('sentry.java.logback', '4.2.0') }}'
+// ___PRODUCT_OPTION_START___ profiling
+implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}'
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```scala {tabTitle: SBT}
 libraryDependencies += "io.sentry" % "sentry-logback" % "{{@inject packages.version('sentry.java.logback', '4.2.0') }}"
+// ___PRODUCT_OPTION_START___ profiling
+libraryDependencies += "io.sentry" % "sentry-async-profiler" % "{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}"
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 For other dependency managers, see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-logback).

platform-includes/getting-started-install/java.mdx

@@ -1,11 +1,16 @@
 <OnboardingOptionButtons
-  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}]}
+  options={["error-monitoring", "performance", {id: "opentelemetry", checked: true}, "profiling", "logs"]}
 />
 
 ```groovy {filename:build.gradle}
 plugins {
   id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.12.0') }}"
 }
+// ___PRODUCT_OPTION_START___ profiling
+dependencies {
+  implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}'
+}
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```xml {tabTitle:Maven Plugin}{filename:pom.xml}
@@ -41,10 +46,22 @@ plugins {
     </execution>
   </executions>
 </plugin>
+// ___PRODUCT_OPTION_START___ profiling
+<dependencies>
+  <dependency>
+      <groupId>io.sentry</groupId>
+      <artifactId>sentry-async-profiler</artifactId>
+      <version>{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}</version>
+  </dependency>
+</dependencies>
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 ```scala {tabTitle:SBT}
 libraryDependencies += "io.sentry" % "sentry" % "{{@inject packages.version('sentry.java', '4.2.0') }}"
+// ___PRODUCT_OPTION_START___ profiling
+libraryDependencies += "io.sentry" % "sentry-async-profiler" % "{{@inject packages.version('sentry.java.async-profiler', '8.23.0') }}"
+// ___PRODUCT_OPTION_END___ profiling
 ```
 
 <Alert>