Sentry-CLI 使用详解(2021 Sentry v21.8.x)

内容源于：https://docs.sentry.io/platforms/javascript/guides/vue/

系列

• 1 分钟快速使用 Docker 上手最新版 Sentry-CLI - 创建版本
• 快速使用 Docker 上手 Sentry-CLI - 30 秒上手 Source Maps
• Sentry For React 完整接入详解
• Sentry For Vue 完整接入详解

脑图

公众号：黑客下午茶

安装

根据您的平台，有不同的方法可用于安装 sentry-cli。

手动下载

您可以在 GitHub release 页面上找到 release 列表。

我们提供适用于 Linux、OS X 和 Windows 的可执行文件。 这是一个单独的文件下载，在收到文件后，您可以将其重命名为 sentry-cli 或 sentry-cli.exe 以使用它。

• https://github.com/getsentry/sentry-cli/releases/

自动安装

如果你使用的是 OS X 或 Linux，你可以使用自动下载器，它会为你获取最新的发行版本并安装它：

curl -sL https://sentry.io/get-cli/ | bash

这将自动为您的操作系统下载正确版本的 sentry-cli 并安装它。如果有必要，它会提示您输入 sudo 的管理员密码。

要验证它是否正确安装，您可以调出帮助：

sentry-cli --help

通过 NPM 安装

对于特殊用例，还可以选择通过 npm 安装 sentry-cli。例如，这对于构建服务器很有用。该包名为 @sentry/cli，在安装后它将下载适当的发行版二进制文件：

npm install @sentry/cli

然后您可以在 .bin 文件夹中找到它：

./node_modules/.bin/sentry-cli --help

如果您想使用 sudo 在 npm 系统范围内安装它，您需要将 --unsafe-perm 传递给它：

sudo npm install -g @sentry/cli --unsafe-perm

但是，不建议进行此安装。

从自定义源下载

默认情况下，这个包会从 Fastly 管理的 CDN 下载 sentry-cli。要使用自定义 CDN，请设置 npm config 属性 sentrycli_cdnurl。下载器将附加 "/<version>/sentry-cli-<dist>"。

• https://www.fastly.com/

npm install @sentry/cli --sentrycli_cdnurl=https://mymirror.local/path

