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 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 docs.
Source Context also works with ProGuard. See the ProGuard & DexGuard docs for more information.
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 Auth Tokens settings page in Sentry.io.
- 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
We have a Sentry Gradle Plugin available.
Set the auth token as an environment variable to be used when running your release build.
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
Add the Sentry Gradle plugin to your project by adding the following lines:
plugins {
id "io.sentry.android.gradle" version "4.4.1"
}
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")
}
By default native code (C/C++) is not uploaded with the Java/Kotlin code. Add the following options to enable Source Context for native code:
sentry {
// Includes the source code of native code when uploading native symbols for Sentry.
// This executes sentry-cli with the --include-sources param. automatically so
// you don't need to do it manually. This only works with uploadNativeSymbols enabled.
//
// Default is disabled.
includeNativeSources = true
// Enables the automatic configuration of Native Symbols for Sentry.
// This executes sentry-cli automatically so you don't need to do it manually.
//
// Default is disabled.
uploadNativeSymbols = true
}
If you have a code generation step in your build (e.g. Quarkus) you will see an error similar to this:
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:
tasks.named("sentryCollectSourcesJava") {
// Make the task run after the tasks that generate code during build
mustRunAfter("CodeGenTask1", "CodeGenTask2")
}
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.
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
Next, upload that source bundle to Sentry:
sentry-cli debug-files upload --type jvm path/to/bundle
You'll need to tell the SDK which source bundle it should use for providing Source Context via one of the following options:
Add a sentry-debug-meta.properties
file to your application resources at build time which will be picked up automatically by the SDK.
io.sentry.bundle-ids=A_VALID_UUID
bundle-ids=A_VALID_UUID
options.addBundleId("A_VALID_UUID");
Upload the native debug symbols manually using the debug-files upload command
. Adding the --include-sources
flag, sentry-cli will automatically generate source bundles on the fly and upload them. Here's a typical example for Android:
sentry-cli debug-files upload app/build/intermediates/merged_native_libs/ --include-sources
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").
- Package:
- maven:io.sentry:sentry-android
- Version:
- 7.8.0
- Repository:
- https://github.com/getsentry/sentry-java
- API Documentation:
- https://javadoc.io/doc/io.sentry