[[422640]]

本文轉(zhuǎn)載自微信公眾號(hào)「黑客下午茶」，作者為少 。轉(zhuǎn)載本文請(qǐng)聯(lián)系黑客下午茶公眾號(hào)。

腦圖

安裝

根據(jù)您的平臺(tái)，有不同的方法可用于安裝 sentry-cli。

手動(dòng)下載

您可以在 GitHub release 頁(yè)面上找到 release 列表。我們提供適用于 Linux、OS X 和 Windows 的可執(zhí)行文件。這是一個(gè)單獨(dú)的文件下載，在收到文件后，您可以將其重命名為 sentry-cli 或 sentry-cli.exe 以使用它。

• https://github.com/getsentry/sentry-cli/releases/

自動(dòng)安裝

如果你使用的是 OS X 或 Linux，你可以使用自動(dòng)下載器，它會(huì)為你獲取最新的發(fā)行版本并安裝它：

curl -sL https://sentry.io/get-cli/ | bash 

這將自動(dòng)為您的操作系統(tǒng)下載正確版本的 sentry-cli 并安裝它。如果有必要，它會(huì)提示您輸入 sudo 的管理員密碼。

要驗(yàn)證它是否正確安裝，您可以調(diào)出幫助：

sentry-cli --help 

通過(guò) NPM 安裝

對(duì)于特殊用例，還可以選擇通過(guò) npm 安裝 sentry-cli。例如，這對(duì)于構(gòu)建服務(wù)器很有用。該包名為 @sentry/cli，在安裝后它將下載適當(dāng)?shù)陌l(fā)行版二進(jìn)制文件：

npm install @sentry/cli 

然后您可以在 .bin 文件夾中找到它：

./node_modules/.bin/sentry-cli --help 

如果您想使用 sudo 在 npm 系統(tǒng)范圍內(nèi)安裝它，您需要將 --unsafe-perm 傳遞給它：

sudo npm install -g @sentry/cli --unsafe-perm 

但是，不建議進(jìn)行此安裝。

從自定義源下載

默認(rèn)情況下，這個(gè)包會(huì)從 Fastly 管理的 CDN 下載 sentry-cli。要使用自定義 CDN，請(qǐng)?jiān)O(shè)置 npm config 屬性 sentrycli_cdnurl。下載器將附加 "//sentry-cli-"。

• https://www.fastly.com/

npm install @sentry/cli --sentrycli_cdnurl=https://mymirror.local/path 

或者將屬性添加到您的 .npmrc 文件中 (https://docs.npmjs.com/files/npmrc)

sentrycli_cdnurl=https://mymirror.local/path 

另一種選擇是使用環(huán)境變量 SENTRYCLI_CDNURL。

SENTRYCLI_CDNURL=https://mymirror.local/path npm install @sentry/cli 

通過(guò) Homebrew 安裝

如果您使用的是 OS X，則可以通過(guò) homebrew 安裝 sentry-cli：

brew install getsentry/tools/sentry-cli 

通過(guò) Scoop 安裝

如果您使用的是 Windows，您可以通過(guò) Scoop 安裝 sentry-cli：

• https://scoop.sh/

> scoop install sentry-cli 

Docker 鏡像

對(duì)于不受支持的發(fā)行版和 CI 系統(tǒng)，我們提供了一個(gè)預(yù)裝了 sentry-cli 的 Docker 鏡像。建議使用 latest tag，但您也可以固定到特定版本。默認(rèn)情況下，該命令在 /work 目錄中運(yùn)行。掛載相關(guān)的項(xiàng)目文件夾并在那里構(gòu)建輸出以允許 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)。

配置和認(rèn)證

對(duì)于大多數(shù)功能，您需要使用 Sentry 進(jìn)行身份驗(yàn)證。設(shè)置可以使用 sentry-cli 自動(dòng)完成，也可以手動(dòng)完成。無(wú)論哪種方式，您都需要一個(gè)至少具有以下作用域(scope)的令牌：

• project:read
• project:releases
• org:read

使用自動(dòng)選項(xiàng)

sentry-cli login 

這將為您提供訪問(wèn)身份驗(yàn)證令牌用戶(auth token user)設(shè)置的選項(xiàng)，您可以在其中創(chuàng)建新的 auth token，或簡(jiǎn)單地復(fù)制現(xiàn)有 token。當(dāng)您返回 CLI 時(shí)，您將粘貼您的 token，它會(huì)自動(dòng)添加到 ~/.sentryclirc 中。

默認(rèn)情況下，sentry-cli 將連接到 sentry.io，但對(duì)于自托管，您也可以在其他地方登錄：

sentry-cli --url https://myserver.invalid/ login 

手動(dòng)驗(yàn)證

訪問(wèn)您的身份驗(yàn)證令牌用戶(auth token user)設(shè)置頁(yè)面并創(chuàng)建或復(fù)制現(xiàn)有 token。然后：

• 添加它到 ~/.sentryclirc：

[auth] 
token=your-auth-token 

• 將其導(dǎo)出為環(huán)境變量：

export SENTRY_AUTH_TOKEN=your-auth-token 

• 調(diào)用 sentry-cli 時(shí)將其作為參數(shù)傳遞：

sentry-cli --auth-token your-auth-token 

配置文件