或者将属性添加到您的 .npmrc 文件中 (https://docs.npmjs.com/files/npmrc)

sentrycli_cdnurl=https://mymirror.local/path

另一种选择是使用环境变量 SENTRYCLI_CDNURL。

SENTRYCLI_CDNURL=https://mymirror.local/path npm install @sentry/cli

通过 Homebrew 安装

如果您使用的是 OS X，则可以通过 homebrew 安装 sentry-cli：

brew install getsentry/tools/sentry-cli

通过 Scoop 安装

如果您使用的是 Windows，您可以通过 Scoop 安装 sentry-cli：

• https://scoop.sh/

> scoop install sentry-cli

Docker 镜像

对于不受支持的发行版和 CI 系统，我们提供了一个预装了 sentry-cli 的 Docker 镜像。建议使用 latest tag，但您也可以固定到特定版本。默认情况下，该命令在 /work 目录中运行。 挂载相关的项目文件夹并在那里构建输出以允许 sentry-cli 扫描资源：

docker pull getsentry/sentry-cli
docker run --rm -v $(pwd):/work getsentry/sentry-cli --help

更新和卸载

您可以使用 sentry-cli update 和 sentry-cli uninstall 更新或卸载 sentry CLI。 这些命令在某些情况下可能不可用（例如，如果您使用 homebrew 安装 sentry-cli）。

配置和认证

对于大多数功能，您需要使用 Sentry 进行身份验证。设置可以使用 sentry-cli 自动完成，也可以手动完成。无论哪种方式，您都需要一个至少具有以下作用域(scope)的令牌：

• project:read
• project:releases
• org:read

使用自动选项

sentry-cli login

这将为您提供访问身份验证令牌用户(auth token user)设置的选项，您可以在其中创建新的 auth token，或简单地复制现有 token。当您返回 CLI 时，您将粘贴您的 token，它会自动添加到 ~/.sentryclirc 中。

默认情况下，sentry-cli 将连接到 sentry.io，但对于自托管，您也可以在其他地方登录：

sentry-cli --url https://myserver.invalid/ login

手动验证

访问您的身份验证令牌用户(auth token user)设置页面并创建或复制现有 token。然后：

• 添加它到 ~/.sentryclirc：

[auth]
token=your-auth-token

• 将其导出为环境变量：

export SENTRY_AUTH_TOKEN=your-auth-token

• 调用 sentry-cli 时将其作为参数传递：

sentry-cli --auth-token your-auth-token

配置文件

sentry-cli 工具可以使用名为 .sentryclirc 的配置文件以及环境变量和 .env 文件进行配置。 从当前路径向上查找配置文件，并且始终加载 ~/.sentryclirc 中的默认值。 您还可以从命令行参数覆盖这些设置。

配置文件使用标准 INI 语法。

默认 sentry-cli 将连接到 sentry.io。对于本地，您可以导出 SENTRY_URL 环境变量并将其指向您的安装：

export SENTRY_URL=https://mysentry.invalid/

或者，您可以将它添加到您的 ~/.sentryclirc 配置中。这也是 login 命令的作用：

[defaults]
url = https://mysentry.invalid/

默认 sentry-cli 加载 .env 文件。在 sentry-cli 1.24 及更新版本上，您可以通过导出环境变量 SENTRY_LOAD_DOTENV=0 来禁用此功能。

配置值

可以使用以下设置（首先是环境变量，括号中的值是 config 文件中的配置 key）：

SENTRY_AUTH_TOKEN (auth.token):

• 用于与 Sentry 的所有通信的身份验证令牌(authentication token)。

SENTRY_API_KEY (auth.api_key):

• 用于身份验证的旧 API key（如果您有的话）。

SENTRY_DSN (auth.dsn):

• 用于连接 sentry 的 DSN。

SENTRY_URL (defaults.url):

• 用于连接 sentry 的 URL。默认为 https://sentry.io/。

SENTRY_ORG (defaults.org):

• 用于命令的 organization(组织) 的 slug。

SENTRY_PROJECT (defaults.project):

• 用于命令的 project(项目) 的 slug。

SENTRY_VCS_REMOTE (defaults.vcs_remote):

• 版本控制系统中 remote 的名称。这默认为 origin。

SENTRY_PIPELINE (defaults.pipeline):

• 要附加到 User-Agent header 的环境(environment)名称。

CUSTOM_HEADER (defaults.custom_header):

• 将以 key:value 格式添加到每个传出请求的 header。

(http.keepalive):

• 仅 ini 设置，用于控制 SDK 在 HTTP keepalives 方面的行为。默认值为 true，但可以将其设置为 false 以禁用 keepalive 支持。

http_proxy (http.proxy_url):

• 应用于 HTTP proxy 的 URL。标准的 http_proxy 环境变量也受到尊重。请注意，它是小写的。

(http.proxy_username):

• 仅 ini 设置，设置代理用户名(proxy username)以防需要代理身份验证(proxy authentication)。

(http.proxy_password):

• 仅 ini设置，在需要代理身份验证时设置代理密码(proxy password)。

(http.verify_ssl):

• 这可用于在设置为 false 时禁用 SSL 验证。 除非您在本地使用已知的自签名服务器，否则您永远不应该这样做。

(http.check_ssl_revoke):

• 如果将其设置为 false，则在 Windows 上禁用 SSL 吊销(revocation)检查。 这在使用未正确实施吊销(revocation)检查的企业 SSL MITM proxy 时非常有用。 除非绝对必要，否则不要使用它。

SENTRY_HTTP_MAX_RETRIES(http.max_retries):

• 设置上传操作的最大重试次数（例如，上传 release 文件和调试符号symbols）。默认值为 5。

(ui.show_notifications):

• 如果将其设置为 false，则会禁用某些操作系统通知。这目前主要影响 xcode 构建，它不会显示后台构建的通知。

SENTRY_LOG_LEVEL (log.level):

• 配置 SDK 的日志级别。默认为 warn。如果您想查看库正在做什么，您可以将其设置为 info， 这将输出更多信息，这可能有助于调试一些权限(permissions)问题。

(dsym.max_upload_size):

• 将调试符号(debug symbols)的最大上传大小（以字节为单位）设置为一批(one batch)。默认为 35MB 或 100MB（取决于 sentry-cli 的版本），适用于 sentry.io 但如果您使用不同的 sentry 服务器，您可能需要在必要时更改此限制。

SENTRY_NO_PROGRESS_BAR:

• 如果设置为 1，则 sentry-cli 不会显示任何操作的进度条。

SENTRY_DISABLE_UPDATE_CHECK(update.disable_check):

• 如果设置为 true，则禁用 sentry-cli 中的自动更新检查。这是在 1.17 中引入的。 之前的版本不包括更新检查。目前还没有为基于 npm 的 sentry-cli 安装启用更新检查。

DEVICE_FAMILY (device.family):

• 向 Sentry 报告的设备系列(Device family)值。

DEVICE_MODEL (device.model):

• 向 Sentry 报告的设备型号(Device model)值。

验证配置

为了确保一切正常，您可以运行 sentry-cli info 并且它应该打印出有关您连接的 Sentry 安装的一些基本信息以及一些身份验证信息。

使用 Project

许多命令要求您指定要使用的组织(organization)和项目(project)。您可以通过多种方式指定此项。

配置默认值

如果您始终使用相同的项目，则可以在 .sentryclirc 文件中进行设置：

[defaults]
project=my-project
org=my-org

环境变量

您还可以在环境变量中设置这些默认值。

有两个环境变量可以控制它（SENTRY_ORG 和 SENTRY_PROJECT），您可以导出它们：

export SENTRY_ORG=my-org
export SENTRY_PROJECT=my-project

属性文件

此外，sentry-cli 支持从 .properties 文件加载配置值（在 Java 环境中很常见）。 您可以通过将路径导出到 SENTRY_PROPERTIES 环境变量中的属性文件来指示 sentry-cli 从那里加载配置文件。对于我们的一些客户端集成，如 Java 和 React Native，这通常是自动完成的。

在属性文件中，您只需使用点符号来设置值。例子：

defaults.url=https://mysentry.invalid/

然后指示 sentry-cli 使用该文件，请使用以下命令：

export SENTRY_PROPERTIES=/path/to/sentry.properties
sentry-cli ...

显式选项

最后，您还可以向正在执行的命令明确提供这些值。对于组织(organization)，这些参数始终称为 --org 或 -o，而对于项目(project)则称为 --project 或 -p。

请注意，它们并不总是使用相同的命令。例如，如果您正在管理 release（在整个组织中共享），您通常将 organization 提供给 releases 命令，但将 project 提供给它的子命令：

sentry-cli releases -o my-org new -p my-project 1.0

有关更多信息，请使用 help 命令，该命令将显示所有参数的文档。

Release 管理

sentry-cli 工具可用于 Sentry 上的 release 管理。

它允许您创建、编辑和删除 release 以及为它们上传 release artifact。请注意，每个组织的 release 都是 global 的。如果您希望将不同项目中的 release 视为单独的实体，请使 release 名称在整个组织中唯一。例如，如果您有共享版本号的 projectA 和 projectB，您可以分别将版本命名为 projectA-1.0 和 projectB-1.0。

由于 release 用于 project，因此您需要指定您正在使用的 organization 和 project。 有关这方面的更多信息，请参阅使用 project。

https://docs.sentry.io/product/cli/configuration/#sentry-cli-working-with-projects

创建 Release

Release 是使用 sentry-clireleases new 命令创建的。 它至少需要一个唯一标识版本的版本标识符(version identifier)。有一些限制 —— release 名称不能：

• 包含换行符、制表符、正斜杠 (/) 或反斜杠 (\)
• 是（全部）句号 (.)、双句号 (..) 或空格 ( )
• 超过 200 个字符

该值可以是任意的，但对于某些平台，存在以下建议：

• 对于移动设备，使用 package-name@version-number 或 package-name@version-number+build-number。不要使用 VERSION_NUMBER (BUILD_NUMBER)，因为括号是用于显示的（foo@1.0+2 变成 1.0 (2)），所以调用它们会导致错误。
• 如果您使用 DVCS，我们建议使用标识哈希（例如：commit SHA，da39a3ee5e6b4b0d3255bfef95601890afd80709）。您可以让 sentry-cli 自动为支持的版本控制系统确定此哈希，并使用 sentry-cli releases propose-version(建议版本)。
• 如果您标记 release，我们建议使用带有产品或包名称前缀的 release tag （例如，my-project-name@2.3.12）。

Release 也可以由不同的系统自动创建。例如，在上传 source map 时，会自动创建一个 release。同样，当 release 事件发生时，某些 client 会创建 release。

完成 Release

默认情况下，一个 release 创建为 “unreleased”。完成 release 意味着我们在 release 记录上填写第二个时间戳，在 UI 中对 release 进行排序时，它的优先级高于 date_created。 这也会影响 resolving issues 的“下一个版本(the next release)”，如果您使用 --auto，将哪个版本release用作关联提交的基础，并在活动流Activity stream中创建一个条目。

这可以通过将 --finalize 传递给 new 命令来更改，该命令将立即完成 release，或者您可以稍后单独调用 sentry-cli releases finalize VERSION。如果您将 release 作为构建过程的一部分进行管理，则后者很有用，例如：

#!/bin/sh
sentry-cli releases new "$VERSION"
# do your build steps here
# once you are done, finalize
sentry-cli releases finalize "$VERSION"

您还可以选择在 release 上线时（当您部署到您的机器、在 App Store 中启用等）时完成 release。

如果您正在使用 git，您可以要求 Sentry 确定 $VERSION：

#!/bin/sh
VERSION=`sentry-cli releases propose-version`

提交 Integration

如果您在 Sentry 组织中配置了存储库，您可以将提交与您的 release 相关联。

• https://docs.sentry.io/product/releases/setup/release-automation/

有两种模式可以使用它。一种是全自动模式。如果您从 git repository 部署并且 sentry-cli 可以从当前工作目录中发现 git repository，您可以使用 --auto 标志设置提交：

sentry-cli releases set-commits "$VERSION" --auto

如果您在无法访问 git repository 的情况下进行部署，则可以改为手动指定提交。为此，请将 --commit 参数以 REPO_NAME@REVISION 格式传递给 set-commits 命令。

sentry-cli releases set-commits "$VERSION" --commit "my-repo@deadbeef"

要查看组织可使用哪些存储库，您可以运行 sentry-cli repos list，它将返回已配置存储库的列表。

请注意，您需要参考使用实际完整 commit SHA 所需的 release。 如果要引用 tag 或 reference（如 HEAD），则需要检出存储库并可以从调用 sentry-cli 的路径访问该存储库。

如果您还想设置以前的提交而不是让服务器使用以前的 release 作为基点，您可以通过设置提交范围(commit range)来做到这一点：

sentry-cli releases set-commits "$VERSION" --commit "my-repo@from..to"

或者：没有 Repository Integration

您仍然可以使用 --auto 标志，CLI 将自动使用您 local repo 的 git tree，并将先前 release 的提交和当前的主要提交之间的提交与该 release 相关联。如果这是第一个 release，Sentry 将使用最新的 20 个提交。此行为可使用 --initial-depth 标志进行配置。

默认情况下，您可以使用 --local 标志启用此行为。

sentry-cli releases set-commits "$VERSION" --local

如果您收到“Unable to Fetch Commits”电子邮件，请查看我们的帮助中心文章。

• https://help.sentry.io/product-features/integrations/why-am-i-receiving-the-email-unable-to-fetch-commits/

处理丢失的提交

在某些情况下，您的存储库可能缺少先前在 release 中使用的提交。 每当您修改有问题的提交时，就会发生这种情况，例如，修改它、重新设置基数(rebasing)或将多个提交压缩在一起。在这种情况下，Sentry CLI 将无法找到它，并且会抛出无法找到提交的错误。

发生这种情况时，您可以传递一个额外的 --ignore-missing 标志。 这将允许命令回退到默认行为，即创建具有指定提交次数的 release（请参阅上面的部分）。

sentry-cli releases set-commits "$VERSION" --auto --ignore-missing

管理 Release Artifact

当您使用 JavaScript 和其他平台时，您可以将 release artifact 上传到 Sentry，然后在处理过程中考虑这些工件。最常见的 release artifact 是 sentry-cli 有特定支持的 source maps。

• https://docs.sentry.io/clients/javascript/sourcemaps/

要管理 release artifact，可以使用 sentry-cli releases files 命令，它本身提供了各种子命令。

上传文件

最常见的用例是上传文件。对于通用上传，可以使用 sentry-cli releases files VERSION upload 命令。然而，由于大多数 release artifact 都与 JavaScript source map 相关，因此我们有一个上传 Source Maps 方便的方法。

上传的文件通常以完整的（例如：http://example.com/foo.js）或截断的 URL（例如：~/foo.js）命名。

Release artifact 仅在事件处理时考虑。因此，虽然可以在事后修改 release artifact ，但它们只会被考虑用于该 release 的未来事件。

upload 的第一个参数是文件的路径，第二个是我们应该与之关联的可选 URL。 请注意，如果您想使用缩写的 URL（例如：~/foo.js），请确保使用单引号以避免 shell 扩展到您的主文件夹。

sentry-cli releases files "$VERSION" upload /path/to/file '~/file.js'

上传 Source Maps

对于 source map 上传，提供了一个单独的命令来帮助您上传和验证 source map：

sentry-cli releases files "$VERSION" upload-sourcemaps /path/to/sourcemaps

这个命令提供了一堆选项并尝试尽可能多的自动检测。默认情况下，它将扫描提供的文件路径并上传以 ~/ 前缀命名的路径。它还将尝试根据文件名找出 minified 文件和 source maps 之间的引用。 因此，如果您有一个名为 foo.min.js 的文件，它是一个 minified 的 JavaScript 文件和一个名为 foo.min.map 的source map，例如，它将发送一个很长的 Sourcemap header 来关联它们。这适用于系统可以检测到关系的文件。

默认情况下，sentry-cli 在上传之前重写 source maps：

1. 它将索引的 source maps 展平。这样做的优点是它有时可以压缩 source maps，这可能会改善您的处理时间，并且可以与嵌入 source map 引用的本地路径的工具一起使用，这些工具在服务器上不起作用。这在使用 source maps 进行开发时特别有用。
2. 源内容的 source maps 中的本地文件引用是内联的。这对于 React Native 项目特别有效，这些项目可能会引用数千个您可能不想单独上传的文件。
3. 它会在上传之前非常准确地自动验证 source maps，这可以发现在事件发生之前您不会发现的错误。这是 --validate 其他情况的改进版本。

以下选项可用于更改上传命令的行为：

--dist

• 设置上传文件的分发标识符(distribution identifier)。此标识符用于区分单个版本中的多个同名文件。在 Source Map 故障排除中了解更多信息。
• https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/#verify-artifact-distribution-value-matches-value-configured-in-your-sdk

--no-sourcemap-reference

• 这会阻止自动检测 source map 引用。不建议使用此选项，因为系统会回退到不发出任何引用。 但是，如果您将 sourceMapURL 注释手动添加到 minified 的文件中并且您知道它们比自动检测更正确，则它很有用。

--no-rewrite

• 禁止重写匹配的 source map。 默认情况下，该工具将重写源，以便在可能的情况下将索引映射展平并内联缺失的源。 这从根本上改变了上传过程，使其完全基于 source map 和 minified 文件，并且对于像 react-native 这样的设置会派上用场，这些设置生成 source map，否则这些 source map 不适用于 Sentry。

--strip-prefix / --strip-common-prefix

• 除非指定 --no-rewrite，否则这将从上传的 source map 中的所有源引用中截断前缀。 例如，您可以使用它来删除特定于构建机器的路径。 通用前缀版本将尝试自动猜测通用前缀是什么并自动将其砍掉。这不会修改上传的源路径。 为此，请将 upload 或 upload-sourcemaps 命令指向更精确的目录。

--validate

• 当未启用重写时，这会在上传之前尝试 source map 验证。 它将发现 source map 的各种问题，并在发现任何问题时取消上传。这不是默认设置，因为这会导致误报。

--url-prefix

• 这会在所有文件前面设置一个 URL 前缀。默认为 ~/ 但您可能希望将其设置为完整 URL。 如果您的文件存储在子文件夹中，这也很有用。例如：--url-prefix '~/static/js'

--ext

• 覆盖要上传的文件扩展名列表。默认情况下，处理以下文件扩展名：js、map、jsbundle 和 bundle。该工具将根据文件内容（例如：sources、minified sources 和 source maps）自动检测文件类型并采取适当的行动。对于多个扩展，您需要重复该选项，例如：--ext js --ext map。

--ignore

• 指定一种或多种被忽略文件和文件夹的模式。覆盖忽略文件中指定的模式。有关更多信息，请参阅 --ignore-file。请注意，与 --ignore-file 不同，此参数是相对于指定的路径参数进行解释的。

--ignore-file

• 指定包含要在扫描期间忽略的文件和文件夹模式的文件。忽略模式遵循 gitignore 规则，并相对于忽略文件的位置进行评估。该文件假定在当前工作目录或其任何父目录中。
• https://git-scm.com/docs/gitignore#_pattern_format

一些示例用法：

# Rewrite and upload all sourcemaps in /path/to/sourcemaps
sentry-cli releases files "$VERSION" upload-sourcemaps /path/to/sourcemaps

# Prefix all paths with ~/static/js to match where the sources are hosted online
sentry-cli releases files "$VERSION" upload-sourcemaps /path/to/sourcemaps \
    --url-prefix '~/static/js'

# Remove a common prefix if all source maps are located in a subdirectory
sentry-cli releases files "$VERSION" upload-sourcemaps /path/to/sourcemaps \
    --url-prefix '~/static/js' --strip-common-prefix

# Omit all files specified in .sentryignore
sentry-cli releases files "$VERSION" upload-sourcemaps /path/to/sourcemaps \
    --ignore-file .sentryignore

列出文件

要列出上传的文件，可以使用以下命令：

sentry-cli releases files "$VERSION" list

这将返回该版本的所有上传文件的列表。

删除文件

您还可以删除已上载的文件。按名称或同时按所有文件：

sentry-cli releases files "$VERSION" delete NAME_OF_FILE
sentry-cli releases files "$VERSION" delete --all

创建 Deploys

您还可以将 deploys 与 releases 相关联。要创建 deploy，您首先要创建一个 release，然后为其创建一个 deploy。至少，你应该提供 deploy 去的“environment”（production、staging等）。您可以自由定义：

sentry-cli releases deploys "$VERSION" new -e ENVIRONMENT

或者，您还可以定义 deploy 所用的时间：

start=$(date +%s)
...
now=$(date +%s)
sentry-cli releases deploys "$VERSION" new -e ENVIRONMENT -t $((now-start))

也可以列出 deploys（但不能删除）：

sentry-cli releases deploys "$VERSION" list

调试信息文件

调试信息文件允许 Sentry 提取堆栈跟踪并为大多数编译平台提供有关崩溃报告的更多信息。 sentry-cli 可用于验证和上传调试信息文件。有关更多一般信息，请参阅调试信息文件。

• https://docs.sentry.io/platforms/apple/data-management/debug-files/

权限

sentry-cli 需要使用一组 Permissions & Scopes 对 Auth Token 进行身份验证，以便可以上传调试信息文件。为此，您必须具有 project:releases 或 project:write 作用域。

Source maps 虽然也是调试信息文件，但在 Sentry 中的处理方式不同。有关更多信息，请参阅 sentry-cli 中的 Source Maps。

https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps

检查文件

并非所有调试信息文件都可以被 Sentry 使用。要查看它们是否可用，您可以使用 sentry-cli difutil check 命令：

sentry-cli difutil check mylibrary.so.debug

Debug Info File Check
  Type: elf debug companion
  Contained debug identifiers:
    > 924e148f-3bb7-06a0-74c1-36f42f08b40e (x86_64)
  Contained debug information:
    > symtab, debug
  Usable: yes

这将报告调试信息文件的调试标识符(debug identifiers)以及它是否通过 Sentry 的基本要求。

查找文件

如果您在 Sentry 的 UI 中看到缺少调试信息文件，但您不确定如何找到它们，则可以使用 sentry-cli difutil find 命令来查找它们：

sentry-cli difutil find <identifier>

此外，sentry-cli upload-dif 可以自动搜索文件夹或 ZIP 存档中的文件。

创建 Source Bundle

要在 Sentry UI 的堆栈跟踪中获取内联源上下文，sentry-cli 可以扫描调试文件以获取对源代码文件的引用，在本地文件系统中解析它们并将它们捆绑起来。 生成的源包(source bundle)是一个存档，其中包含特定调试信息文件引用的所有源文件。

这在构建和上传调试信息文件分离时特别有用。 在这种情况下，可以在构建时创建一个源包(source bundle)，并且可以在以后的任何时间点使用 sentry-cli upload-dif 上传。

要创建 source bundle，请对调试信息文件列表使用 difutil bundle-sources 命令：

# on the build machine:
sentry-cli difutil bundle-sources /path/to/files...

# at any later time:
sentry-cli upload-dif --type sourcebundle /path/to/bundles...

要为所有调试信息文件创建多个源包(source bundles)，请分别对每个文件使用该命令。

或者，将 --include-sources 选项添加到 upload-dif 命令，它会在上传过程中即时生成源包(source bundles)。 这要求上传与应用程序构建在同一台机器上执行：

sentry-cli upload-dif --include-sources /path/to/files...

上传文件

使用 sentry-cli upload-dif 命令上传调试信息文件到 Sentry。该命令将递归扫描提供的文件夹或 ZIP 档案。已上传的文件会自动跳过。

我们建议在发布或发布您的应用程序时上传调试信息文件。或者，可以在构建过程中上传文件。 有关更多信息，请参阅调试信息文件。

• https://docs.sentry.io/workflow/debug-files/

您需要指定您正在使用的 organization 和 project，因为调试信息文件适用于 project。 有关这方面的更多信息，请参阅使用 project。

https://docs.sentry.io/product/cli/configuration/#sentry-cli-working-with-projects

可以通过以下方式开始基本的调试文件上传：

sentry-cli upload-dif -o <org> -p <project> /path/to/files...

> Found 2 debug information files
> Prepared debug information files for upload
> Uploaded 2 missing debug information files
> File processing complete:

  PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable)
  PENDING 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion)

