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

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

系列

脑图

公众号:黑客下午茶

安装

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

手动下载

您可以在 GitHub release 页面上找到 release 列表。
我们提供适用于 LinuxOS XWindows 的可执行文件。 这是一个单独的文件下载,在收到文件后,您可以将其重命名为 sentry-clisentry-cli.exe 以使用它。

自动安装

如果你使用的是 OS XLinux,你可以使用自动下载器,它会为你获取最新的发行版本并安装它:

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

如果您想使用 sudonpm 系统范围内安装它,您需要将 --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-cliDocker 镜像。建议使用 latest tag,但您也可以固定到特定版本。默认情况下,该命令在 /work 目录中运行。 挂载相关的项目文件夹并在那里构建输出以允许 sentry-cli 扫描资源:

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

更新和卸载

您可以使用 sentry-cli updatesentry-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):

  • 用于连接 sentryDSN

SENTRY_URL (defaults.url):

  • 用于连接 sentryURL。默认为 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 设置,用于控制 SDKHTTP keepalives 方面的行为。默认值为 true,但可以将其设置为 false 以禁用 keepalive 支持。

http_proxy (http.proxy_url):

  • 应用于 HTTP proxyURL。标准的 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)。默认为 35MB100MB(取决于 sentry-cli 的版本),适用于 sentry.io 但如果您使用不同的 sentry 服务器,您可能需要在必要时更改此限制。

SENTRY_NO_PROGRESS_BAR:

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

SENTRY_DISABLE_UPDATE_CHECK(update.disable_check):

  • 如果设置为 true,则禁用 sentry-cli 中的自动更新检查。这是在 1.17 中引入的。 之前的版本不包括更新检查。目前还没有为基于 npmsentry-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_ORGSENTRY_PROJECT),您可以导出它们:

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

属性文件

此外,sentry-cli 支持从 .properties 文件加载配置值(在 Java 环境中很常见)。 您可以通过将路径导出到 SENTRY_PROPERTIES 环境变量中的属性文件来指示 sentry-cli 从那里加载配置文件。对于我们的一些客户端集成,如 JavaReact 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 名称在整个组织中唯一。例如,如果您有共享版本号的 projectAprojectB,您可以分别将版本命名为 projectA-1.0projectB-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-numberpackage-name@version-number+build-number。不要使用 VERSION_NUMBER (BUILD_NUMBER),因为括号是用于显示的(foo@1.0+2 变成 1.0 (2)),所以调用它们会导致错误。
  • 如果您使用 DVCS,我们建议使用标识哈希(例如:commit SHAda39a3ee5e6b4b0d3255bfef95601890afd80709)。您可以让 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。 如果要引用 tagreference(如 HEAD),则需要检出存储库并可以从调用 sentry-cli 的路径访问该存储库。

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

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

或者:没有 Repository Integration

您仍然可以使用 --auto 标志,CLI 将自动使用您 local repogit tree,并将先前 release 的提交和当前的主要提交之间的提交与该 release 相关联。如果这是第一个 releaseSentry 将使用最新的 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 artifactsentry-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 的文件,它是一个 minifiedJavaScript 文件和一个名为 foo.min.mapsource 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 mapminified 文件,并且对于像 react-native 这样的设置会派上用场,这些设置生成 source map,否则这些 source map 不适用于 Sentry

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

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

--validate

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

--url-prefix

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

--ext

  • 覆盖要上传的文件扩展名列表。默认情况下,处理以下文件扩展名:jsmapjsbundlebundle。该工具将根据文件内容(例如:sourcesminified sourcessource 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

您还可以将 deploysreleases 相关联。要创建 deploy,您首先要创建一个 release,然后为其创建一个 deploy。至少,你应该提供 deploy 去的“environment”(productionstaging等)。您可以自由定义:

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 & ScopesAuth Token 进行身份验证,以便可以上传调试信息文件。为此,您必须具有 project:releasesproject: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 的基本要求。

查找文件

如果您在 SentryUI 中看到缺少调试信息文件,但您不确定如何找到它们,则可以使用 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

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

--no-unwind

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

--no-debug

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

--include-sources

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

--derived-data

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

--no-zips

默认情况下,sentry-cli 将打开并搜索 ZIP 存档以查找调试文件。这在从 iTunes ConnectCI 环境中的先前构建阶段下载构建时特别有用。如果您的搜索路径包含没有调试文件的大型 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 无法在堆栈跟踪中显示内联帧。

如果可能,请上传本机调试文件,例如 dSYMPDBELF 文件,而不是 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 注册一个 EXITERR 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

公众号:黑客下午茶
posted @ 2021-09-08 13:00  为少  阅读(4084)  评论(0编辑  收藏  举报