sentry-cli 工具可以使用名為 .sentryclirc 的配置文件以及環(huán)境變量和 .env 文件進(jìn)行配置。從當(dāng)前路徑向上查找配置文件，并且始終加載 ~/.sentryclirc 中的默認(rèn)值。您還可以從命令行參數(shù)覆蓋這些設(shè)置。

配置文件使用標(biāo)準(zhǔn) INI 語(yǔ)法。

默認(rèn) sentry-cli 將連接到 sentry.io。對(duì)于本地，您可以導(dǎo)出 SENTRY_URL 環(huán)境變量并將其指向您的安裝：

export SENTRY_URL=https://mysentry.invalid/ 

或者，您可以將它添加到您的 ~/.sentryclirc 配置中。這也是 login 命令的作用：

[defaults] 
url = https://mysentry.invalid/ 

默認(rèn) sentry-cli 加載 .env 文件。在 sentry-cli 1.24 及更新版本上，您可以通過(guò)導(dǎo)出環(huán)境變量 SENTRY_LOAD_DOTENV=0 來(lái)禁用此功能。

配置值

可以使用以下設(shè)置(首先是環(huán)境變量，括號(hào)中的值是 config 文件中的配置 key)：

SENTRY_AUTH_TOKEN (auth.token):

• 用于與 Sentry 的所有通信的身份驗(yàn)證令牌(authentication token)。

SENTRY_API_KEY (auth.api_key):

• 用于身份驗(yàn)證的舊 API key(如果您有的話)。

SENTRY_DSN (auth.dsn):

• 用于連接 sentry 的 DSN。

SENTRY_URL (defaults.url):

• 用于連接 sentry 的 URL。默認(rèn)為 https://sentry.io/。

SENTRY_ORG (defaults.org):

• 用于命令的 organization(組織) 的 slug。

SENTRY_PROJECT (defaults.project):

• 用于命令的 project(項(xiàng)目) 的 slug。

SENTRY_VCS_REMOTE (defaults.vcs_remote):

• 版本控制系統(tǒng)中 remote 的名稱。這默認(rèn)為 origin。

SENTRY_PIPELINE (defaults.pipeline):

• 要附加到 User-Agent header 的環(huán)境(environment)名稱。

CUSTOM_HEADER (defaults.custom_header):

• 將以 key:value 格式添加到每個(gè)傳出請(qǐng)求的 header。

(http.keepalive):

• 僅 ini 設(shè)置，用于控制 SDK 在 HTTP keepalives 方面的行為。默認(rèn)值為 true，但可以將其設(shè)置為 false 以禁用 keepalive 支持。

http_proxy (http.proxy_url):

• 應(yīng)用于 HTTP proxy 的 URL。標(biāo)準(zhǔn)的 http_proxy 環(huán)境變量也受到尊重。請(qǐng)注意，它是小寫的。

(http.proxy_username):

• 僅 ini 設(shè)置，設(shè)置代理用戶名(proxy username)以防需要代理身份驗(yàn)證(proxy authentication)。

(http.proxy_password):

• 僅 ini設(shè)置，在需要代理身份驗(yàn)證時(shí)設(shè)置代理密碼(proxy password)。

(http.verify_ssl):

• 這可用于在設(shè)置為 false 時(shí)禁用 SSL 驗(yàn)證。除非您在本地使用已知的自簽名服務(wù)器，否則您永遠(yuǎn)不應(yīng)該這樣做。

(http.check_ssl_revoke):

如果將其設(shè)置為 false，則在 Windows 上禁用 SSL 吊銷(revocation)檢查。這在使用未正確實(shí)施吊銷(revocation)檢查的企業(yè) SSL MITM proxy 時(shí)非常有用。除非絕對(duì)必要，否則不要使用它。

SENTRY_HTTP_MAX_RETRIES(http.max_retries):

設(shè)置上傳操作的最大重試次數(shù)(例如，上傳 release 文件和調(diào)試符號(hào)symbols)。默認(rèn)值為 5。

(ui.show_notifications):

• 如果將其設(shè)置為 false，則會(huì)禁用某些操作系統(tǒng)通知。這目前主要影響 xcode 構(gòu)建，它不會(huì)顯示后臺(tái)構(gòu)建的通知。

SENTRY_LOG_LEVEL (log.level):

• 配置 SDK 的日志級(jí)別。默認(rèn)為 warn。如果您想查看庫(kù)正在做什么，您可以將其設(shè)置為 info， 這將輸出更多信息，這可能有助于調(diào)試一些權(quán)限(permissions)問(wèn)題。

(dsym.max_upload_size):

• 將調(diào)試符號(hào)(debug symbols)的最大上傳大小(以字節(jié)為單位)設(shè)置為一批(one batch)。默認(rèn)為 35MB 或 100MB(取決于 sentry-cli 的版本)，適用于 sentry.io 但如果您使用不同的 sentry 服務(wù)器，您可能需要在必要時(shí)更改此限制。

SENTRY_NO_PROGRESS_BAR:

• 如果設(shè)置為 1，則 sentry-cli 不會(huì)顯示任何操作的進(jìn)度條。

SENTRY_DISABLE_UPDATE_CHECK(update.disable_check):

• 如果設(shè)置為 true，則禁用 sentry-cli 中的自動(dòng)更新檢查。這是在 1.17 中引入的。之前的版本不包括更新檢查。目前還沒有為基于 npm 的 sentry-cli 安裝啟用更新檢查。

DEVICE_FAMILY (device.family):

• 向 Sentry 報(bào)告的設(shè)備系列(Device family)值。