上传后，Sentry 分析文件以 symbolicate 未来的事件。如果要将本机崩溃发送到 Sentry 以验证正确操作，请确保调试文件在 Project Settings > Debug Files 中列出。 或者，在 CLI 中指定 --wait，它将阻塞直到服务器端分析完成：

sentry-cli upload-dif -o <org> -p <project> --wait /path/to/files...

> Found 2 debug information files
> Prepared debug information files for upload
> Uploaded 2 missing debug information files
> File processing complete:

      OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 executable)
      OK 1ddb3423-950a-3646-b17b-d4360e6acfc9 (MyApp; x86_64 debug companion)

上传选项

您可以为上传命令提供几个选项：

--wait

等待上传文件的服务器端处理。默认情况下，一旦调试文件上传到 Sentry，upload-dif 就会完成。 在此之后，Sentry 分析文件并使它们可用于 symbolication。 指定 --wait 以确保在将崩溃发送到 Sentry 之前准备好调试文件是有意义的。 这可能会减慢命令的速度，不推荐用于 CI 构建。

--no-unwind

不要扫描堆栈展开信息。为禁用 FPO 的构建指定此标志，或在设备上发生堆栈遍历时指定此标志。 这通常不包括可执行文件和库。如果它们包含调试信息，它们可能仍会被上传。

