T O P

[资源分享]     Sentry-CLI 使用详解(2021 Sentry v21.8.x)

  • By - 楼主

  • 2021-09-08 14:02:31
  • 内容源于:https://docs.sentry.io/platforms/javascript/guides/vue/

    系列

    脑图

    公众号:黑客下午茶
    

    安装

    根据您的平台,有不同的方法可用于安装 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

    公众号:黑客下午茶
    

    本帖子中包含资源

    您需要 登录 才可以下载,没有帐号?立即注册