DEVICE_MODEL (device.model):

• 向 Sentry 報(bào)告的設(shè)備型號(hào)(Device model)值。

驗(yàn)證配置

為了確保一切正常，您可以運(yùn)行 sentry-cli info 并且它應(yīng)該打印出有關(guān)您連接的 Sentry 安裝的一些基本信息以及一些身份驗(yàn)證信息。

使用 Project

許多命令要求您指定要使用的組織(organization)和項(xiàng)目(project)。您可以通過(guò)多種方式指定此項(xiàng)。

配置默認(rèn)值

如果您始終使用相同的項(xiàng)目，則可以在 .sentryclirc 文件中進(jìn)行設(shè)置：

[defaults] 
project=my-project 
org=my-org 

環(huán)境變量

您還可以在環(huán)境變量中設(shè)置這些默認(rèn)值。有兩個(gè)環(huán)境變量可以控制它(SENTRY_ORG 和 SENTRY_PROJECT)，您可以導(dǎo)出它們：

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

屬性文件

此外，sentry-cli 支持從 .properties 文件加載配置值(在 Java 環(huán)境中很常見)。您可以通過(guò)將路徑導(dǎo)出到 SENTRY_PROPERTIES 環(huán)境變量中的屬性文件來(lái)指示 sentry-cli 從那里加載配置文件。對(duì)于我們的一些客戶端集成，如 Java 和 React Native，這通常是自動(dòng)完成的。

在屬性文件中，您只需使用點(diǎn)符號(hào)來(lái)設(shè)置值。例子：

defaults.url=https://mysentry.invalid/ 

然后指示 sentry-cli 使用該文件，請(qǐng)使用以下命令：

export SENTRY_PROPERTIES=/path/to/sentry.properties 
 
sentry-cli ... 

顯式選項(xiàng)

最后，您還可以向正在執(zhí)行的命令明確提供這些值。對(duì)于組織(organization)，這些參數(shù)始終稱為 --org 或 -o，而對(duì)于項(xiàng)目(project)則稱為 --project 或 -p。

請(qǐng)注意，它們并不總是使用相同的命令。例如，如果您正在管理 release(在整個(gè)組織中共享)，您通常將 organization 提供給 releases 命令，但將 project 提供給它的子命令：

sentry-cli releases -o my-org new -p my-project 1.0 

有關(guān)更多信息，請(qǐng)使用 help 命令，該命令將顯示所有參數(shù)的文檔。

Release 管理

sentry-cli 工具可用于 Sentry 上的 release 管理。它允許您創(chuàng)建、編輯和刪除 release 以及為它們上傳 release artifact。請(qǐng)注意，每個(gè)組織的 release 都是 global 的。如果您希望將不同項(xiàng)目中的 release 視為單獨(dú)的實(shí)體，請(qǐng)使 release 名稱在整個(gè)組織中唯一。例如，如果您有共享版本號(hào)的 projectA 和 projectB，您可以分別將版本命名為 projectA-1.0 和 projectB-1.0。

由于 release 用于 project，因此您需要指定您正在使用的 organization 和 project。有關(guān)這方面的更多信息，請(qǐng)參閱使用 project。 
 
https://docs.sentry.io/product/cli/configuration/#sentry-cli-working-with-projects 

創(chuàng)建 Release

Release 是使用 sentry-clireleases new 命令創(chuàng)建的。它至少需要一個(gè)唯一標(biāo)識(shí)版本的版本標(biāo)識(shí)符(version identifier)。有一些限制 —— release 名稱不能：

• 包含換行符、制表符、正斜杠 (/) 或反斜杠 (\)
• 是(全部)句號(hào) (.)、雙句號(hào) (..) 或空格 ( )
• 超過(guò) 200 個(gè)字符

該值可以是任意的，但對(duì)于某些平臺(tái)，存在以下建議：

對(duì)于移動(dòng)設(shè)備，使用 package-name@version-number 或 package-name@version-number+build-number。不要使用 VERSION_NUMBER (BUILD_NUMBER)，因?yàn)槔ㄌ?hào)是用于顯示的(foo@1.0+2 變成 1.0 (2))，所以調(diào)用它們會(huì)導(dǎo)致錯(cuò)誤。

如果您使用 DVCS，我們建議使用標(biāo)識(shí)哈希(例如：commit SHA，da39a3ee5e6b4b0d3255bfef95601890afd80709)。您可以讓 sentry-cli 自動(dòng)為支持的版本控制系統(tǒng)確定此哈希，并使用 sentry-cli releases propose-version(建議版本)。

如果您標(biāo)記 release，我們建議使用帶有產(chǎn)品或包名稱前綴的 release tag (例如，my-project-name@2.3.12)。

Release 也可以由不同的系統(tǒng)自動(dòng)創(chuàng)建。例如，在上傳 source map 時(shí)，會(huì)自動(dòng)創(chuàng)建一個(gè) release。同樣，當(dāng) release 事件發(fā)生時(shí)，某些 client 會(huì)創(chuàng)建 release。

完成 Release

默認(rèn)情況下，一個(gè) release 創(chuàng)建為 “unreleased”。完成 release 意味著我們?cè)?release 記錄上填寫第二個(gè)時(shí)間戳，在 UI 中對(duì) release 進(jìn)行排序時(shí)，它的優(yōu)先級(jí)高于 date_created。這也會(huì)影響 resolving issues 的“下一個(gè)版本(the next release)”，如果您使用 --auto，將哪個(gè)版本release用作關(guān)聯(lián)提交的基礎(chǔ)，并在活動(dòng)流Activity stream中創(chuàng)建一個(gè)條目。

