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 以使用它。

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

自動安裝

如果你使用的是 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>"。

• 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

另一種選擇是使用環境變量 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：

• https://scoop.sh/

> 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

創建 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 相關聯。

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

有兩種模式可以使用它。一種是全自動模式。如果您從 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”電子郵件，請查看我們的幫助中心文章。

• https://help.sentry.io/product-features/integrations/why-am-i-receiving-the-email-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。

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

要管理 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

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

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

一些示例用法：

# 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 可用於驗證和上傳調試信息文件。有關更多一般信息，請參閱調試信息文件。

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

權限

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

檢查文件

並非所有調試信息文件都可以被 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 檔案。已上傳的文件會自動跳過。

我們建議在發布或發布您的應用程序時上傳調試信息文件。或者，可以在構建過程中上傳文件。 有關更多信息，請參閱調試信息文件。

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

您需要指定您正在使用的 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

等待上傳文件的服務器端處理。默認情況下，一旦調試文件上傳到 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 文件（例如，當您僅發布正在創建的部分構建版本時）。

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

您需要指定您正在使用的 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://[e-mail]/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://[e-mail]/0'
eval "$(sentry-cli bash-hook)"
# rest of the script goes here

或者，您可以使用其他機制（如 .sentryclirc 文件）來配置 DSN。

公眾號：黑客下午茶