--no-debug

不要扫描调试信息。这通常会排除调试伴随文件。如果它们包含堆栈展开信息，它们可能仍会被上传。

--include-sources

扫描调试文件以获取对源代码文件的引用。 如果引用的文件在本地文件系统上可用，则将它们捆绑并作为源存档(source archive)上传。这允许 Sentry 解析源上下文(source context)。仅在从与构建相同的机器上传时指定此命令。否则，请使用 difutil bundle-sources 提前生成包。

--derived-data

在派生数据文件夹中搜索 dSYM。 Xcode 将其构建输出存储在此默认位置。

--no-zips

默认情况下，sentry-cli 将打开并搜索 ZIP 存档以查找调试文件。这在从 iTunes Connect 或 CI 环境中的先前构建阶段下载构建时特别有用。如果您的搜索路径包含没有调试文件的大型 ZIP 档案，请使用此开关禁用以加快搜索速度。

--force-foreground

此选项强制在前台进行上传。这仅影响从 Xcode 构建步骤调用的上传。默认情况下，上传过程将在从 Xcode 启动时分离并在后台完成。如果您需要调试上传过程，强制上传在前台运行可能会很有用。

--info-plist

覆盖 Info.plist 的搜索路径，如果它位于非标准位置，则很有用。

--no-reprocessing