這可以通過(guò)將 --finalize 傳遞給 new 命令來(lái)更改，該命令將立即完成 release，或者您可以稍后單獨(dú)調(diào)用 sentry-cli releases finalize VERSION。如果您將 release 作為構(gòu)建過(guò)程的一部分進(jìn)行管理，則后者很有用，例如：

#!/bin/sh 
sentry-cli releases new "$VERSION" 
# do your build steps here 
# once you are done, finalize 
sentry-cli releases finalize "$VERSION" 

您還可以選擇在 release 上線時(shí)(當(dāng)您部署到您的機(jī)器、在 App Store 中啟用等)時(shí)完成 release。

如果您正在使用 git，您可以要求 Sentry 確定 $VERSION：

#!/bin/sh 
VERSION=`sentry-cli releases propose-version` 

提交 Integration

如果您在 Sentry 組織中配置了存儲(chǔ)庫(kù)，您可以將提交與您的 release 相關(guān)聯(lián)。

• https://docs.sentry.io/product/releases/setup/release-automation/

有兩種模式可以使用它。一種是全自動(dòng)模式。如果您從 git repository 部署并且 sentry-cli 可以從當(dāng)前工作目錄中發(fā)現(xiàn) git repository，您可以使用 --auto 標(biāo)志設(shè)置提交：

sentry-cli releases set-commits "$VERSION" --auto 

如果您在無(wú)法訪問(wèn) git repository 的情況下進(jìn)行部署，則可以改為手動(dòng)指定提交。為此，請(qǐng)將 --commit 參數(shù)以 REPO_NAME@REVISION 格式傳遞給 set-commits 命令。

sentry-cli releases set-commits "$VERSION" --commit "my-repo@deadbeef" 

要查看組織可使用哪些存儲(chǔ)庫(kù)，您可以運(yùn)行 sentry-cli repos list，它將返回已配置存儲(chǔ)庫(kù)的列表。

請(qǐng)注意，您需要參考使用實(shí)際完整 commit SHA 所需的 release。如果要引用 tag 或 reference(如 HEAD)，則需要檢出存儲(chǔ)庫(kù)并可以從調(diào)用 sentry-cli 的路徑訪問(wèn)該存儲(chǔ)庫(kù)。

如果您還想設(shè)置以前的提交而不是讓服務(wù)器使用以前的 release 作為基點(diǎn)，您可以通過(guò)設(shè)置提交范圍(commit range)來(lái)做到這一點(diǎn)：

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

或者：沒有 Repository Integration

您仍然可以使用 --auto 標(biāo)志，CLI 將自動(dòng)使用您 local repo 的 git tree，并將先前 release 的提交和當(dāng)前的主要提交之間的提交與該 release 相關(guān)聯(lián)。如果這是第一個(gè) release，Sentry 將使用最新的 20 個(gè)提交。此行為可使用 --initial-depth 標(biāo)志進(jìn)行配置。

默認(rèn)情況下，您可以使用 --local 標(biāo)志啟用此行為。

sentry-cli releases set-commits "$VERSION" --local 

如果您收到“Unable to Fetch Commits”電子郵件，請(qǐng)查看我們的幫助中心文章。

• https://help.sentry.io/product-features/integrations/why-am-i-receiving-the-email-unable-to-fetch-commits/

處理丟失的提交

在某些情況下，您的存儲(chǔ)庫(kù)可能缺少先前在 release 中使用的提交。每當(dāng)您修改有問(wèn)題的提交時(shí)，就會(huì)發(fā)生這種情況，例如，修改它、重新設(shè)置基數(shù)(rebasing)或?qū)⒍鄠€(gè)提交壓縮在一起。在這種情況下，Sentry CLI 將無(wú)法找到它，并且會(huì)拋出無(wú)法找到提交的錯(cuò)誤。

發(fā)生這種情況時(shí)，您可以傳遞一個(gè)額外的 --ignore-missing 標(biāo)志。這將允許命令回退到默認(rèn)行為，即創(chuàng)建具有指定提交次數(shù)的 release(請(qǐng)參閱上面的部分)。

sentry-cli releases set-commits "$VERSION" --auto --ignore-missing 

管理 Release Artifact

當(dāng)您使用 JavaScript 和其他平臺(tái)時(shí)，您可以將 release artifact 上傳到 Sentry，然后在處理過(guò)程中考慮這些工件。最常見的 release artifact 是 sentry-cli 有特定支持的 source maps。

• https://docs.sentry.io/clients/javascript/sourcemaps/

要管理 release artifact，可以使用 sentry-cli releases files 命令，它本身提供了各種子命令。

上傳文件

最常見的用例是上傳文件。對(duì)于通用上傳，可以使用 sentry-cli releases files VERSION upload 命令。然而，由于大多數(shù) release artifact 都與 JavaScript source map 相關(guān)，因此我們有一個(gè)上傳 Source Maps 方便的方法。

