Document Java Source Context

src/docs/product/cli/dif.mdx

@@ -311,3 +311,48 @@ UUIDs into a properties file.
 `--require-one`
 
 : Requires at least one file to upload or the command will error.
+
+## JVM Source Bundles
+
+`sentry-cli` can be used to upload source files for any JVM based language like
+Java or Kotlin to Sentry; however, in most situations, you would use one of our
+build tool plugins to do that ([Android](/platforms/android/source-context/)
+[Java](/platforms/java/source-context/)). Nevertheless, there may be situations
+where you would upload source bundle files manually.
+
+<Note>
+
+You need to specify the organization and project you are working with
+because source bundle files work on projects. For more information about this refer to
+[Working with Projects](/product/cli/configuration/#sentry-cli-working-with-projects).
+
+</Note>
+
+### Creating a Source Bundle
+
+The `debug-files bundle-jvm` command can be used 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
+```
+
+Since the Java/Android SDK needs to send the UUID of the source bundle, you need to
+provide it. More details can be found in the [Java SDK docs](/platforms/java/source-context/#manually-uploading-source-context) and [Android SDK Docs](/platforms/android/source-context/#manually-uploading-source-context)
+
+### Uploading a Source Bundle
+
+The `debug-files upload` command allows you to upload the previously created source
+bundle 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 that it worked, you can check _Project Settings > Debug Files_ and see if the uploaded source bundle files are listed.

src/platform-includes/source-context/java.mdx

@@ -0,0 +1,298 @@
+If you want to see your source code as part of stack traces in Sentry, you can enable the Source Context feature by adding
+one of our build tool plugins to your project. You may also manually upload source bundle by using [sentry-cli](/product/cli/dif/#jvm-source-bundles).
+
+It works the same either way. A (random) UUID will be or has to be generated and placed into the `sentry-debug-meta.properties`. The same UUID has to be used to upload the source bundle file. Whenever an error is sent to Sentry, this UUID will be sent along, allowing
+the Sentry server to look up source code in the source bundle with matching ID.
+
+![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
+[auth token user settings page](https://sentry.io/settings/account/api/auth-tokens/).
+The auth token requires either a `project:releases` or `project:write` Scope.
+
+<PlatformSection supported={["android"]}>
+
+Source Context also works with [ProGuard](/platforms/android/proguard/).
+
+</PlatformSection>
+
+## Known Limitations
+
+- Multiple files with same name but different extension will lead to undefined behaviour
+  - 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
+
+<PlatformSection supported={["android"]}>
+
+- Kotlin files may contain multiple classes but this feature may be broken by code obfuscation tools like ProGuard or R8
+- For AGP < 7.4 we don't add generated sources yet
+
+</PlatformSection>
+
+## Gradle Plugin
+
+You can add the plugin to your project by adding the following lines and making sure the `assemble` task is executed:
+
+<PlatformSection supported={["android"]}>
+
+```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 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 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")
+}
+```
+
+</PlatformSection>
+
+<PlatformSection notSupported={["android"]}>
+
+```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 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 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")
+}
+```
+
+</PlatformSection>
+
+<PlatformSection notSupported={["android"]}>
+
+## Maven Plugin
+
+We also offer a [Sentry Maven Plugin](https://github.com/getsentry/sentry-maven-plugin).
+
+You can add the plugin to your `pom.xml` by adding the following lines:
+
+```xml
+<build>
+    <plugins>
+        <plugin>
+            <groupId>io.sentry</groupId>
+            <artifactId>sentry-maven-plugin</artifactId>
+            <version>{{@inject packages.version('sentry.java.mavenplugin', '0.0.2') }}</version>
+            <configuration>
+                <!-- for showing output of sentry-cli -->
+                <debugSentryCli>true</debugSentryCli>
+
+                <!-- download the latest sentry-cli and provide path to it here -->
+                <!-- download it here: https://github.com/getsentry/sentry-cli/releases -->
+                <!-- minimum required version is 2.17.3 -->
+                <sentryCliExecutablePath>/path/to/sentry-cli</sentryCliExecutablePath>
+
+                <org>___ORG_SLUG___</org>
+
+                <project>___PROJECT_SLUG___</project>
+
+                <!-- in case you're self hosting, provide the URL here -->
+                <!--<url>http://localhost:8000/</url>-->
+
+                <!-- provide your auth token via SENTRY_AUTH_TOKEN environment variable -->
+                <!-- you can find it in Sentry UI: Settings > Account > API > Auth Tokens -->
+                <authToken>${env.SENTRY_AUTH_TOKEN}</authToken>
+            </configuration>
+            <executions>
+                <execution>
+                    <phase>install</phase>
+                    <goals>
+                        <goal>uploadSourceBundle</goal>
+                    </goals>
+                </execution>
+            </executions>
+        </plugin>
+    </plugins>
+    ...
+</build>
+```
+
+For now you have to 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') }}
+```
+
+</PlatformSection>
+
+## Manually Uploading Source Context
+
+If your build tool of choice isn't supported yet or there are other reasonsfor not
+using our Gradle or Maven plugins, you can manually create and upload source bundles.
+
+The `sentry-cli` commands allow you to supply `--org` and `--project` as well as providing the auth token by setting the `SENTRY_AUTH_TOKEN` environment variable.
+Another option is to use `.sentryclirc` or a `.properties` file which you can link using the `SENTRY_PROPERTIES` environment variable.
+
+### Creating the Source Bundle
+
+First you have to 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 you can upload that source bundle to Sentry.
+
+```
+sentry-cli debug-files upload --type jvm path/to/bundle
+```
+
+### Configuring the SDK
+
+You have 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` 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
+```
+
+<PlatformSection supported={["java.spring"]}>
+
+#### `application.properties`
+
+```properties
+sentry.bundle-ids=A_VALID_UUID`
+```
+
+</PlatformSection>
+
+#### `SentryOptions`
+
+```Java
+options.addBundleId("A_VALID_UUID");
+```