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

Sentry-CLI 使用详解(2021 Sentry v21.8.x)
内容源于：https://docs.sentry.io/product/cli/

系列
脑图
```
公众号：黑客下午茶
```
安装

根据您的平台，有不同的方法可用于安装 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。
```
公众号：黑客下午茶
```
相关阅读:
Python之路【第二篇】：Python基础（8）-Tuple元组
 Python之路【第二篇】：Python基础（7）-列表
 Python之路【第一篇】：Python基础（6）
Python之路【第一篇】：Python基础（5）
Python之路【第一篇】：Python基础（4）
Python之路【第一篇】：Python基础（3）
Python之路【第一篇】：Python基础（2）
Python之路【第一篇】：Python基础（1）
SQL Server优化50法
 四层和七层负载均衡的区别
原文地址：https://www.cnblogs.com/hacker-linner/p/15242276.html

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

系列

脑图

安装

手动下载

自动安装

通过 NPM 安装

从自定义源下载

通过 Homebrew 安装

通过 Scoop 安装

Docker 镜像

更新和卸载

配置和认证

使用自动选项

手动验证

配置文件

配置值

验证配置

使用 Project

配置默认值

环境变量

属性文件

显式选项

Release 管理

创建 Release

完成 Release

提交 Integration

或者：没有 Repository Integration

处理丢失的提交

管理 Release Artifact

上传文件

上传 Source Maps

列出文件

删除文件

创建 Deploys

调试信息文件

权限

检查文件

查找文件

创建 Source Bundle

上传文件

上传选项

Symbol Maps

Breakpad 文件

ProGuard Mapping 上传

上传选项

发送事件

基本事件

带参数的事件

发送面包屑

Extra 数据

指定 Release

Bash Hook