Java Continuous Profiling (#15154)

<!-- Use this checklist to make sure your PR is ready for merge. You may
delete any sections you don't need. -->

## DESCRIBE YOUR PR
Adds docs for Continuous Profiling on JVM
(getsentry/sentry-java#2635)


## IS YOUR CHANGE URGENT?  

Help us prioritize incoming PRs by letting us know when the change needs
to go live.
- [ ] Urgent deadline (GA date, etc.): <!-- ENTER DATE HERE -->
- [ ] Other deadline: <!-- ENTER DATE HERE -->
- [ ] None: Not urgent, can wait up to 1 week+

## SLA

- Teamwork makes the dream work, so please add a reviewer to your PRs.
- Please give the docs team up to 1 week to review your PR unless you've
added an urgent due date to it.
Thanks in advance for your help!

## PRE-MERGE CHECKLIST

*Make sure you've checked the following before merging your changes:*

- [ ] Checked Vercel preview for correctness, including links
- [ ] PR was reviewed and approved by any necessary SMEs (subject matter
experts)
- [ ] PR was reviewed and approved by a member of the [Sentry docs
team](https://github.com/orgs/getsentry/teams/docs)

## LEGAL BOILERPLATE

<!-- Sentry employees and contractors can delete or ignore this section.
-->

Look, I get it. The entity doing business as "Sentry" was incorporated
in the State of Delaware in 2015 as Functional Software, Inc. and is
gonna need some rights from me in order to utilize my contributions in
this here PR. So here's the deal: I retain all rights, title and
interest in and to my contributions, and by keeping this boilerplate
intact I confirm that Sentry can use, modify, copy, and redistribute my
contributions, under Sentry's choice of terms.

## EXTRA RESOURCES

- [Sentry Docs contributor guide](https://docs.sentry.io/contributing/)

Author: lbloder

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