docs(cli): Add code mappings documentation page#17196
Open
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: Unrelated Android session replay changes included in PR
- Removed the accidental Android session replay
beforeErrorSamplingdocs from both affected files and pushed a single focused commit.
- Removed the accidental Android session replay
Or push these changes by commenting:
@cursor push b8f666ce65
Preview (b8f666ce65)
diff --git a/docs/platforms/android/session-replay/configuration.mdx b/docs/platforms/android/session-replay/configuration.mdx
--- a/docs/platforms/android/session-replay/configuration.mdx
+++ b/docs/platforms/android/session-replay/configuration.mdx
@@ -29,7 +29,6 @@
| networkRequestHeaders | `io.sentry.session-replay.network-request-headers` | List<String> | `['Content-Type', 'Content-Length', 'Accept']` | Request header names to capture for enabled URLs. |
| networkResponseHeaders| `io.sentry.session-replay.network-response-headers` | List<String> | `['Content-Type', 'Content-Length', 'Accept']` | Response header names to capture for enabled URLs. |
| debug | `io.sentry.session-replay.debug` | boolean | `false` | Enables Session Replay debug logging, which prints diagnostic information when a replay is recorded. |
- | beforeErrorSampling | `—` | `BeforeErrorSamplingCallback` | `null` | A callback invoked before the `onErrorSampleRate` is checked. Return `false` to skip replay capture for this error, or `true` to proceed with the normal sample rate check. If the callback throws, replay capture proceeds normally (fail-open). Only configurable in code. See [Ignore Certain Errors from Error Sampling](/platforms/android/session-replay/#ignore-certain-errors-from-error-sampling). |
## Network Details
diff --git a/docs/platforms/android/session-replay/index.mdx b/docs/platforms/android/session-replay/index.mdx
--- a/docs/platforms/android/session-replay/index.mdx
+++ b/docs/platforms/android/session-replay/index.mdx
@@ -121,37 +121,6 @@
Sampling begins as soon as a session starts. `sessionSampleRate` is evaluated first. If it's sampled, the replay recording will begin. Otherwise, `onErrorSampleRate` is evaluated and if it's sampled, the integration will begin buffering the replay and will only upload it to Sentry if an error occurs. The remainder of the replay will behave similarly to a whole-session replay.
-### Ignore Certain Errors from Error Sampling
-
-Once you've enabled `onErrorSampleRate`, you can further customize which errors should trigger a replay capture by using the `beforeErrorSampling` callback. This is useful if you want to capture replays only for unhandled errors, or exclude certain error types from replay capture.
-
-The `beforeErrorSampling` callback is called when an error occurs and receives the event and hint as arguments. Returning `false` will prevent the replay from being captured for that specific error. If the callback throws an exception, replay capture proceeds normally (fail-open).
-
-```kotlin {tabTitle:Kotlin}
-SentryAndroid.init(context) { options ->
- options.dsn = "___PUBLIC_DSN___"
- options.sessionReplay.onErrorSampleRate = 1.0
-
- options.sessionReplay.beforeErrorSampling =
- SentryReplayOptions.BeforeErrorSamplingCallback { event, hint ->
- // Only capture replays for unhandled/crashed events
- event.isCrashed
- }
-}
-```
-
-```java {tabTitle:Java}
-SentryAndroid.init(context, options -> {
- options.setDsn("___PUBLIC_DSN___");
- options.getSessionReplay().setOnErrorSampleRate(1.0);
-
- options.getSessionReplay().setBeforeErrorSampling((event, hint) -> {
- // Only capture replays for unhandled/crashed events
- return event.isCrashed();
- });
-});
-```
-
## Privacy
The SDK is recording and aggressively masking all text, images, and webviews by default. If your app has any sensitive data, you should only turn the default masking off after explicitly masking out the sensitive data, using the APIs described below.This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.
Add a new CLI docs page for code mappings with upload command usage, JSON format, options, batching, and CI/CD integration. Also add backlinks from suspect commits, Java source context, and GitHub integration pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
romtsn
force-pushed
the
rz/feat/code-mappings-cli-docs
branch
from
e37e221 to
6d06adb
Compare
Comment on lines
+17
to
+21
| <Alert> | ||
|
|
||
| You need to specify the organization and project you are working with because code mappings work on projects. For more information about this refer to [Working with Projects](/cli/configuration/#sentry-cli-working-with-projects). | ||
|
|
||
| </Alert> |
Member
There was a problem hiding this comment.
I think we can leave this out. The command should error if any required arguments are missing.
Suggested change
| <Alert> | |
| You need to specify the organization and project you are working with because code mappings work on projects. For more information about this refer to [Working with Projects](/cli/configuration/#sentry-cli-working-with-projects). | |
| </Alert> |
Member
Author
There was a problem hiding this comment.
This was also a copy from Debug Files and Release Management, so if you want to drop this we should align all of them, I believe
Member
There was a problem hiding this comment.
Let's drop it here; we can align on the other pages in a separate PR
Comment on lines
+23
to
+38
| ```bash | ||
| sentry-cli code-mappings upload ./mappings.json \ | ||
| --org my-org \ | ||
| --project my-project \ | ||
| --repo owner/repo \ | ||
| --default-branch main | ||
| ``` | ||
|
|
||
| ### Options | ||
|
|
||
| | Option | Required | Description | | ||
| |--------|----------|-------------| | ||
| | `--org` | Required | The organization slug. Can also be set via `SENTRY_ORG` or in `.sentryclirc`. | | ||
| | `--project` | Required | The project slug. Can also be set via `SENTRY_PROJECT` or in `.sentryclirc`. | | ||
| | `--repo` | Optional | The repository name (e.g. `getsentry/sentry`). Defaults to the git remote origin. Required if not running from within a git repository. | | ||
| | `--default-branch` | Optional | The default branch name. Defaults to the git remote HEAD or `main`. Required if not running from within a git repository. | |
Member
There was a problem hiding this comment.
m: Let's keep the example invocation minimal (the only strictly required argument is the path to the mappings; everything else can be auto-detected or configured via environment variables that folks may already be setting). Also, let's not document the options here, and instead point folks towards --help. Documenting here increases risk of divergence in the future.
Suggested change
| ```bash | |
| sentry-cli code-mappings upload ./mappings.json \ | |
| --org my-org \ | |
| --project my-project \ | |
| --repo owner/repo \ | |
| --default-branch main | |
| ``` | |
| ### Options | |
| | Option | Required | Description | | |
| |--------|----------|-------------| | |
| | `--org` | Required | The organization slug. Can also be set via `SENTRY_ORG` or in `.sentryclirc`. | | |
| | `--project` | Required | The project slug. Can also be set via `SENTRY_PROJECT` or in `.sentryclirc`. | | |
| | `--repo` | Optional | The repository name (e.g. `getsentry/sentry`). Defaults to the git remote origin. Required if not running from within a git repository. | | |
| | `--default-branch` | Optional | The default branch name. Defaults to the git remote HEAD or `main`. Required if not running from within a git repository. | | |
| Use the `sentry-cli code-mappings upload` command to upload code mappings: | |
| ```bash | |
| sentry-cli code-mappings upload /path/to/code-mappings.json | |
| ``` | |
| See `sentry-cli code-mappings upload --help` for all options. |
| | `--repo` | Optional | The repository name (e.g. `getsentry/sentry`). Defaults to the git remote origin. Required if not running from within a git repository. | | ||
| | `--default-branch` | Optional | The default branch name. Defaults to the git remote HEAD or `main`. Required if not running from within a git repository. | | ||
|
|
||
| ### JSON File Format |
Member
There was a problem hiding this comment.
Is there a standardized way to generate such files? If so, I think we should mention it.
Member
Author
There was a problem hiding this comment.
nope, not really. I was thinking to add a sentry.io/changelog entry where I'd provide an example snippet on how to do this in Gradle, but I could also add it here if you prefer. Although, the next step would be to do this automatically in the Sentry Gradle plugin so this would make the snippet redundant.
Comment on lines
+42
to
+70
| The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`. | ||
|
|
||
| The following example is based on the [getsentry/sentry-java](https://github.com/getsentry/sentry-java) monorepo, which has multiple modules sharing the `io/sentry` package prefix: | ||
|
|
||
| ```json {filename:mappings.json} | ||
| [ | ||
| { | ||
| "stackRoot": "io/sentry/android/core", | ||
| "sourceRoot": "sentry-android-core/src/main/java/io/sentry/android/core" | ||
| }, | ||
| { | ||
| "stackRoot": "io/sentry/opentelemetry", | ||
| "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry" | ||
| }, | ||
| { | ||
| "stackRoot": "io/sentry/opentelemetry", | ||
| "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry" | ||
| }, | ||
| { | ||
| "stackRoot": "io/sentry", | ||
| "sourceRoot": "sentry/src/main/java/io/sentry" | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| - **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS). | ||
| - **sourceRoot**: The corresponding path in your repository where the source code lives. | ||
|
|
||
| Multiple mappings can share the same `stackRoot` if they point to different `sourceRoot` paths. In the example above, `io/sentry/opentelemetry` maps to two different modules. Sentry evaluates mappings from most specific to least specific, using the first one that resolves to a real file in the repository. |
Member
There was a problem hiding this comment.
l: I think it makes sense to reorder this. Right now, we start the description, have an example, then continue the description afterwards. I would do the full description first, then the example under a subheading, like so:
Suggested change
| The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`. | |
| The following example is based on the [getsentry/sentry-java](https://github.com/getsentry/sentry-java) monorepo, which has multiple modules sharing the `io/sentry` package prefix: | |
| ```json {filename:mappings.json} | |
| [ | |
| { | |
| "stackRoot": "io/sentry/android/core", | |
| "sourceRoot": "sentry-android-core/src/main/java/io/sentry/android/core" | |
| }, | |
| { | |
| "stackRoot": "io/sentry/opentelemetry", | |
| "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry" | |
| }, | |
| { | |
| "stackRoot": "io/sentry/opentelemetry", | |
| "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry" | |
| }, | |
| { | |
| "stackRoot": "io/sentry", | |
| "sourceRoot": "sentry/src/main/java/io/sentry" | |
| } | |
| ] | |
| ``` | |
| - **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS). | |
| - **sourceRoot**: The corresponding path in your repository where the source code lives. | |
| Multiple mappings can share the same `stackRoot` if they point to different `sourceRoot` paths. In the example above, `io/sentry/opentelemetry` maps to two different modules. Sentry evaluates mappings from most specific to least specific, using the first one that resolves to a real file in the repository. | |
| The input file should be a JSON array of mapping objects, each with a `stackRoot` and `sourceRoot`: | |
| - **stackRoot**: The path prefix as it appears in stack traces (e.g. `io/sentry/android/core` for Java, `src/` for Python/JS). | |
| - **sourceRoot**: The corresponding path in your repository where the source code lives. | |
| Multiple mappings can share the same `stackRoot` if they point to different `sourceRoot` paths. In the example below, `io/sentry/opentelemetry` maps to two different modules. Sentry evaluates mappings from most specific to least specific, using the first one that resolves to a real file in the repository. | |
| #### Example | |
| This example is based on the [getsentry/sentry-java](https://github.com/getsentry/sentry-java) monorepo, which has multiple modules sharing the `io/sentry` package prefix: | |
| ```json {filename:mappings.json} | |
| [ | |
| { | |
| "stackRoot": "io/sentry/android/core", | |
| "sourceRoot": "sentry-android-core/src/main/java/io/sentry/android/core" | |
| }, | |
| { | |
| "stackRoot": "io/sentry/opentelemetry", | |
| "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-core/src/main/java/io/sentry/opentelemetry" | |
| }, | |
| { | |
| "stackRoot": "io/sentry/opentelemetry", | |
| "sourceRoot": "sentry-opentelemetry/sentry-opentelemetry-bootstrap/src/main/java/io/sentry/opentelemetry" | |
| }, | |
| { | |
| "stackRoot": "io/sentry", | |
| "sourceRoot": "sentry/src/main/java/io/sentry" | |
| } | |
| ] | |
| ``` |
|
|
||
| Code mappings link stack trace paths to source code paths in your repository. They enable features like [source context](/platforms/java/source-context/), [suspect commits](/product/issues/suspect-commits/), [stack trace linking](/organization/integrations/source-code-mgmt/github/#stack-trace-linking), and [code owners](/product/issues/ownership-rules/). | ||
|
|
||
| You can manage code mappings through the Sentry web UI (see [Setting Up Code Mappings](/product/issues/suspect-commits/#set-up-code-mappings)), or upload them in bulk using `sentry-cli`. |
Member
There was a problem hiding this comment.
m: Let's mention that you can use the CLI command in CI here. I think we can then eliminate the CI section at the bottom. Also, let's use "Sentry CLI" rather than sentry-cli.
l: Also, we can integrate the link to the web UI more cleanly in the text.
Suggested change
| You can manage code mappings through the Sentry web UI (see [Setting Up Code Mappings](/product/issues/suspect-commits/#set-up-code-mappings)), or upload them in bulk using `sentry-cli`. | |
| You can [manage code mappings through the Sentry web UI](/product/issues/suspect-commits/#set-up-code-mappings)), or upload them in bulk using Sentry CLI. It is also possible to upload code mappings automatically in your CI process using Sentry CLI. |
|
|
||
| ## Permissions | ||
|
|
||
| The `sentry-cli` requires an [Organization Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) with the `org:ci` scope to upload code mappings. |
Member
There was a problem hiding this comment.
m:
Suggested change
| The `sentry-cli` requires an [Organization Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) with the `org:ci` scope to upload code mappings. | |
| Sentry CLI requires an [Organization Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/) with the `org:ci` scope to upload code mappings. |
Comment on lines
+102
to
+114
| ## CI/CD Integration | ||
|
|
||
| You can run `sentry-cli code-mappings upload` as part of your CI/CD pipeline to keep code mappings in sync with your repository structure: | ||
|
|
||
| ```bash | ||
| sentry-cli code-mappings upload ./mappings.json \ | ||
| --org $SENTRY_ORG \ | ||
| --project $SENTRY_PROJECT \ | ||
| --repo $GITHUB_REPOSITORY \ | ||
| --default-branch $GITHUB_REF_NAME | ||
| ``` | ||
|
|
||
| For authentication, set the `SENTRY_AUTH_TOKEN` environment variable. See [Configuration](/cli/configuration/) for details. |
Member
There was a problem hiding this comment.
m: This section is unnecessary imo. Instead, we can mention the idea of using CLI in CI at the top.
Suggested change
| ## CI/CD Integration | |
| You can run `sentry-cli code-mappings upload` as part of your CI/CD pipeline to keep code mappings in sync with your repository structure: | |
| ```bash | |
| sentry-cli code-mappings upload ./mappings.json \ | |
| --org $SENTRY_ORG \ | |
| --project $SENTRY_PROJECT \ | |
| --repo $GITHUB_REPOSITORY \ | |
| --default-branch $GITHUB_REF_NAME | |
| ``` | |
| For authentication, set the `SENTRY_AUTH_TOKEN` environment variable. See [Configuration](/cli/configuration/) for details. |
| </Alert> | ||
|
|
||
| For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android as well as release and source maps management for other platforms. | ||
| For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android, release and source maps management, as well as [code mappings](/cli/code-mappings/) for other platforms. |
Member
There was a problem hiding this comment.
l: I think this change is unnecessary. This list is only for some examples of use cases, it is not meant to be exhaustive
Suggested change
| For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android, release and source maps management, as well as [code mappings](/cli/code-mappings/) for other platforms. | |
| For certain actions, you can use the `sentry-cli` command line executable. It can connect to the Sentry API and manage some data for your projects. It’s primarily used for managing debug information files for iOS, Android as well as release and source maps management for other platforms. |
Member
Author
There was a problem hiding this comment.
I think I'd keep it for discoverability purpose
Member
There was a problem hiding this comment.
I understand, but it is also awkward that code mappings is the only feature we mention there, which we also link to. So I'd consider removing the link, or adding a link for everything else, to keep it consistent 😄
Member
Author
There was a problem hiding this comment.
sure, I can drop the link 👍
| ## 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 find information on how to set up code mappings in our [Set Up Code Mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) docs. | ||
| 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 find information on how to set up code mappings in our [Set Up Code Mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) docs. For projects with many modules, you can also [upload code mappings in bulk via the CLI](/cli/code-mappings/). |
Member
There was a problem hiding this comment.
m: The link for "Set Up Code Mappings" is broken (I guess it was already broken before your PR, but it makes sense to fix here or in a separate PR alongside this one)
l: Also, I think it makes more sense to present the options of Sentry UI and CLI as alternatives. The existing page primarily describes the Sentry web UI path
Suggested change
| 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 find information on how to set up code mappings in our [Set Up Code Mappings](/product/issues/suspect-commits/#2-set-up-code-mappings) docs. For projects with many modules, you can also [upload code mappings in bulk via the CLI](/cli/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](/product/issues/suspect-commits/#set-up-code-mappings) or [upload code mappings in bulk via Sentry CLI](/cli/code-mappings/). We recommend using the CLI if your project has many modules. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/cli/code-mappings/covering thesentry-cli code-mappings uploadcommandTest plan
/cli/code-mappings/🤖 Generated with Claude Code