---
title: "Source Context"
description: "Learn about showing your source code as part of stack traces."
url: https://docs.sentry.io/platforms/java/guides/logback/source-context/
---

# Source Context | Sentry for Logback

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](https://docs.sentry.io/cli/dif.md#jvm-source-bundles) docs.

### [UUIDs](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#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.

All of the following methods require `org`, `project` and an `authToken`.

You can create an auth token by visiting the [Organization Tokens](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) settings page in Sentry.io.

## [Known Limitations](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#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

## [Using the Gradle Build Tool Plugin](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#using-the-gradle-build-tool-plugin)

We have a [Sentry Gradle Plugin](https://github.com/getsentry/sentry-android-gradle-plugin) available.

Set the auth token as an environment variable to be used when running your release build.

```bash
export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
```

Add the Sentry Gradle plugin to your project by adding the following lines:

Make sure the `assemble` task is executed.

```groovy
plugins {
    id "io.sentry.jvm.gradle" version "6.3.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 = System.getenv("SENTRY_AUTH_TOKEN")
}
```

### [Source Context for Generated Code](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#source-context-for-generated-code)

If you have a code generation step in your build (e.g. Quarkus) you will see an error similar to this:

```bash
Task ':xxx:sentryCollectSourcesJava' uses this output of task ':xxx:quarkusGenerateCode' without declaring an explicit or implicit dependency. This can lead to incorrect results being produced, depending on what order the tasks are executed.
```

To resolve this, declare a task dependency for `sentryCollectSourcesJava` on code generation tasks that exist in your build:

```groovy
tasks.named("sentryCollectSourcesJava") {
    // Make the task run after the tasks that generate code during build
    mustRunAfter("CodeGenTask1", "CodeGenTask2")
}
```

## [Using the Maven Build Tool Plugin](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#using-the-maven-build-tool-plugin)

We have a [Sentry Maven Plugin](https://github.com/getsentry/sentry-maven-plugin) available.

Set the auth token as an environment variable to be used when running your release build.

```bash
export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
```

Add the Sentry Maven Plugin to your project by adding the following lines to your `pom.xml` file:

```xml
<build>
    <plugins>
        <plugin>
            <groupId>io.sentry</groupId>
            <artifactId>sentry-maven-plugin</artifactId>
            <version>0.11.0</version>
            <!-- Required to allow auto-install of Sentry SDK and Integrations -->
            <extensions>true</extensions>
            <configuration>
                <!-- for showing output of sentry-cli -->
                <debugSentryCli>true</debugSentryCli>

                <!-- optionally specify the path to sentry-cli -->
                <!-- download it here: https://github.com/getsentry/sentry-cli/releases -->
                <!-- minimum required version is 2.21.2 -->
                <!-- by default the sentry-cli bundled with the plugin will be used -->
                <!-- <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 -->
                <authToken>${env.SENTRY_AUTH_TOKEN}</authToken>
            </configuration>
            <executions>
                <execution>
                    <goals>
                        <!--  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. -->
                        <goal>uploadSourceBundle</goal>
                        <!--  Validates Sentry SDK dependency versions. -->
                        <!--  Mixing SDK dependency versions can result in build or run time errors. -->
                        <!--  If mixed versions are detected, the build will fail. -->
                        <goal>validateSdkDependencyVersions</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
    ...
</build>
```

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:

```bash
https://github.com/getsentry/sentry-cli/releases/tag/3.3.5
```

## [Manually Uploading Source Context](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#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](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#creating-the-source-bundle)

First, create the source bundle containing your source files:

```bash
sentry-cli debug-files bundle-jvm --output path/to/store/bundle --debug-id A_VALID_UUID path/to/source-code
```

### [Uploading the Source Bundle](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#uploading-the-source-bundle)

Next, upload that source bundle to Sentry:

```bash
sentry-cli debug-files upload --type jvm path/to/bundle
```

### [Configuring the SDK](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#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`](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#sentry-debug-metaproperties)

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`](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#sentryproperties)

```properties
bundle-ids=A_VALID_UUID
```

#### [`SentryOptions`](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#sentryoptions)

```Java
options.addBundleId("A_VALID_UUID");
```

## [Setting Up Code Mappings](https://docs.sentry.io/platforms/java/guides/logback/source-context.md#setting-up-code-mappings)

To use suspect commits and stack trace linking, you'll need to set up a code mapping. This is a mapping between the source code in your repository and the source code in your stack traces. You can [set up code mappings manually in the Sentry UI](https://docs.sentry.io/product/issues/suspect-commits.md#set-up-code-mappings) or [upload code mappings in bulk via Sentry CLI](https://docs.sentry.io/cli/code-mappings.md). We recommend using the CLI if your project has many modules.

Use the following steps to determine the correct **Stack Trace Root** **Source Code Root** while setting up your code mapping:

First, navigate to a stack trace that you wish to map. Find an **In App** frame, which is denoted by a bubble on the right side of the frame. The Java module will be shown as the first piece of text at the left hand side of the frame header (marked as **1** in the below screenshot). In this example, it is `com.example.vu.android.MainActivity`. Hovering over the module will show the absolute path to the file (marked as **2** in the below screenshot). In this example, it is `MainActivity.java`.

Next, calculate the derived file path. Take the frame `module` and replace all `.` characters with `/`. Then, replace the last item (`MainActivity` in this example) with the absolute path found earlier (`MainActivity.java`). In this example, the derived file path is `com/example/vu/android/MainActivity.java`.

Finally, compare the derived with the path found in your source repository. In this example, the `com/example/vu/android/` folder may match the `src/com/example/vu/android/` folder in the source code. Using that information, set the **Stack Trace Root** to `com/example/vu/android/` and the **Source Code Root** to `src/com/example/vu/android/`. This tells Sentry to replace all file paths beginning in `com/example/vu/android/` with `src/com/example/vu/android/` when searching for the source code.

Because Sentry will use the first matching code mapping, it is recommended to always provide a non-empty value for the **Stack Trace Root** when possible. An empty value in the **Stack Trace Root** will match all file paths, which will work poorly if multiple code mappings are required.