Sentry-CLI 使用详解(2021 Sentry v21.8.x)
内容源于:https://docs.sentry.io/product/cli/
系列
- 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
以使用它。
自动安装
如果你使用的是 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>"
。
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
:
> 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
相关联。
有两种模式可以使用它。一种是全自动模式。如果您从 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”
电子邮件,请查看我们的帮助中心文章。
处理丢失的提交
在某些情况下,您的存储库可能缺少先前在 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
。
要管理 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
:
- 它将索引的
source maps
展平。这样做的优点是它有时可以压缩source maps
,这可能会改善您的处理时间,并且可以与嵌入source map
引用的本地路径的工具一起使用,这些工具在服务器上不起作用。这在使用source maps
进行开发时特别有用。 - 源内容的
source maps
中的本地文件引用是内联的。这对于React Native
项目特别有效,这些项目可能会引用数千个您可能不想单独上传的文件。 - 它会在上传之前非常准确地自动验证
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
可用于验证和上传调试信息文件。有关更多一般信息,请参阅调试信息文件。
权限
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
档案。已上传的文件会自动跳过。
我们建议在发布或发布您的应用程序时上传调试信息文件。或者,可以在构建过程中上传文件。 有关更多信息,请参阅调试信息文件。
您需要指定您正在使用的 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
文件(例如,当您仅发布正在创建的部分构建版本时)。
您需要指定您正在使用的 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
。
公众号:黑客下午茶