Java Continuous Profiling

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

@@ -0,0 +1,60 @@
+---
+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>
+
+## 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.sentry-async-profiler', '8.23.0') }}'
+```
+```xml {tabTitle:Maven}
+<dependency>
+    <groupId>io.sentry</groupId>
+    <artifactId>sentry-async-profiler</artifactId>
+    <version>{{@inject packages.version('sentry.java.sentry-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) version 3.0 under the hood to collect profiling data. It currently supports Java up to JDK 22.

docs/product/explore/profiling/index.mdx

@@ -30,6 +30,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/profiling/automatic-instrumentation-setup/java.mdx

@@ -0,0 +1,95 @@
+
+### Enabling Trace Lifecycle Profiling
+
+To enable trace profiling, set the lifecycle to `trace`. Trace profiling requires tracing to be enabled.
+
+Check out the <PlatformLink to="/tracing/">tracing setup documentation</PlatformLink> for more detailed information on how to configure sampling. Setting the sample rate to 1.0 means all transactions will be captured.
+
+
+```java
+import io.sentry.Sentry;
+import io.sentry.ProfileLifecycle;
+
+Sentry.init(options -> {
+  options.setDsn("___PUBLIC_DSN___");
+  // Set traces_sample_rate to 1.0 to capture 100%
+  // of transactions for tracing.
+  options.setTracesSampleRate(1.0);
+  // To collect profiles for all profile sessions,
+  // set `profile_session_sample_rate` to 1.0.
+  options.setProfileSessionSampleRate(1.0);
+  // Profiles will be automatically collected while
+  // there is an active span.
+  options.setProfileLifecycle(ProfileLifecycle.TRACE);
+});
+```
+
+```kotlin
+import io.sentry.Sentry
+import io.sentry.ProfileLifecycle
+
+Sentry.init { options ->
+  options.dsn = "___PUBLIC_DSN___"
+  // Set traces_sample_rate to 1.0 to capture 100%
+  // of transactions for tracing.
+  options.tracesSampleRate = 1.0
+  // To collect profiles for all profile sessions,
+  // set `profile_session_sample_rate` to 1.0.
+  options.profileSessionSampleRate = 1.0
+  // Profiles will be automatically collected while
+  // there is an active span.
+  options.profileLifecycle = ProfileLifecycle.TRACE
+}
+```
+
+### Enabling Manual Lifecycle Profiling
+
+To enable manual profiling, set the lifecycle to `manual`. Manual profiling does not require tracing to be enabled.
+
+```java
+import io.sentry.Sentry;
+import io.sentry.ProfileLifecycle;
+
+Sentry.init(options -> {
+  options.setDsn("___PUBLIC_DSN___");
+  // To collect profiles for all profile sessions,
+  // set `profile_session_sample_rate` to 1.0.
+  options.setProfileSessionSampleRate(1.0)
+  // Profiles will be collected when
+  // `Sentry.startProfiler()` is called and
+  // stopped when `Sentry.stopProfiler()` is called.
+  options.setProfileLifecycle(ProfileLifecycle.MANUAL);
+});
+
+// Start profiling
+Sentry.startProfiler();
+
+// run some code here
+
+// Stop profiling
+Sentry.stopProfiler();
+```
+
+```kotlin
+import io.sentry.Sentry
+import io.sentry.ProfileLifecycle
+
+Sentry.init { options ->
+  options.dsn = "___PUBLIC_DSN___"
+  // To collect profiles for all profile sessions,
+  // set `profile_session_sample_rate` to 1.0.
+  options.profileSessionSampleRate = 1.0
+  // Profiles will be collected when
+  // `Sentry.startProfiler()` is called and
+  // stopped when `Sentry.stopProfiler()` is called.
+  options.profileLifecycle = ProfileLifecycle.MANUAL
+}
+
+// Start profiling
+Sentry.startProfiler()
+
+// run some code here
+
+// Stop profiling
+Sentry.stopProfiler()
+```

platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx

@@ -0,0 +1,61 @@
+
+### Enabling Trace Lifecycle Profiling
+
+To enable trace profiling, set the lifecycle to `TRACE`. Trace profiling requires tracing to be enabled.
+
+Check out the <PlatformLink to="/tracing/">tracing setup documentation</PlatformLink> for more detailed information on how to configure sampling. Setting the sample rate to 1.0 means all transactions will be captured.
+
+```properties {filename:application.properties}
+sentry.traces-sample-rate=1.0
+sentry.profile-session-sample-rate=1.0
+sentry.profile-lifecycle=TRACE
+```
+
+```yaml {filename:application.yml}
+sentry:
+  traces-sample-rate: 1.0
+  profile-session-sample-rate: 1.0
+  profile-lifecycle: TRACE
+```
+
+### Enabling Manual Lifecycle Profiling
+
+To enable manual profiling, set the lifecycle to `MANUAL`. Manual profiling does not require tracing to be enabled.
+
+```properties {filename:application.properties}
+sentry.profile-session-sample-rate=1.0
+sentry.profile-lifecycle=MANUAL
+```
+
+```yaml {filename:application.yml}
+sentry:
+  profile-session-sample-rate: 1.0
+  profile-lifecycle: MANUAL
+```
+
+Then use the `startProfiler` and `stopProfiler` methods to start and stop profiling respectively.
+
+
+```java
+import io.sentry.Sentry;
+
+// Start profiling
+Sentry.startProfiler();
+
+// run some code here
+
+// Stop profiling
+Sentry.stopProfiler();
+```
+
+```kotlin
+import io.sentry.Sentry
+
+// Start profiling
+Sentry.startProfiler()
+
+// run some code here
+
+// Stop profiling
+Sentry.stopProfiler()
+```