Feeling bold?
Ask A Bot
Product
API
Changelog
Sign In

Source Context

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
    projectRepresents your service in Sentry and allows you to scope events to a distinct application.
  • 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 docs.

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

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

You can create an auth

tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
by visiting the Organization Auth Tokens settings page in Sentry.io.

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

We have a Sentry Gradle Plugin available.

Set the auth

tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
as an environment variable to be used when running your release build.

Copied
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

Add the Sentry Gradle plugin to your

projectRepresents your service in Sentry and allows you to scope events to a distinct application.
by adding the following lines:

Make sure the assemble task is executed.

Copied
buildscript {
    repositories {
        mavenCentral()
    }
}

plugins {
    id "io.sentry.jvm.gradle" version "3.13.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 = "example-org"
    projectName = "example-project"
    authToken = System.getenv("SENTRY_AUTH_TOKEN")
}

Using the Maven Build Tool Plugin

We have a Sentry Maven Plugin available.

Set the auth

tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
as an environment variable to be used when running your release build.

Copied
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE

Add the Sentry Maven Plugin to your

projectRepresents your service in Sentry and allows you to scope events to a distinct application.
by adding the following lines to your pom.xml file:

Copied
<build>
    <plugins>
        <plugin>
            <groupId>io.sentry</groupId>
            <artifactId>sentry-maven-plugin</artifactId>
            <version>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>example-org</org>

                <project>example-project</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>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>uploadSourceBundle</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:

Copied
https://github.com/getsentry/sentry-cli/releases/tag/2.21.1

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

tokenIn search, a key-value pair or raw search term. Also, a value used for authorization.
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:

Copied
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:

Copied
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.

Copied
io.sentry.bundle-ids=A_VALID_UUID

sentry.properties

Copied
bundle-ids=A_VALID_UUID

SentryOptions

Copied
options.addBundleId("A_VALID_UUID");
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) to suggesting an update ("yeah, this would be better").
Suggest an edit to this page   |  Contribute to Docs   |  Report a problem
Package:
maven:io.sentry:sentry
Version:
6.30.0
Repository:
https://github.com/getsentry/sentry-java