此参数可防止 Sentry 立即触发重新处理。在极少数情况下，您希望分批上传文件，并且希望确保 Sentry 在上传某些可选 dSYM 之前不会开始重新处理，这会很有用。 但请注意，有人仍然可以在此期间从 UI 触发重新处理。

--symbol-maps

使用 BCSymbolMaps 解析 iTunes Connect 版本中的隐藏 symbols。如果在 AppStore 中发布应用程序时未将 symbols 上传到 Apple，则需要使用此 symbols 来表示崩溃。

Symbol Maps

如果您对 Apple 隐藏调试符号，则调试文件将不会包含许多有用的符号。在这种情况下， sentry-cli 上传会警告您它需要 BCSymbolMaps：

sentry-cli upload-dif ...
> Found 34 debug information files
> Warning: Found 10 symbol files with hidden symbols (need BCSymbolMaps)

在这种情况下，您需要与您的文件匹配的 BCSymbolMaps。通常，这些是由 Xcode 构建过程生成的。 提供 --symbol-maps 参数并将其指向包含符号映射(symbol maps)的文件夹：

sentry-cli upload-dif --symbol-maps path/to/symbolmaps path/to/debug/symbols

Breakpad 文件

与本机调试文件相比，Breakpad symbols 会丢弃许多处理小型转储不需要的信息。 最值得注意的是，未声明内联函数，因此 Sentry 无法在堆栈跟踪中显示内联帧。