上傳的文件通常以完整的(例如：http://example.com/foo.js)或截?cái)嗟?URL(例如：~/foo.js)命名。

Release artifact 僅在事件處理時(shí)考慮。因此，雖然可以在事后修改 release artifact ，但它們只會(huì)被考慮用于該 release 的未來(lái)事件。

upload 的第一個(gè)參數(shù)是文件的路徑，第二個(gè)是我們應(yīng)該與之關(guān)聯(lián)的可選 URL。請(qǐng)注意，如果您想使用縮寫的 URL(例如：~/foo.js)，請(qǐng)確保使用單引號(hào)以避免 shell 擴(kuò)展到您的主文件夾。

sentry-cli releases files "$VERSION" upload /path/to/file '~/file.js' 

上傳 Source Maps

對(duì)于 source map 上傳，提供了一個(gè)單獨(dú)的命令來(lái)幫助您上傳和驗(yàn)證 source map：

sentry-cli releases files "$VERSION" upload-sourcemaps /path/to/sourcemaps 

這個(gè)命令提供了一堆選項(xiàng)并嘗試盡可能多的自動(dòng)檢測(cè)。默認(rèn)情況下，它將掃描提供的文件路徑并上傳以 ~/ 前綴命名的路徑。它還將嘗試根據(jù)文件名找出 minified 文件和 source maps 之間的引用。因此，如果您有一個(gè)名為 foo.min.js 的文件，它是一個(gè) minified 的 JavaScript 文件和一個(gè)名為 foo.min.map 的source map，例如，它將發(fā)送一個(gè)很長(zhǎng)的 Sourcemap header 來(lái)關(guān)聯(lián)它們。這適用于系統(tǒng)可以檢測(cè)到關(guān)系的文件。

默認(rèn)情況下，sentry-cli 在上傳之前重寫 source maps：

1. 它將索引的 source maps 展平。這樣做的優(yōu)點(diǎn)是它有時(shí)可以壓縮 source maps，這可能會(huì)改善您的處理時(shí)間，并且可以與嵌入 source map 引用的本地路徑的工具一起使用，這些工具在服務(wù)器上不起作用。這在使用 source maps 進(jìn)行開發(fā)時(shí)特別有用。
2. 源內(nèi)容的 source maps 中的本地文件引用是內(nèi)聯(lián)的。這對(duì)于 React Native 項(xiàng)目特別有效，這些項(xiàng)目可能會(huì)引用數(shù)千個(gè)您可能不想單獨(dú)上傳的文件。
3. 它會(huì)在上傳之前非常準(zhǔn)確地自動(dòng)驗(yàn)證 source maps，這可以發(fā)現(xiàn)在事件發(fā)生之前您不會(huì)發(fā)現(xiàn)的錯(cuò)誤。這是 --validate 其他情況的改進(jìn)版本。

以下選項(xiàng)可用于更改上傳命令的行為：

--dist

• 設(shè)置上傳文件的分發(fā)標(biāo)識(shí)符(distribution identifier)。此標(biāo)識(shí)符用于區(qū)分單個(gè)版本中的多個(gè)同名文件。在 Source Map 故障排除中了解更多信息。
• https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/#verify-artifact-distribution-value-matches-value-configured-in-your-sdk

--no-sourcemap-reference

• 這會(huì)阻止自動(dòng)檢測(cè) source map 引用。不建議使用此選項(xiàng)，因?yàn)橄到y(tǒng)會(huì)回退到不發(fā)出任何引用。但是，如果您將 sourceMapURL 注釋手動(dòng)添加到 minified 的文件中并且您知道它們比自動(dòng)檢測(cè)更正確，則它很有用。

--no-rewrite

• 禁止重寫匹配的 source map。默認(rèn)情況下，該工具將重寫源，以便在可能的情況下將索引映射展平并內(nèi)聯(lián)缺失的源。這從根本上改變了上傳過(guò)程，使其完全基于 source map 和 minified 文件，并且對(duì)于像 react-native 這樣的設(shè)置會(huì)派上用場(chǎng)，這些設(shè)置生成 source map，否則這些 source map 不適用于 Sentry。

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

• 除非指定 --no-rewrite，否則這將從上傳的 source map 中的所有源引用中截?cái)嗲熬Y。例如，您可以使用它來(lái)刪除特定于構(gòu)建機(jī)器的路徑。通用前綴版本將嘗試自動(dòng)猜測(cè)通用前綴是什么并自動(dòng)將其砍掉。這不會(huì)修改上傳的源路徑。為此，請(qǐng)將 upload 或 upload-sourcemaps 命令指向更精確的目錄。

--validate

• 當(dāng)未啟用重寫時(shí)，這會(huì)在上傳之前嘗試 source map 驗(yàn)證。它將發(fā)現(xiàn) source map 的各種問(wèn)題，并在發(fā)現(xiàn)任何問(wèn)題時(shí)取消上傳。這不是默認(rèn)設(shè)置，因?yàn)檫@會(huì)導(dǎo)致誤報(bào)。

--url-prefix

• 這會(huì)在所有文件前面設(shè)置一個(gè) URL 前綴。默認(rèn)為 ~/ 但您可能希望將其設(shè)置為完整 URL。如果您的文件存儲(chǔ)在子文件夾中，這也很有用。例如：--url-prefix '~/static/js'

--ext

• 覆蓋要上傳的文件擴(kuò)展名列表。默認(rèn)情況下，處理以下文件擴(kuò)展名：js、map、jsbundle 和 bundle。該工具將根據(jù)文件內(nèi)容(例如：sources、minified sources 和 source maps)自動(dòng)檢測(cè)文件類型并采取適當(dāng)?shù)男袆?dòng)。對(duì)于多個(gè)擴(kuò)展，您需要重復(fù)該選項(xiàng)，例如：--ext js --ext map。

--ignore

• 指定一種或多種被忽略文件和文件夾的模式。覆蓋忽略文件中指定的模式。有關(guān)更多信息，請(qǐng)參閱 --ignore-file。請(qǐng)注意，與 --ignore-file 不同，此參數(shù)是相對(duì)于指定的路徑參數(shù)進(jìn)行解釋的。

--ignore-file

• 指定包含要在掃描期間忽略的文件和文件夾模式的文件。忽略模式遵循 gitignore 規(guī)則，并相對(duì)于忽略文件的位置進(jìn)行評(píng)估。該文件假定在當(dāng)前工作目錄或其任何父目錄中。
• 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 

這將返回該版本的所有上傳文件的列表。

刪除文件

您還可以刪除已上載的文件。按名稱或同時(shí)按所有文件：

sentry-cli releases files "$VERSION" delete NAME_OF_FILE 
sentry-cli releases files "$VERSION" delete --all 

創(chuàng)建 Deploys

您還可以將 deploys 與 releases 相關(guān)聯(lián)。要?jiǎng)?chuàng)建 deploy，您首先要?jiǎng)?chuàng)建一個(gè) release，然后為其創(chuàng)建一個(gè) deploy。至少，你應(yīng)該提供 deploy 去的“environment”(production、staging等)。您可以自由定義：

sentry-cli releases deploys "$VERSION" new -e ENVIRONMENT 

或者，您還可以定義 deploy 所用的時(shí)間：

start=$(date +%s) 
... 
now=$(date +%s) 
sentry-cli releases deploys "$VERSION" new -e ENVIRONMENT -t $((now-start)) 

也可以列出 deploys(但不能刪除)：

sentry-cli releases deploys "$VERSION" list 

調(diào)試信息文件

調(diào)試信息文件允許 Sentry 提取堆棧跟蹤并為大多數(shù)編譯平臺(tái)提供有關(guān)崩潰報(bào)告的更多信息。 sentry-cli 可用于驗(yàn)證和上傳調(diào)試信息文件。有關(guān)更多一般信息，請(qǐng)參閱調(diào)試信息文件。

• https://docs.sentry.io/platforms/apple/data-management/debug-files/

權(quán)限

sentry-cli 需要使用一組 Permissions & Scopes 對(duì) Auth Token 進(jìn)行身份驗(yàn)證，以便可以上傳調(diào)試信息文件。為此，您必須具有 project:releases 或 project:write 作用域。

Source maps 雖然也是調(diào)試信息文件，但在 Sentry 中的處理方式不同。有關(guān)更多信息，請(qǐng)參閱 sentry-cli 中的 Source Maps。 
 
https://docs.sentry.io/product/cli/releases/#sentry-cli-sourcemaps 

檢查文件

并非所有調(diào)試信息文件都可以被 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 

這將報(bào)告調(diào)試信息文件的調(diào)試標(biāo)識(shí)符(debug identifiers)以及它是否通過(guò) Sentry 的基本要求。

查找文件

如果您在 Sentry 的 UI 中看到缺少調(diào)試信息文件，但您不確定如何找到它們，則可以使用 sentry-cli difutil find 命令來(lái)查找它們：

 

sentry-cli difutil find 

此外，sentry-cli upload-dif 可以自動(dòng)搜索文件夾或 ZIP 存檔中的文件。

創(chuàng)建 Source Bundle

要在 Sentry UI 的堆棧跟蹤中獲取內(nèi)聯(lián)源上下文，sentry-cli 可以掃描調(diào)試文件以獲取對(duì)源代碼文件的引用，在本地文件系統(tǒng)中解析它們并將它們捆綁起來(lái)。生成的源包(source bundle)是一個(gè)存檔，其中包含特定調(diào)試信息文件引用的所有源文件。

這在構(gòu)建和上傳調(diào)試信息文件分離時(shí)特別有用。在這種情況下，可以在構(gòu)建時(shí)創(chuàng)建一個(gè)源包(source bundle)，并且可以在以后的任何時(shí)間點(diǎn)使用 sentry-cli upload-dif 上傳。

要?jiǎng)?chuàng)建 source bundle，請(qǐng)對(duì)調(diào)試信息文件列表使用 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... 

要為所有調(diào)試信息文件創(chuàng)建多個(gè)源包(source bundles)，請(qǐng)分別對(duì)每個(gè)文件使用該命令。

或者，將 --include-sources 選項(xiàng)添加到 upload-dif 命令，它會(huì)在上傳過(guò)程中即時(shí)生成源包(source bundles)。這要求上傳與應(yīng)用程序構(gòu)建在同一臺(tái)機(jī)器上執(zhí)行：

sentry-cli upload-dif --include-sources /path/to/files... 

上傳文件

使用 sentry-cli upload-dif 命令上傳調(diào)試信息文件到 Sentry。該命令將遞歸掃描提供的文件夾或 ZIP 檔案。已上傳的文件會(huì)自動(dòng)跳過(guò)。

我們建議在發(fā)布或發(fā)布您的應(yīng)用程序時(shí)上傳調(diào)試信息文件?；蛘?，可以在構(gòu)建過(guò)程中上傳文件。有關(guān)更多信息，請(qǐng)參閱調(diào)試信息文件。

