開發
要構建 Relay，我們需要最新的穩定版 Rust。crate 被拆分為具有多個功能的工作區，因此在執行構建或執行測試時，請始終確保傳遞 --all 和 --all-features 標誌。processing 功能還需要 C 編譯器和 CMake。
要安裝開發環境，必須安裝 librdkafka 並在 path 上。 在 macOS 上，我們需要使用 brew install librdkafka 安裝它，因為安裝指令碼使用 brew --prefix 來確定正確的位置。
我們使用 VSCode 進行開發。此儲存庫包含配置程式碼樣式、linter 和有用功能的設定檔案。 首次開啟專案時，請確保 安裝推薦擴充套件，因為它們將允許編輯器在編碼期間提供幫助。
儲存庫的根目錄包含一個 Makefile，其中包含用於開發的有用命令：
make check: 執行程式碼格式檢查和linter。這在開啟pull request之前很有用。make test: 執行單元測試、整合測試和 Python 包測試（有關更多資訊，請參見下文）。make all: 執行所有檢查和測試。這會執行在CI中也執行的大多數任務。make clean: 刪除所有構建工件、virtualenv和快取檔案。
整合測試要求 Redis 和 Kafka 在其預設配置中執行。 獲取所有必需服務的最便捷方式是通過 sentry devservices，這需要最新的 Sentry 開發環境。
- sentry devservices
構建和執行
重建和執行 Relay 的最簡單方法是使用 cargo。根據配置，您可能需要執行 Sentry 的本地例項。
# 第一次初始化 Relay
cargo run --all-features -- config init
# 重建並執行所有功能
cargo run --all-features -- run
標準構建命令也可用作 make 目標。請注意，釋出版本仍會生成除錯資訊。
# 在除錯模式下不進行優化構建。
make build
# 使用釋出優化和除錯資訊進行構建。
make release
為了在進行一些更改後快速驗證 Relay 是否編譯，您還可以使用 cargo check：
cargo check --all --all-features
功能
預設情況下，Relay 編譯時不使用 processing 模式。 這是用於作為代理執行的中繼的配置。有兩個可選功能：
-
processing: 啟用事件處理(event processing)和攝取(ingestion)功能。這允許在配置中啟用 processing。啟用後，Relay會將事件生成到Kafka topic中，而不是轉發到配置的上游。此外，它將執行完整的事件規範化、過濾和速率限制。 -
ssl: 在伺服器中啟用SSL支援。
要啟用功能，請將其傳遞給 cargo 呼叫。例如，要在啟用了 processing 功能的情況下跨所有 workspace crates 執行測試，請執行：
cargo run --features=processing
測試
測試套件包括單元測試、整合測試套件和 Python 包的單獨測試套件。單元測試是作為 Rust crates 的一部分實現的，可以通過以下方式執行：
# 測試預設功能
make test-rust
# 為所有功能執行 Rust 測試
make test-rust-all
整合測試套件需要 python。預設情況下，整合測試套件將建立一個 virtualenv，構建啟用處理的 Relay 二進位制檔案，並執行一組整合測試：
# 建立一個新的 virtualenv，構建 Relay 並執行整合測試
make test-integration
# 手動構建和執行單個測試
make build
.venv/bin/pytest tests/integration -k <test_name>
Linting
我們使用來自最新穩定通道的 rustfmt 和 clippy 進行程式碼格式化和 linting。 要確保正確設定這些工具並使用正確的配置執行，請使用以下 make 目標：
# 格式化整個程式碼庫
make format
# 在整個程式碼庫上執行 clippy
make lint
Python 和 C-ABI
潛在地，還需要將新功能新增到 Python 包中。這首先需要在 C ABI 中公開新功能。 為此，請參閱 Relay C-ABI readme。
- Relay C-ABI readme
我們強烈建議在 virtual
environment 中開發和測試 python 包。更新和測試 ABI 後，確保 virtualenv 處於活動狀態並安裝構建原生庫的包。有兩種安裝方法：
# 安裝釋出版本，推薦：
pip install --editable ./py
# 安裝除錯版本，安裝速度更快，但執行時慢得多：
RELAY_DEBUG=1 pip install --editable ./py
對於測試，我們使用無處不在的 pytest。 同樣，確保您的 virtualenv 處於活動狀態並且已安裝最新版本的原生庫。然後，執行：
# 建立一個新的 virtualenv，安裝釋出版本並執行測試
make test-python
# 手動執行單個測試
.venv/bin/pytest py/tests -k <test_name>
開發 Server
如果你安裝了 systemfd 和 cargo-watch，make devserver 命令可以自動重新載入 Relay：
cargo install systemfd cargo-watch
make devserver
SSL
該儲存庫包含用於開發目的的 SSL-certificate + private key。它有兩種格式：一種是 (.pem, .cert) 對，一種是 .pfx (PKCS #12) 檔案。
密碼，.pfx 檔案是 password。
與 Sentry 一起使用
要使用現有的 Sentry devserver、self-hosted Sentry 安裝或 Sentry SaaS 開發 Relay，請將 .relay/config.yml 中的 upstream 配置為 Sentry server 的 URL。 例如，在本地開發中將 relay.upstream 設定為 http://localhost:8000/。
要使用本地 development Sentry 測試 processing 模式，請使用以下配置：
relay:
# 指向您的 Sentry devserver URL：
upstream: http://localhost:8000/
# 監聽 3000 以外的埠：
port: 3001
logging:
# 啟用完整的日誌記錄和回溯：
level: trace
enable_backtraces: true
limits:
# 在 ^C 上加速 shutdown
shutdown_timeout: 0
processing:
# 啟用儲存規範化的 processing 模式並將資料釋出到 Kafka：
enabled: true
kafka_config:
- { name: "bootstrap.servers", value: "127.0.0.1:9092" }
- { name: "message.max.bytes", value: 2097176 }
redis: "redis://127.0.0.1"
請注意，Sentry devserver 還在 processing 模式下在埠 3000 上以類似配置啟動 Relay。 該 Relay 不會干擾您的開發構建。為確保 SDK 傳送到您的開發例項，請更新 DSN 中的埠：
http://<key>@localhost:3001/<id>
釋出管理
我們使用 craft 來發布新版本。有兩個單獨的專案要釋出：
-
Relay binary 從根資料夾中釋出。在該目錄中執行
craft prepare和craft publish以分別建立釋出版本併發布它。我們使用日曆版本控制並與Sentry協調發布。 -
Relay Python library 和
C-ABI從py/子資料夾中釋出。切換到該目錄並執行craft prepare和craft publish。我們在開發週期中使用語義版本控制和釋出。
- craft
- 日曆化版本
- 語義版本控制
變更日誌說明
對於暴露給 Python package 的更改，請在 py/CHANGELOG.md 中新增一個條目。這包括但不限於事件規範化、PII 清理和協議。對於 Relay server 的更改，請在 CHANGELOG.md 的以下標題下新增一個條目：
Features: 用於新的使用者可見功能。Bug Fixes: 用於使用者可見的錯誤修復。Internal: 用於內部操作中的功能和錯誤修復，尤其是processing模式。
在 changelog 條目中，請新增指向此 PR 的連結（考慮更具描述性的訊息）：
- ${getCleanTitle()}. (${PR_LINK})
如果以上都不適用，您可以通過在 PR 描述中新增 #skip-changelog 來選擇退出。