如果可能，请上传本机调试文件，例如 dSYM、PDB 或 ELF 文件，而不是 Breakpad symbols。

ProGuard Mapping 上传

sentry-cli 可用于将 ProGuard 文件上传到 Sentry；然而，在大多数情况下，您会使用 Gradle 插件来做到这一点。但是，在某些情况下，您需要手动上传 ProGuard 文件（例如，当您仅发布正在创建的部分构建版本时）。

• https://github.com/getsentry/sentry-android-gradle-plugin

您需要指定您正在使用的 organization 和 project，因为 ProGuard 文件适用于项目。 有关这方面的更多信息，请参阅使用项目。

https://docs.sentry.io/product/cli/configuration/#sentry-cli-working-with-projects

upload-proguard 命令用于上传 ProGuard 文件。它获取一个或多个 ProGuard 映射文件(mapping files)的路径，并将它们上传到 Sentry。 例子：

sentry-cli upload-proguard \
    app/build/outputs/mapping/{BuildVariant}/mapping.txt

由于 Android SDK 需要知道映射文件的 UUID，因此您需要将其嵌入到 sentry-debug-meta.properties 文件中。如果您提供自动完成的 --write-properties：

sentry-cli upload-proguard \
    --write-properties app/build/generated/assets/sentry/{BuildVariant}/sentry-debug-meta.properties \
    app/build/outputs/mapping/{BuildVariant}/mapping.txt

