開發

要構建 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

https://develop.sentry.dev/services/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

https://getsentry.github.io/relay/relay_cabi/

我們強烈建議在 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

https://github.com/getsentry/craft

• 日歷化版本

https://calver.org

• 語義版本控制

https://semver.org

變更日志說明

對于暴露給 Python package 的更改，請在 py/CHANGELOG.md 中添加一個條目。這包括但不限于事件規范化、PII 清理和協議。對于 Relay server 的更改，請在 CHANGELOG.md 的以下標題下添加一個條目：

• Features: 用于新的用戶可見功能。
• Bug Fixes: 用于用戶可見的錯誤修復。
• Internal: 用于內部操作中的功能和錯誤修復，尤其是 processing 模式。

在 changelog 條目中，請添加指向此 PR 的鏈接(考慮更具描述性的消息)：

- ${getCleanTitle()}. (${PR_LINK})

如果以上都不適用，您可以通過在 PR 描述中添加 #skip-changelog 來選擇退出。