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镜像。建议使用
latesttag,但您也可以固定到特定版本。默认情况下,该命令在
/work目录中运行。 挂载相关的项目文件夹并在那里构建输出以允许
sentry-cli扫描资源:
docker pull getsentry/sentry-cli docker run --rm -v $(pwd):/work getsentry/sentry-cli --help
更新和卸载
您可以使用
sentry-cli update和
sentry-cli uninstall更新或卸载
sentryCLI。 这些命令在某些情况下可能不可用(例如,如果您使用
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</small>
创建 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,例如,它将发送一个很长的
Sourcemapheader 来关联它们。这适用于系统可以检测到关系的文件。
默认情况下,
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</small>
--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</small>
一些示例用法:
# 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</small>
检查文件
并非所有调试信息文件都可以被
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</small>
可以通过以下方式开始基本的调试文件上传:
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</small>
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。
公众号:黑客下午茶
- 详解如何使用Node.js编写命令工具――以vue-cli为例
- 详解windows下vue-cli及webpack 构建网站(四) 路由vue-router的使用
- 详解windows下vue-cli及webpack 构建网站(三)使用组件
- 在vue-cli中引入lodash.js并使用详解
- 详解vue2.0 使用动态组件实现 Tab 标签页切换效果(vue-cli)
- 详解vue-cli 本地开发mock数据使用方法
- 使用vue脚手架(vue-cli)搭建一个项目详解
- 详解在vue-cli中使用路由
- 详解使用vue-cli脚手架初始化Vue项目下的项目结构
- 详解如何在vue-cli中使用vuex
- 详解如何使用vue-cli脚手架搭建Vue.js项目
- Vue2 Vue-cli中使用Typescript的配置详解
- 详解如何使用 vue-cli 开发多页应用
- 详解vue2.0 使用动态组件实现 Tab 标签页切换效果(vue-cli)
- vue-cli项目中使用公用的提示弹层tips或加载loading组件实例详解
- 详解vue-cli项目中怎么使用mock数据
- 详解在vue-cli中使用graphql即vue-apollo的用法
- 详解vue-cli3使用
- 使用vue-cli脚手架创建的项目结构详解
- 详解Vue-cli3.X使用px2rem遇到的问题