上传后，Sentry 对未来的事件进行反混淆处理。如果您想向 Sentry 发送混淆崩溃以验证正确的操作，请确保 ProGuard 映射文件在 Project Settings > ProGuard 中列出。

上传选项

--no-reprocessing

• 此参数可防止 Sentry 立即触发重新处理。 在极少数情况下，您希望分批上传文件，并且希望确保 Sentry 在上传某些可选 dSYM 之前不会开始重新处理，这会很有用。 但请注意，有人仍然可以在此期间从 UI 触发重新处理。

--no-upload

• 禁用实际上传。这会运行处理的所有步骤，但不会触发上传（这也会自动禁用重新处理。如果您只想验证映射文件并将 ProGuard UUID 写入属性文件，这将非常有用。

--require-one

至少需要上传一个文件，否则命令会出错。

发送事件

sentry-cli 工具也可用于发送事件。如果你想使用它，你需要导出 SENTRY_DSN 环境变量并将其指向你的一个项目的 DSN：

export SENTRY_DSN='https://examplePublicKey@o0.ingest.sentry.io/0'

完成后，您可以开始使用 sentry-cli send-event 命令。

基本事件

对于基本的消息事件，您只需要提供 --message 或 -m 参数即可发送消息：

sentry-cli send-event -m "Hello from Sentry"

