您的位置:首页 > 其它

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

2021-09-08 13:00 579 查看

内容源于:https://docs.sentry.io/product/cli/

系列

脑图

公众号:黑客下午茶

安装

根据您的平台,有不同的方法可用于安装

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</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
,例如,它将发送一个很长的
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

--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

一些示例用法:

# 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

公众号:黑客下午茶
内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签: