diff --git a/src/docs/product/cli/dif.mdx b/src/docs/product/cli/dif.mdx index 7b4f26ada8ac7..7f40498c68171 100644 --- a/src/docs/product/cli/dif.mdx +++ b/src/docs/product/cli/dif.mdx @@ -50,7 +50,7 @@ to look for them: sentry-cli difutil find ``` -Additionally, `sentry-cli upload-dif` can automatically search for files in a +Additionally, `sentry-cli debug-files upload` can automatically search for files in a folder or ZIP archive. ## Creating Source Bundles @@ -62,7 +62,7 @@ containing all source files referenced by a specific debug information file. This is particularly useful when building and uploading debug information files are detached. In this case, a source bundle can be created when building and can -be uploaded at any later point in time with `sentry-cli upload-dif`. +be uploaded at any later point in time with `sentry-cli debug-files upload`. To create a source bundle, use the `difutil bundle-sources` command on a list of debug information files: @@ -72,23 +72,23 @@ debug information files: sentry-cli difutil bundle-sources /path/to/files... # at any later time: -sentry-cli upload-dif --type sourcebundle /path/to/bundles... +sentry-cli debug-files upload --type sourcebundle /path/to/bundles... ``` To create multiple source bundles for all debug information files, use the command on each file individually. -Alternatively, add the `--include-sources` option to the `upload-dif` command, +Alternatively, add the `--include-sources` option to the `debug-files upload` command, which generates source bundles on the fly during the upload. This requires that the upload is performed on the same machine as the application build: ```bash -sentry-cli upload-dif --include-sources /path/to/files... +sentry-cli debug-files upload --include-sources /path/to/files... ``` ## Uploading Files -Use the `sentry-cli upload-dif` command to upload debug information files to +Use the `sentry-cli debug-files upload` command to upload debug information files to Sentry. The command will recursively scan the provided folders or ZIP archives. Files that have already been upload are skipped automatically. @@ -108,7 +108,7 @@ to [Working with Projects](/product/cli/configuration/#sentry-cli-working-with-p A basic debug file upload can be started with: ```bash -sentry-cli upload-dif -o -p /path/to/files... +sentry-cli debug-files upload -o -p /path/to/files... > Found 2 debug information files > Prepared debug information files for upload @@ -126,7 +126,7 @@ specify `--wait` in the CLI, which will block until server-side analysis is complete: ```bash -sentry-cli upload-dif -o -p --wait /path/to/files... +sentry-cli debug-files upload -o -p --wait /path/to/files... > Found 2 debug information files > Prepared debug information files for upload @@ -143,7 +143,7 @@ There are a few options you can supply to the upload command: `--wait` -: Wait for server-side processing of uploaded files. By default, `upload-dif` +: Wait for server-side processing of uploaded files. By default, `debug-files upload` completes once the debug files have been uploaded to Sentry. After this, Sentry analyzes the files and makes them available for symbolication. It makes sense to specify `--wait` to ensure that debug files are ready before sending @@ -223,7 +223,7 @@ many useful symbols. In that case, the sentry-cli upload will warn you that it needs BCSymbolMaps: ```bash -sentry-cli upload-dif ... +sentry-cli debug-files upload ... > Found 34 debug information files > Warning: Found 10 symbol files with hidden symbols (need BCSymbolMaps) ``` @@ -233,7 +233,7 @@ are generated by the Xcode build process. Supply the `--symbol-maps` parameter and point it to the folder containing the symbol maps: ```bash -sentry-cli upload-dif --symbol-maps path/to/symbolmaps path/to/debug/symbols +sentry-cli debug-files upload --symbol-maps path/to/symbolmaps path/to/debug/symbols ``` ### Breakpad Files @@ -311,3 +311,52 @@ UUIDs into a properties file. `--require-one` : Requires at least one file to upload or the command will error. + +## JVM Source Bundles + +If you're using a build tool we don't support, or you prefer not to use Sentry's build tool plugins, you'll need to upload source bundle files manually. + +See the build tool plugins we currently support here: + +- [Android](/platforms/android/source-context/) +- [Java](/platforms/java/source-context/) + +You can also upload ProGuard files manually with `sentry-cli` for any JVM-based language like +Java or Kotlin. + + + +Before you can upload source files, you must configure the Sentry CLI with the organization and project you are uploading bundle files for. See the CLI docs on +[Working with Projects](/product/cli/configuration/#sentry-cli-working-with-projects) to learn how to do this. + + + +### Creating a Source Bundle + +Run the `debug-files bundle-jvm` command to create a source bundle for a +source directory. + +```bash +sentry-cli debug-files bundle-jvm \ + --output some/dir \ + --debug-id A_VALID_UUID \ + path/to/source/dir +``` + +You must provide the UUID of the source bundle for the Java/Android SDK to send. +More details can be found in the [Source Context](/platforms/java/source-context/#manually-uploading-source-context) docs for Java and the [Source Context](/platforms/android/source-context/#manually-uploading-source-context) docs for Android. + +### Uploading a Source Bundle + +The `debug-files upload` command allows you to upload the source +bundle you created to Sentry. + +```bash +sentry-cli debug-files upload \ + --type jvm \ + output/path/of/bundle-jvm/command +``` + +After the upload, Sentry will attach Source Context to future events. + +To make sure these steps worked, check **Project Settings > Debug Files** in Sentry.io to see if the uploaded source bundle files are listed. diff --git a/src/platform-includes/source-context/java-source-context.png b/src/platform-includes/source-context/java-source-context.png new file mode 100644 index 0000000000000..a570443b42afe Binary files /dev/null and b/src/platform-includes/source-context/java-source-context.png differ diff --git a/src/platform-includes/source-context/java.mdx b/src/platform-includes/source-context/java.mdx new file mode 100644 index 0000000000000..b4dac09a5f40c --- /dev/null +++ b/src/platform-includes/source-context/java.mdx @@ -0,0 +1,306 @@ +You'll need to enable the Source Context feature to see your source code as part of stack traces in Sentry. You can either do this: + +- By adding one of a build tool plugin to your project +- Or, by manually uploading your source bundle using the Sentry CLI + +This document covers both methods. You can find more information about uploading via the CLI in our [Debug Information Files](/product/cli/dif/#jvm-source-bundles) docs. + + + +Source Context also works with ProGuard. See the [ProGuard & DexGuard](/platforms/android/proguard/) docs for more information. + + + +### UUIDs + +A random UUID must be generated and placed into the `sentry-debug-meta.properties`. The same UUID must be used to upload the source bundle file. Whenever an error is sent to Sentry, this UUID is sent alongside the error, allowing +the Sentry server to look up source code in the source bundle with a matching ID. + +If you're using a build tool plugin, these steps happen automatically. + +![Java Source Context](java-source-context.png) + +All of the following methods require `org`, `project` and an `authToken`. + +You can create an auth token by visiting the +[User Auth Tokens](https://sentry.io/settings/account/api/auth-tokens/) settings page in Sentry.io. +The auth token requires either a `project:releases` or `project:write` Scope. + +## Known Limitations + +- Files with same name but different extensions will lead to undefined behavior + - e.g. MainActivity.java and MainActivity.kt will both be renamed to MainActivity.jvm +- Package declaration and file tree must match for source lookup to work + - e.g. a class io.sentry.sample.MainActivity.java has to be stored in io/sentry/sample + + + +- Kotlin files are allowed to contain multiple classes but code obfuscation tools like ProGuard or R8 may prevent this from working correctly +- We don't add generated sources for AGP < 7.4 + + + +## Using the Gradle Build Tool Plugin + +Add the Sentry Gradle plugin to your project by adding the following lines: + + + +```groovy +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id "io.sentry.android.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Enables more detailed log output, e.g. for sentry-cli. + // + // Default is false. + debug = true + + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + // + // Default is disabled. + includeSourceContext = true + + // Includes additional source directories into the source bundle. + // These directories are resolved relative to the project directory. + additionalSourceDirsForSourceContext = ["mysrc/java", "other-source-dir/main/kotlin"] + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" +} +``` + +```kotlin +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id("io.sentry.android.gradle") version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Enables more detailed log output, e.g. for sentry-cli. + // + // Default is false. + debug.set(true) + + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + // + // Default is disabled. + includeSourceContext.set(true) + + // Includes additional source directories into the source bundle. + // These directories are resolved relative to the project directory. + additionalSourceDirsForSourceContext.set(setOf("mysrc/java", "other-source-dir/main/kotlin")) + + org.set("___ORG_SLUG___") + projectName.set("___PROJECT_SLUG___") + authToken.set("your-sentry-auth-token") +} +``` + + + + + +Make sure the `assemble` task is executed. + +```groovy +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Enables more detailed log output, e.g. for sentry-cli. + // + // Default is false. + debug = true + + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + // + // Default is disabled. + includeSourceContext = true + + // Includes additional source directories into the source bundle. + // These directories are resolved relative to the project directory. + additionalSourceDirsForSourceContext = ["mysrc/java", "other-source-dir/main/kotlin"] + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" +} +``` + +```kotlin +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id("io.sentry.jvm.gradle") version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Enables more detailed log output, e.g. for sentry-cli. + // + // Default is false. + debug.set(true) + + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + // + // Default is disabled. + includeSourceContext.set(true) + + // Includes additional source directories into the source bundle. + // These directories are resolved relative to the project directory. + additionalSourceDirsForSourceContext.set(setOf("mysrc/java", "other-source-dir/main/kotlin")) + + org.set("___ORG_SLUG___") + projectName.set("___PROJECT_SLUG___") + authToken.set("your-sentry-auth-token") +} +``` + + + + + +## Using the Maven Build Tool Plugin + +Add the [Sentry Maven Plugin](https://github.com/getsentry/sentry-maven-plugin) to your project by adding the following lines to your `pom.xml` file: + +```xml + + + + io.sentry + sentry-maven-plugin + {{@inject packages.version('sentry.java.mavenplugin', '0.0.2') }} + + + true + + + + + /path/to/sentry-cli + + ___ORG_SLUG___ + + ___PROJECT_SLUG___ + + + + + + + ${env.SENTRY_AUTH_TOKEN} + + + + install + + uploadSourceBundle + + + + + + ... + +``` + +You must manually download `sentry-cli` for your required architecture and point +the Maven Plugin to it using `sentryCliExecutablePath`. +You can get the latest release from the following URL: + +``` +https://github.com/getsentry/sentry-cli/releases/tag/{{@inject apps.version('sentry-cli', '2.17.3') }} +``` + + + +## Manually Uploading Source Context + +If you're using a build tool we don't support, or you prefer not to use Sentry's build tool plugins, you'll need to create and upload source bundle files manually using the Sentry CLI. + +The `sentry-cli` commands allow you to supply `--org` and `--project` as well as provide the auth token by setting the `SENTRY_AUTH_TOKEN` environment variable. + +You can also use a `.sentryclirc` or a `.properties` file, which you can link using the `SENTRY_PROPERTIES` environment variable. + +### Creating the Source Bundle + +First, create the source bundle containing your source files: + +``` +sentry-cli debug-files bundle-jvm --output path/to/store/bundle --debug-id A_VALID_UUID path/to/source-code +``` + +### Uploading the Source Bundle + +Next, upload that source bundle to Sentry: + +``` +sentry-cli debug-files upload --type jvm path/to/bundle +``` + +### Configuring the SDK + +You'll need to tell the SDK which source bundle it should use for providing Source Context via one of the following options: + +#### `sentry-debug-meta.properties` + +Add a `sentry-debug-meta.properties` file to your application resources at build time which will be picked up automatically by the SDK. + +```properties +io.sentry.bundle-ids=A_VALID_UUID +``` + +#### `sentry.properties` + +```properties +bundle-ids=A_VALID_UUID +``` + + + +#### `application.properties` + +```properties +sentry.bundle-ids=A_VALID_UUID` +``` + + + +#### `SentryOptions` + +```Java +options.addBundleId("A_VALID_UUID"); +``` diff --git a/src/platforms/android/common/gradle.mdx b/src/platforms/android/common/gradle.mdx index 3954310254949..fd27ebb1a4e29 100644 --- a/src/platforms/android/common/gradle.mdx +++ b/src/platforms/android/common/gradle.mdx @@ -8,6 +8,7 @@ The [Sentry Android Gradle Plugin](https://github.com/getsentry/sentry-android-g seamless integration with the Gradle build system. It supports the following features: - ProGuard/R8 mappings upload +- Java/Kotlin Source Context upload - Native debug symbols and sources upload - Auto-instrumentation tracing through bytecode manipulation - Logcat breadcrumb logging @@ -91,6 +92,11 @@ sentry { // Default is disabled. includeNativeSources = false + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext = false + // Enable or disable the tracing instrumentation. // Does auto instrumentation for specified features through bytecode manipulation. // Default is enabled. @@ -174,6 +180,11 @@ sentry { // Default is disabled. includeNativeSources.set(false) + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext.set(false) + // Enable or disable the tracing instrumentation. // Does auto instrumentation for specified features through bytecode manipulation. // Default is enabled. @@ -288,6 +299,24 @@ You can find your authentication token [on the Sentry API page](https://sentry.i +## Java/Kotlin Source Context + +This plugin can automatically upload your source code to Sentry so it is shown as part of the stack traces. + +```groovy +sentry { + includeSourceContext = true +} +``` + +```kotlin +sentry { + includeSourceContext.set(true) +} +``` + +Checkout the full documentation on Source Context for more details. + ## Tracing Auto-instrumentation The plugin uses the [bytecode manipulation](https://www.infoq.com/articles/Living-Matrix-Bytecode-Manipulation/) framework to inject a code snippet diff --git a/src/platforms/android/source-context.mdx b/src/platforms/android/source-context.mdx new file mode 100644 index 0000000000000..3e0a8262f18a5 --- /dev/null +++ b/src/platforms/android/source-context.mdx @@ -0,0 +1,7 @@ +--- +title: Source Context +sidebar_order: 110 +description: "Learn about showing your source code as part of stack traces." +--- + + diff --git a/src/platforms/java/common/gradle.mdx b/src/platforms/java/common/gradle.mdx index ed9cb44a1d477..11253a23a5e71 100644 --- a/src/platforms/java/common/gradle.mdx +++ b/src/platforms/java/common/gradle.mdx @@ -21,7 +21,7 @@ buildscript { } plugins { - id "io.sentry.android.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.0.0') }}" + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" } ``` @@ -33,13 +33,13 @@ buildscript { } plugins { - id("io.sentry.android.gradle") version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.0.0') }}" + id("io.sentry.jvm.gradle") version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" } ``` -Although the plugin id contains `android`, it can be used for non-android projects. However, for non-android projects, the plugin only collects external dependencies. +For non-Android projects, the plugin only collects external dependencies and uploads Source Context. @@ -49,6 +49,22 @@ We expose the following configuration values directly in `build.gradle`: ```groovy sentry { + // Enables more detailed log output, e.g. for sentry-cli. + // + // Default is false. + debug = true + + // Generates a source bundle and uploads it to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + // + // Default is disabled. + includeSourceContext = true + + // Includes additional source directories into the source bundle. + // These directories are resolved relative to the project directory. + additionalSourceDirsForSourceContext = ["mysrc/java", "other-source-dir/main/kotlin"] + // Disables or enables dependencies metadata reporting for Sentry. // If enabled, the plugin will collect external dependencies and // upload them to Sentry as part of events. If disabled, all the logic @@ -61,6 +77,22 @@ sentry { ```kotlin sentry { + // Enables more detailed log output, e.g. for sentry-cli. + // + // Default is false. + debug.set(true) + + // Generates a source bundle and uploads it to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + // + // Default is disabled. + includeSourceContext.set(true) + + // Includes additional source directories into the source bundle. + // These directories are resolved relative to the project directory. + additionalSourceDirsForSourceContext.set(setOf("mysrc/java", "other-source-dir/main/kotlin")) + // Disables or enables dependencies metadata reporting for Sentry. // If enabled, the plugin will collect external dependencies and // upload them to Sentry as part of events. If disabled, all the logic @@ -71,6 +103,10 @@ sentry { } ``` +## Source Context + +See our documentation on Source Context. + ## Dependencies Report The plugin automatically collects an application's external dependencies (including transitive ones), and generates a compile-time report. The Sentry Java SDK picks up the report at runtime and sends it along with every Sentry event. The event dependencies metadata will look something like this: diff --git a/src/platforms/java/common/source-context.mdx b/src/platforms/java/common/source-context.mdx new file mode 100644 index 0000000000000..3e0a8262f18a5 --- /dev/null +++ b/src/platforms/java/common/source-context.mdx @@ -0,0 +1,7 @@ +--- +title: Source Context +sidebar_order: 110 +description: "Learn about showing your source code as part of stack traces." +--- + + diff --git a/src/wizard/android/index.md b/src/wizard/android/index.md index bdd893d075e9c..2ab0a9db0041a 100644 --- a/src/wizard/android/index.md +++ b/src/wizard/android/index.md @@ -9,9 +9,10 @@ type: framework Sentry captures data by using an SDK within your application’s runtime. These are platform-specific and allow Sentry to have a deep understanding of how your app works. -### Auto-Installation With the Sentry Android Gradle Plugin +### Auto-Installation and Source Context With the Sentry Android Gradle Plugin The Sentry Android Gradle plugin will install the Android SDK and integrations relevant to your application. +It can also upload your source code to Sentry so it can be shown as part of the stack traces. To install the plugin, please update your app's `build.gradle` file as follows: @@ -22,11 +23,22 @@ buildscript { } } plugins { - id "io.sentry.android.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.0.0') }}" + id "io.sentry.android.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext = true + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" } ``` -The plugin version `{{@inject packages.version('sentry.java.android.gradle-plugin', '3.0.0') }}` will automatically add the Sentry Android SDK (version `{{@inject packages.version('sentry.java.android', '4.2.0') }}`) to your app. +The plugin version `{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}` will automatically add the Sentry Android SDK (version `{{@inject packages.version('sentry.java.android', '6.21.0') }}`) to your app. ## Connecting the SDK to Sentry diff --git a/src/wizard/java/index.md b/src/wizard/java/index.md index b928d5b1e624e..45f71fe59d5b8 100644 --- a/src/wizard/java/index.md +++ b/src/wizard/java/index.md @@ -13,6 +13,8 @@ type: language Install the SDK via Gradle, Maven, or SBT: +### Gradle + For **Gradle**, add to your `build.gradle` file: ```groovy @@ -27,6 +29,33 @@ dependencies { } ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Gradle plugin. + +```groovy +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext = true + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" +} +``` + +### Maven + For **Maven**, add to your `pom.xml` file: ```xml @@ -37,12 +66,59 @@ For **Maven**, add to your `pom.xml` file: ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Maven plugin. + +```xml + + + + io.sentry + sentry-maven-plugin + {{@inject packages.version('sentry.java.mavenplugin', '0.0.2') }} + + + true + + + + + /path/to/sentry-cli + + ___ORG_SLUG___ + + ___PROJECT_SLUG___ + + + + + + + ${env.SENTRY_AUTH_TOKEN} + + + + install + + uploadSourceBundle + + + + + + ... + +``` + +### SBT + For **SBT**: ```scala libraryDependencies += "io.sentry" % "sentry" % "{{@inject packages.version('sentry.java', '4.0.0') }}" ``` +To upload your source code to Sentry so it can be shown in stack traces, please refer to [Manually Uploading Source Context](https://docs.sentry.io/platforms/java/source-context). + ## Configure Configure Sentry as soon as possible in your application's lifecycle: diff --git a/src/wizard/java/log4j2.md b/src/wizard/java/log4j2.md index a4d6d4970ef27..fed00c6d507aa 100644 --- a/src/wizard/java/log4j2.md +++ b/src/wizard/java/log4j2.md @@ -9,6 +9,8 @@ type: framework The sentry-log4j2 library provides Log4j 2.x support for Sentry via an Appender that sends logged exceptions to Sentry. +## Install + Install Sentry's integration with Log4j 2.x using either Maven or Gradle: ### Maven @@ -21,12 +23,82 @@ Install Sentry's integration with Log4j 2.x using either Maven or Gradle: ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Maven plugin. + +```xml + + + + io.sentry + sentry-maven-plugin + {{@inject packages.version('sentry.java.mavenplugin', '0.0.2') }} + + + true + + + + + /path/to/sentry-cli + + ___ORG_SLUG___ + + ___PROJECT_SLUG___ + + + + + + + ${env.SENTRY_AUTH_TOKEN} + + + + install + + uploadSourceBundle + + + + + + ... + +``` + ### Gradle ```groovy implementation 'io.sentry:sentry-log4j2:{{@inject packages.version('sentry.java.log4j2', '4.0.0') }}' ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Gradle plugin. + +```groovy +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext = true + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" +} +``` + +## Configure + Configure Sentry as soon as possible in your application's lifecycle: diff --git a/src/wizard/java/logback.md b/src/wizard/java/logback.md index f77b0261a13f6..1a9569493a375 100644 --- a/src/wizard/java/logback.md +++ b/src/wizard/java/logback.md @@ -9,6 +9,8 @@ type: framework The sentry-logback library provides Logback support for Sentry using an Appender that sends logged exceptions to Sentry. +## Install + Install Sentry's integration with Logback using either Maven or Gradle: ### Maven @@ -21,14 +23,84 @@ Install Sentry's integration with Logback using either Maven or Gradle: ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Maven plugin. + +```xml + + + + io.sentry + sentry-maven-plugin + {{@inject packages.version('sentry.java.mavenplugin', '0.0.2') }} + + + true + + + + + /path/to/sentry-cli + + ___ORG_SLUG___ + + ___PROJECT_SLUG___ + + + + + + + ${env.SENTRY_AUTH_TOKEN} + + + + install + + uploadSourceBundle + + + + + + ... + +``` + ### Gradle ```groovy implementation 'io.sentry:sentry-logback:{{@inject packages.version('sentry.java.logback', '4.0.0') }}' ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Maven plugin. + +```groovy +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext = true + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" +} +``` + For other dependency managers see the [central Maven repository](https://search.maven.org/artifact/io.sentry/sentry-logback). +## Configure + Configure Sentry as soon as possible in your application's lifecycle: diff --git a/src/wizard/java/spring-boot.md b/src/wizard/java/spring-boot.md index b97b6499c412c..7113e98c6664a 100644 --- a/src/wizard/java/spring-boot.md +++ b/src/wizard/java/spring-boot.md @@ -13,11 +13,15 @@ There are two variants of Sentry available for Spring Boot. If you're using Spri Sentry's integration with Spring Boot supports Spring Boot 2.1.0 and above to report unhandled exceptions as well as release and registration of beans. If you're on an older version, use our legacy integration. +## Install + Install using either Maven or Gradle: ### Maven -```xml {tabTitle: Spring Boot 2} +#### Spring Boot 2 + +```xml io.sentry sentry-spring-boot-starter @@ -25,7 +29,9 @@ Install using either Maven or Gradle: ``` -```xml {tabTitle: Spring Boot 3} +#### Spring Boot 3 + +```xml io.sentry sentry-spring-boot-starter-jakarta @@ -35,14 +41,20 @@ Install using either Maven or Gradle: ### Gradle -```groovy {tabTitle: Spring Boot 2} +#### Spring Boot 2 + +```groovy implementation 'io.sentry:sentry-spring-boot-starter:{{@inject packages.version('sentry.java.spring-boot', '4.0.0') }}' ``` -```groovy {tabTitle: Spring Boot 3} +#### Spring Boot 3 + +```groovy implementation 'io.sentry:sentry-spring-boot-starter-jakarta:{{@inject packages.version('sentry.java.spring-boot.jakarta', '6.7.0') }}' ``` +## Configure + Open up `src/main/application.properties` (or `src/main/application.yml`) and configure the DSN, and any other [_settings_](/platforms/java/configuration/#options) you need: Modify `src/main/application.properties`: @@ -76,15 +88,85 @@ If you use Logback for logging you may also want to send error logs to Sentry. A ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Maven plugin. + +```xml + + + + io.sentry + sentry-maven-plugin + {{@inject packages.version('sentry.java.mavenplugin', '0.0.2') }} + + + true + + + + + /path/to/sentry-cli + + ___ORG_SLUG___ + + ___PROJECT_SLUG___ + + + + + + + ${env.SENTRY_AUTH_TOKEN} + + + + install + + uploadSourceBundle + + + + + + ... + +``` + ### Gradle ```groovy {tabTitle:Gradle} implementation 'io.sentry:sentry-logback:{{@inject packages.version('sentry.java.logback', '4.0.0') }}' ``` +To upload your source code to Sentry so it can be shown in stack traces, use our Gradle plugin. + +```groovy +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext = true + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" +} +``` + +### Send First Event + Then create an intentional error, so you can test that everything is working using either Java or Kotlin: -### Java +#### Java ```java import java.lang.Exception; @@ -97,7 +179,7 @@ try { } ``` -### Kotlin +#### Kotlin ```kotlin import java.lang.Exception @@ -118,9 +200,11 @@ If you're an existing user and have disabled alerts, you won't receive this emai Each incoming Spring MVC HTTP request is automatically turned into a transaction. To create spans around bean method executions, annotate bean method with `@SentrySpan` annotation: -### Java +#### Java + +##### Spring Boot 2 -```java {tabTitle: Spring Boot 2} +```java import org.springframework.stereotype.Component; import io.sentry.spring.tracing.SentrySpan; @@ -134,7 +218,9 @@ class PersonService { } ``` -```java {tabTitle: Spring Boot 3} +##### Spring Boot 3 + +```java import org.springframework.stereotype.Component; import io.sentry.spring.jakarta.tracing.SentrySpan; @@ -148,9 +234,11 @@ class PersonService { } ``` -### Kotlin +#### Kotlin + +##### Spring Boot 2 -```kotlin {tabTitle: Spring Boot 2} +```kotlin import org.springframework.stereotype.Component import io.sentry.spring.tracing.SentrySpan @@ -164,7 +252,9 @@ class PersonService { } ``` -```kotlin {tabTitle: Spring Boot 3} +##### Spring Boot 3 + +```kotlin import org.springframework.stereotype.Component import io.sentry.spring.jakarta.tracing.SentrySpan diff --git a/src/wizard/java/spring.md b/src/wizard/java/spring.md index b65ad37a1dfb6..dddaa3fc2ba81 100644 --- a/src/wizard/java/spring.md +++ b/src/wizard/java/spring.md @@ -13,11 +13,15 @@ type: framework Sentry's integration with Spring supports Spring Framework 5.1.2 and above to report unhandled exceptions and optional user information. If you're on an older version, use our legacy integration. +## Install + Install Sentry's integration with Spring using either Maven or Gradle: ### Maven: -```xml {tabTitle:Spring 5}{filename:pom.xml} +#### Spring 5 + +```xml io.sentry sentry-spring @@ -25,6 +29,8 @@ Install Sentry's integration with Spring using either Maven or Gradle: ``` +#### Spring 6 + ```xml {tabTitle:Spring 6}{filename:pom.xml} io.sentry @@ -33,18 +39,96 @@ Install Sentry's integration with Spring using either Maven or Gradle: ``` +#### Source Context + +To upload your source code to Sentry so it can be shown in stack traces, use our Maven plugin. + +```xml + + + + io.sentry + sentry-maven-plugin + {{@inject packages.version('sentry.java.mavenplugin', '0.0.2') }} + + + true + + + + + /path/to/sentry-cli + + ___ORG_SLUG___ + + ___PROJECT_SLUG___ + + + + + + + ${env.SENTRY_AUTH_TOKEN} + + + + install + + uploadSourceBundle + + + + + + ... + +``` + ### Gradle: -```groovy {tabTitle:Spring 5}{filename:build.gradle} +#### Spring 5 + +```groovy implementation 'io.sentry:sentry-spring:{{@inject packages.version('sentry.java.spring', '4.0.0') }}' ``` -```groovy {tabTitle:Spring 6}{filename:build.gradle} +#### Spring 6 + +```groovy implementation 'io.sentry:sentry-spring-jakarta:{{@inject packages.version('sentry.java.spring.jakarta', '6.7.0') }}' ``` +#### Source Context + +To upload your source code to Sentry so it can be shown in stack traces, use our Gradle plugin. + +```groovy +buildscript { + repositories { + mavenCentral() + } +} + +plugins { + id "io.sentry.jvm.gradle" version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.9.0') }}" +} + +sentry { + // Generates a JVM (Java, Kotlin, etc.) source bundle and uploads your source code to Sentry. + // This enables source context, allowing you to see your source + // code as part of your stack traces in Sentry. + includeSourceContext = true + + org = "___ORG_SLUG___" + projectName = "___PROJECT_SLUG___" + authToken = "your-sentry-auth-token" +} +``` + For other dependency managers see the [central Maven repository (Spring 5)](https://search.maven.org/artifact/io.sentry/sentry-spring) and [central Maven repository (Spring 6)](https://search.maven.org/artifact/io.sentry/sentry-spring-jakarta). +## Configure + Configure Sentry as soon as possible in your application's lifecycle: @@ -55,7 +139,9 @@ The `sentry-spring` and `sentry-spring-jakarta` libraries provide an `@EnableSen ### Java -```java {tabTitle: Spring 5} +#### Spring 5 + +```java import io.sentry.spring.EnableSentry; @EnableSentry(dsn = "___PUBLIC_DSN___") @@ -64,7 +150,9 @@ class SentryConfiguration { } ``` -```java {tabTitle: Spring 6} +#### Spring 6 + +```java import io.sentry.spring.jakarta.EnableSentry; @EnableSentry(dsn = "___PUBLIC_DSN___") @@ -75,7 +163,9 @@ class SentryConfiguration { ### Kotlin -```kotlin {tabTitle: Spring 5} +#### Spring 5 + +```kotlin import io.sentry.spring.EnableSentry import org.springframework.core.Ordered @@ -85,7 +175,9 @@ import org.springframework.core.Ordered ) ``` -```kotlin {tabTitle: Spring 6} +#### Spring 6 + +```kotlin import io.sentry.spring.jakarta.EnableSentry import org.springframework.core.Ordered