• https://docs.sentry.io/workflow/debug-files/

您需要指定您正在使用的 organization 和 project，因?yàn)檎{(diào)試信息文件適用于 project。有關(guān)這方面的更多信息，請(qǐng)參閱使用 project。

https://docs.sentry.io/product/cli/configuration/#sentry-cli-working-with-projects

可以通過(guò)以下方式開始基本的調(diào)試文件上傳：

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 未來(lái)的事件。如果要將本機(jī)崩潰發(fā)送到 Sentry 以驗(yàn)證正確操作，請(qǐng)確保調(diào)試文件在 Project Settings > Debug Files 中列出?；蛘?，在 CLI 中指定 --wait，它將阻塞直到服務(wù)器端分析完成：

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) 

上傳選項(xiàng)

您可以為上傳命令提供幾個(gè)選項(xiàng)：

--wait

等待上傳文件的服務(wù)器端處理。默認(rèn)情況下，一旦調(diào)試文件上傳到 Sentry，upload-dif 就會(huì)完成。在此之后，Sentry 分析文件并使它們可用于 symbolication。指定 --wait 以確保在將崩潰發(fā)送到 Sentry 之前準(zhǔn)備好調(diào)試文件是有意義的。這可能會(huì)減慢命令的速度，不推薦用于 CI 構(gòu)建。

--no-unwind

不要掃描堆棧展開信息。為禁用 FPO 的構(gòu)建指定此標(biāo)志，或在設(shè)備上發(fā)生堆棧遍歷時(shí)指定此標(biāo)志。這通常不包括可執(zhí)行文件和庫(kù)。如果它們包含調(diào)試信息，它們可能仍會(huì)被上傳。

--no-debug

不要掃描調(diào)試信息。這通常會(huì)排除調(diào)試伴隨文件。如果它們包含堆棧展開信息，它們可能仍會(huì)被上傳。

--include-sources

掃描調(diào)試文件以獲取對(duì)源代碼文件的引用。如果引用的文件在本地文件系統(tǒng)上可用，則將它們捆綁并作為源存檔(source archive)上傳。這允許 Sentry 解析源上下文(source context)。僅在從與構(gòu)建相同的機(jī)器上傳時(shí)指定此命令。否則，請(qǐng)使用 difutil bundle-sources 提前生成包。

--derived-data

在派生數(shù)據(jù)文件夾中搜索 dSYM。 Xcode 將其構(gòu)建輸出存儲(chǔ)在此默認(rèn)位置。

--no-zips

默認(rèn)情況下，sentry-cli 將打開并搜索 ZIP 存檔以查找調(diào)試文件。這在從 iTunes Connect 或 CI 環(huán)境中的先前構(gòu)建階段下載構(gòu)建時(shí)特別有用。如果您的搜索路徑包含沒有調(diào)試文件的大型 ZIP 檔案，請(qǐng)使用此開關(guān)禁用以加快搜索速度。

--force-foreground

此選項(xiàng)強(qiáng)制在前臺(tái)進(jìn)行上傳。這僅影響從 Xcode 構(gòu)建步驟調(diào)用的上傳。默認(rèn)情況下，上傳過(guò)程將在從 Xcode 啟動(dòng)時(shí)分離并在后臺(tái)完成。如果您需要調(diào)試上傳過(guò)程，強(qiáng)制上傳在前臺(tái)運(yùn)行可能會(huì)很有用。

--info-plist

覆蓋 Info.plist 的搜索路徑，如果它位于非標(biāo)準(zhǔn)位置，則很有用。

--no-reprocessing

此參數(shù)可防止 Sentry 立即觸發(fā)重新處理。在極少數(shù)情況下，您希望分批上傳文件，并且希望確保 Sentry 在上傳某些可選 dSYM 之前不會(huì)開始重新處理，這會(huì)很有用。但請(qǐng)注意，有人仍然可以在此期間從 UI 觸發(fā)重新處理。

--symbol-maps

使用 BCSymbolMaps 解析 iTunes Connect 版本中的隱藏 symbols。如果在 AppStore 中發(fā)布應(yīng)用程序時(shí)未將 symbols 上傳到 Apple，則需要使用此 symbols 來(lái)表示崩潰。

Symbol Maps

如果您對(duì) Apple 隱藏調(diào)試符號(hào)，則調(diào)試文件將不會(huì)包含許多有用的符號(hào)。在這種情況下， sentry-cli 上傳會(huì)警告您它需要 BCSymbolMaps：

sentry-cli upload-dif ... 
 
> Found 34 debug information files 
 
> Warning: Found 10 symbol files with hidden symbols (need BCSymbolMaps) 

在這種情況下，您需要與您的文件匹配的 BCSymbolMaps。通常，這些是由 Xcode 構(gòu)建過(guò)程生成的。提供 --symbol-maps 參數(shù)并將其指向包含符號(hào)映射(symbol maps)的文件夾：

sentry-cli upload-dif --symbol-maps path/to/symbolmaps path/to/debug/symbols 

Breakpad 文件

與本機(jī)調(diào)試文件相比，Breakpad symbols 會(huì)丟棄許多處理小型轉(zhuǎn)儲(chǔ)不需要的信息。最值得注意的是，未聲明內(nèi)聯(lián)函數(shù)，因此 Sentry 無(wú)法在堆棧跟蹤中顯示內(nèi)聯(lián)幀。

