From e6bbe5499063f6a22183a7ebbf8d4a760fd5b466 Mon Sep 17 00:00:00 2001 From: Lukas Bloder Date: Tue, 7 Oct 2025 15:51:33 +0200 Subject: [PATCH 1/2] add setup instructions for java continuous profiling --- .../platforms/java/common/profiling/index.mdx | 60 ++++++++++++ docs/product/explore/profiling/index.mdx | 1 + .../automatic-instrumentation-setup/java.mdx | 95 +++++++++++++++++++ .../java.spring-boot.mdx | 34 +++++++ 4 files changed, 190 insertions(+) create mode 100644 docs/platforms/java/common/profiling/index.mdx create mode 100644 platform-includes/profiling/automatic-instrumentation-setup/java.mdx create mode 100644 platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx diff --git a/docs/platforms/java/common/profiling/index.mdx b/docs/platforms/java/common/profiling/index.mdx new file mode 100644 index 0000000000000..d65c0dde540f1 --- /dev/null +++ b/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 +--- + + + + + + +Continuous profiling is available starting in SDK version `8.23.0` for macOS and Linux. + + + +## 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.0.0') }}' +``` +```xml {tabTitle:Maven} + + io.sentry + sentry-async-profiler + {{@inject packages.version('sentry.java.sentry-async-profiler', '8.0.0') }} + +``` + +## 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. + + + +### 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. diff --git a/docs/product/explore/profiling/index.mdx b/docs/product/explore/profiling/index.mdx index 246fe78aa6ccc..b675ea1a01a42 100644 --- a/docs/product/explore/profiling/index.mdx +++ b/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/) diff --git a/platform-includes/profiling/automatic-instrumentation-setup/java.mdx b/platform-includes/profiling/automatic-instrumentation-setup/java.mdx new file mode 100644 index 0000000000000..2b07f9fefe2f0 --- /dev/null +++ b/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 tracing setup documentation 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() +``` \ No newline at end of file diff --git a/platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx b/platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx new file mode 100644 index 0000000000000..2f12e8fa628eb --- /dev/null +++ b/platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx @@ -0,0 +1,34 @@ + +### Enabling Trace Lifecycle Profiling + +To enable trace profiling, set the lifecycle to `TRACE`. Trace profiling requires tracing to be enabled. + +Check out the tracing setup documentation 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 +``` \ No newline at end of file From 3daa293cea5dd415a9c4a233d2fad62e1d9a882f Mon Sep 17 00:00:00 2001 From: Lukas Bloder Date: Fri, 10 Oct 2025 10:36:38 +0200 Subject: [PATCH 2/2] update default version in install instructions, added code sample for manual profiling in spring-boot --- .../platforms/java/common/profiling/index.mdx | 4 +-- .../java.spring-boot.mdx | 27 +++++++++++++++++++ 2 files changed, 29 insertions(+), 2 deletions(-) diff --git a/docs/platforms/java/common/profiling/index.mdx b/docs/platforms/java/common/profiling/index.mdx index d65c0dde540f1..dcb7c563137f8 100644 --- a/docs/platforms/java/common/profiling/index.mdx +++ b/docs/platforms/java/common/profiling/index.mdx @@ -21,13 +21,13 @@ Continuous profiling is available starting in SDK version `8.23.0` for macOS and 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.0.0') }}' +implementation 'io.sentry:sentry-async-profiler:{{@inject packages.version('sentry.java.sentry-async-profiler', '8.23.0') }}' ``` ```xml {tabTitle:Maven} io.sentry sentry-async-profiler - {{@inject packages.version('sentry.java.sentry-async-profiler', '8.0.0') }} + {{@inject packages.version('sentry.java.sentry-async-profiler', '8.23.0') }} ``` diff --git a/platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx b/platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx index 2f12e8fa628eb..718f38c1eba2a 100644 --- a/platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx +++ b/platform-includes/profiling/automatic-instrumentation-setup/java.spring-boot.mdx @@ -31,4 +31,31 @@ sentry.profile-lifecycle=MANUAL 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() ``` \ No newline at end of file