要构建 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>
我们使用来自最新稳定通道的 rustfmt 和 clippy 进行代码格式化和 linting。 要确保正确设置这些工具并使用正确的配置运行，请使用以下 make 目标：
# 格式化整个代码库
make format
# 在整个代码库上运行 clippy
make lint
潜在地，还需要将新功能添加到 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>
如果你安装了 systemfd 和 cargo-watch，make devserver 命令可以自动重新加载 Relay：
cargo install systemfd cargo-watch
make devserver
该存储库包含用于开发目的的 SSL-certificate + private key。它有两种格式：一种是 (.pem, .cert) 对，一种是 .pfx (PKCS #12) 文件。
密码，.pfx 文件是 password。
要使用现有的 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 来选择退出。
- Sentry Web 前端监控 - 最佳实践(官方教程)
- Sentry 后端监控 - 最佳实践(官方教程)