如果可能，請(qǐng)上傳本機(jī)調(diào)試文件，例如 dSYM、PDB 或 ELF 文件，而不是 Breakpad symbols。

ProGuard Mapping 上傳

sentry-cli 可用于將 ProGuard 文件上傳到 Sentry;然而，在大多數(shù)情況下，您會(huì)使用 Gradle 插件來(lái)做到這一點(diǎn)。但是，在某些情況下，您需要手動(dòng)上傳 ProGuard 文件(例如，當(dāng)您僅發(fā)布正在創(chuàng)建的部分構(gòu)建版本時(shí))。

• https://github.com/getsentry/sentry-android-gradle-plugin

您需要指定您正在使用的 organization 和 project，因?yàn)?ProGuard 文件適用于項(xiàng)目。有關(guān)這方面的更多信息，請(qǐng)參閱使用項(xiàng)目。

https://docs.sentry.io/product/cli/configuration/#sentry-cli-working-with-projects

upload-proguard 命令用于上傳 ProGuard 文件。它獲取一個(gè)或多個(gè) ProGuard 映射文件(mapping files)的路徑，并將它們上傳到 Sentry。例子：

sentry-cli upload-proguard \ 
 
app/build/outputs/mapping/{BuildVariant}/mapping.txt 

由于 Android SDK 需要知道映射文件的 UUID，因此您需要將其嵌入到 sentry-debug-meta.properties 文件中。如果您提供自動(dòng)完成的 --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 對(duì)未來(lái)的事件進(jìn)行反混淆處理。如果您想向 Sentry 發(fā)送混淆崩潰以驗(yàn)證正確的操作，請(qǐng)確保 ProGuard 映射文件在 Project Settings > ProGuard 中列出。

上傳選項(xiàng)

--no-reprocessing

此參數(shù)可防止 Sentry 立即觸發(fā)重新處理。在極少數(shù)情況下，您希望分批上傳文件，并且希望確保 Sentry 在上傳某些可選 dSYM 之前不會(huì)開始重新處理，這會(huì)很有用。但請(qǐng)注意，有人仍然可以在此期間從 UI 觸發(fā)重新處理。

--no-upload

禁用實(shí)際上傳。這會(huì)運(yùn)行處理的所有步驟，但不會(huì)觸發(fā)上傳(這也會(huì)自動(dòng)禁用重新處理。如果您只想驗(yàn)證映射文件并將 ProGuard UUID 寫入屬性文件，這將非常有用。

--require-one 至少需要上傳一個(gè)文件，否則命令會(huì)出錯(cuò)。

發(fā)送事件

sentry-cli 工具也可用于發(fā)送事件。如果你想使用它，你需要導(dǎo)出 SENTRY_DSN 環(huán)境變量并將其指向你的一個(gè)項(xiàng)目的 DSN：

export SENTRY_DSN='https://examplePublicKey@o0.ingest.sentry.io/0' 

完成后，您可以開始使用 sentry-cli send-event 命令。

基本事件

對(duì)于基本的消息事件，您只需要提供 --message 或 -m 參數(shù)即可發(fā)送消息：

sentry-cli send-event -m "Hello from Sentry" 

這將向 sentry 發(fā)送一條消息并將其記錄為事件。與該事件一起，它會(huì)發(fā)送有關(guān)您正在運(yùn)行 sentry-cli 的機(jī)器的基本信息。您可以多次提供 -m 以發(fā)送多行：

sentry-cli send-event -m "Hello from Sentry" -m "This is more text"

帶參數(shù)的事件

此外，您可以在消息中使用 %s 作為占位符并使用 -a 參數(shù)填充它。這有助于查看它們，因?yàn)樗邢⒆詣?dòng)組合在一起：

sentry-cli send-event -m "Hello %s!" -a "Joe" 
 
sentry-cli send-event -m "Hello %s!" -a "Peter" 

發(fā)送面包屑

您還可以將日志文件傳遞給 send-event 命令，該命令將被解析并作為面包屑發(fā)送。將發(fā)送最后 100 項(xiàng)：

sentry-cli send-event -m “task failed” –-logfile error.log 

日志文件可以是各種格式。如果你想自己創(chuàng)建一個(gè)，你可以按照以下方式做一些事情：

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 數(shù)據(jù)

Extra 的數(shù)據(jù)可以通過(guò) -e 參數(shù)作為 KEY:VALUE 附加。例如，您可以像這樣發(fā)送一些鍵值對(duì)：

sentry-cli send-event -m "a failure" -e task:create-user -e object:42 

同樣，可以使用 -t 使用相同的格式發(fā)送 tag：

sentry-cli send-event -m "a failure" -t task:create-user 

指定 Release

可以使用 --release 參數(shù)發(fā)送 release。如果您在 git repository 中使用 sentry-cli，則會(huì)自動(dòng)選擇默認(rèn) release。

Bash Hook

對(duì)于 bash 腳本，您還可以使用 sentry-cli bash hook 啟用自動(dòng)錯(cuò)誤發(fā)送。這將啟用 set -e 并將為未處理的錯(cuò)誤(unhandled errors)發(fā)送 sentry 事件。

這樣做的限制是：

• sentry-cli 只有在啟用 set -e 時(shí)才有效(默認(rèn)情況下它會(huì)為您啟用)。
• sentry-cli 注冊(cè)一個(gè) 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 

 

或者，您可以使用其他機(jī)制(如 .sentryclirc 文件)來(lái)配置 DSN。