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

內容源於：https://docs.sentry.io/platforms/javascript/guides/vue/

系列

• 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)，因為括號是用於顯示的（[email protected]+2 變成 1.0 (2)），所以呼叫它們會導致錯誤。
• 如果您使用 DVCS，我們建議使用標識雜湊（例如：commit SHA，da39a3ee5e6b4b0d3255bfef95601890afd80709）。您可以讓 sentry-cli 自動為支援的版本控制系統確定此雜湊，並使用 sentry-cli releases propose-version(建議版本)。
• 如果您標記 release，我們建議使用帶有產品或包名稱字首的 release tag （例如，[email protected]）。

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 "[email protected]"

或者：沒有 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://[email protected]/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://[email protected]/0'

eval "$(sentry-cli bash-hook)"

# rest of the script goes here

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

公眾號：黑客下午茶