这将向 sentry 发送一条消息并将其记录为事件。与该事件一起，它会发送有关您正在运行 sentry-cli 的机器的基本信息。您可以多次提供 -m 以发送多行：

sentry-cli send-event -m "Hello from Sentry" -m "This is more text"

带参数的事件

此外，您可以在消息中使用 %s 作为占位符并使用 -a 参数填充它。 这有助于查看它们，因为所有消息将自动组合在一起：

sentry-cli send-event -m "Hello %s!" -a "Joe"
sentry-cli send-event -m "Hello %s!" -a "Peter"

发送面包屑

您还可以将日志文件传递给 send-event 命令，该命令将被解析并作为面包屑发送。将发送最后 100 项：

sentry-cli send-event -m “task failed” –-logfile error.log

日志文件可以是各种格式。如果你想自己创建一个，你可以按照以下方式做一些事情：

echo "$(date +%c) This is a log record" >> output.log
echo "$(date +%c) This is another record" >> output.log
sentry-cli send-event -m "Demo Event" --logfile output.log
rm output.log

Extra 数据

Extra 的数据可以通过 -e 参数作为 KEY:VALUE 附加。例如，您可以像这样发送一些键值对：

sentry-cli send-event -m "a failure" -e task:create-user -e object:42

同样，可以使用 -t 使用相同的格式发送 tag：

sentry-cli send-event -m "a failure" -t task:create-user

指定 Release

可以使用 --release 参数发送 release。如果您在 git repository 中使用 sentry-cli，则会自动选择默认 release。

Bash Hook

对于 bash 脚本，您还可以使用 sentry-cli bash hook 启用自动错误发送。这将启用 set -e 并将为未处理的错误(unhandled errors)发送 sentry 事件。

这样做的限制是：

• sentry-cli 只有在启用 set -e 时才有效（默认情况下它会为您启用）。
• sentry-cli 注册一个 EXIT 和 ERR trap。

用法：

#!/bin/bash
export SENTRY_DSN='https://examplePublicKey@o0.ingest.sentry.io/0'
eval "$(sentry-cli bash-hook)"
# rest of the script goes here

或者，您可以使用其他机制（如 .sentryclirc 文件）来配置 DSN。

公众号：黑客下午茶