getsentry/relay
GitHub: getsentry/relay
Sentry 官方的事件转发与摄取代理服务，将 SDK 与服务器之间的部分功能推送到独立代理进程中执行。
Stars: 378 | Forks: 119
# 官方 Sentry Relay
[](https://github.com/getsentry/relay/actions?query=workflow%3ACI+branch%3Amaster)
[](https://github.com/getsentry/relay/releases/latest)
[](https://pypi.python.org/pypi/sentry-relay)
Sentry Relay 是一个服务，它将 Sentry SDK 以及 Sentry 服务器的一些功能推送到代理进程中。
## 文档
- 产品文档可以在以下地址找到：[https://docs.sentry.io/product/relay/](https://docs.sentry.io/product/relay)。
- 代码和开发文档可以在以下地址找到：
[https://getsentry.github.io/relay/](https://getsentry.github.io/relay/)。
## 许可证
与 Sentry 一样， Relay 采用 FSL 授权。有关更多信息，请参阅 `LICENSE.md` 文件和[此博客文章](https://blog.sentry.io/introducing-the-functional-source-license-freedom-without-free-riding/)。
## 开发
要构建 Relay，我们需要**最新稳定版的 Rust**（通过 [rustup](https://rustup.rs/) 安装）。该 crate 被拆分为一个包含多个功能（features）的 workspace，因此在运行构建或测试时，请始终确保传递 `--all` 和 `--all-features` 标志。
`processing` 功能还需要 C 编译器和 CMake。
要安装 cmake，请运行 `brew install cmake`。
要安装开发环境，请运行 `direnv allow` 然后运行 `devenv sync`。
（如果您尚未安装，请[安装 devenv](https://github.com/getsentry/devenv/?tab=readme-ov-file#install)。）
我们使用 VSCode 进行开发。此存储库包含用于配置代码风格、 linter 和实用功能的设置文件。首次打开项目时，请务必_安装推荐的扩展_，因为它们将在编码期间提供编辑器辅助。
存储库根目录包含一个带有实用开发命令的 `Makefile`：
- `make check`：运行代码格式检查和 linter。这在提交 pull request 之前非常有用。
- `make test`：运行单元测试、集成测试和 Python 包测试（更多信息请参见下文）。
- `make all`：运行所有检查和测试。这将执行大部分在 CI 中运行的任务。
- `make clean`：删除所有构建产物、 virtualenv 和缓存文件。
有关更多可用的 make 目标，请运行 `make help`。
集成测试需要 Redis 和 Kafka 在其默认配置下运行。获取所有必需服务最方便的方法是通过 [`devservices`](https://develop.sentry.dev/development-infrastructure/devservices/)，这需要一个最新的 Sentry 开发环境。
### 构建与运行
在开发环境中重新构建和运行 Relay 最简单的方法是使用 `cargo`。
根据配置的不同，您可能需要在本地运行一个 Sentry 实例。
```
# 更新 rust
rustup update
# 首次初始化 Relay
cargo run --all-features -- config init
# 使用所有 features 进行重新构建和运行
cargo run --all-features -- run
```
标准构建命令也可作为 `make` 目标使用。请注意， release 构建仍会生成调试信息。
```
# 在 debug 模式下不使用 optimizations 进行构建。
make build
# 使用 release optimizations 和 debug 信息进行构建。
make release
```
为了在进行一些更改后快速验证 Relay 是否能编译通过，您还可以使用 `cargo check`：
```
cargo check --all --all-features
```
### 功能
默认情况下， Relay 在编译时不包含 _处理（processing）_ 模式。这是用于将 Relay 作为代理运行的配置。有两个可选功能：
- **`processing`**：启用事件处理和摄取功能。这允许在配置中启用处理。启用后， Relay 会将事件生成到 Kafka topic 中，而不是转发到配置的上游。此外，它还将执行完整的事件规范化、过滤和速率限制。
- **`crash-handler`**：在启用向 Sentry 进行内部错误报告时，允许针对段错误和内存不足情况进行原生崩溃报告。
要启用某项功能，请将其传递给 cargo 命令。例如，要在启用了 `processing` 功能的情况下跨所有 workspace crate 运行测试，请运行：
```
cargo run --features=processing
```
### 测试
测试套件包含单元测试、集成测试套件以及针对 Python 包的独立测试套件。单元测试作为 Rust crate 的一部分实现，可以通过以下命令运行：
```
# 针对默认 features 的 tests
make test-rust
# 针对所有 features 运行 Rust tests
make test-rust-all
```
集成测试套件需要 Python。所需的版本在 `.python-version` 文件中指定。默认情况下，集成测试套件将创建一个 virtualenv，构建启用了处理的 Relay 二进制文件，并运行一系列集成测试：
```
# 确保所有 dependencies 都在运行
devservices up relay
# 创建新的 virtualenv，构建 Relay 并运行集成 tests
make test-integration
# 手动构建并运行单个 test
make build
.venv/bin/pytest tests/integration -k
```
#### 快照测试
我们使用 `insta` 进行快照测试。它将作为 `make test` 命令的一部分运行，以验证 schema/protocol 更改。要安装 `insta` 工具来审查快照，请运行：
```
cargo install cargo-insta
```
之后，您就可以通过运行以下命令来审查并自动更新快照文件：
```
cargo insta review
```
如果您对事件 schema/protocol 进行了任何更改，请务必运行此命令。
有关更多信息，请参见 。
### 代码检查
我们使用来自最新稳定通道的 `rustfmt` 和 `clippy` 进行代码格式化和代码检查。为确保这些工具已正确设置并以正确的配置运行，请使用以下 make 目标：
```
# 格式化整个 codebase
make format
# 在整个 codebase 上运行 clippy
make lint
```
### 调试
开发者构建默认不包含调试信息。如果您想将调试器附加到本地 Relay，可以使用提供的 `dev-debug` 配置，命令为 `cargo run --all-features --profile dev-debug`。
### Python 和 C-ABI
新的功能可能还需要添加到 Python 包中。这首先需要在 C ABI 中公开新函数。为此，请参阅 [Relay C-ABI readme](https://getsentry.github.io/relay/relay_cabi/)。
我们强烈建议在**虚拟环境**中开发和测试 Python 包。 ABI 更新并测试完成后，请确保激活 virtualenv 并安装该包，这将构建原生库。有两种方法可以安装它：
```
# 安装 dependencies：
devenv sync
# 安装 release build（推荐）：
.devenv/bin/uv pip install -v -e py
# 注意：使用 `direnv allow` 将 .devenv/bin 添加到 PATH，或者
# 你也可以自行安装 uv
# 安装 debug build（安装更快，但运行时慢得多）：
RELAY_DEBUG=1 uv pip install -v -e py
```
对于测试，我们使用通用的 `pytest`。同样，请确保您的 virtualenv 处于激活状态，并且已安装了最新版本的原生库。然后，运行：
```
# 创建新的 virtualenv，安装 release build 并运行 tests
make test-python
# 手动运行单个 test
.venv/bin/pytest py/tests -k
```
### 结合 Sentry 使用
要结合现有的 Sentry 开发服务器、自托管的 Sentry 安装或 Sentry SaaS 来开发 Relay，请在项目根目录的 `.relay/config.yml` 中将 upstream 配置为 Sentry 服务器的 URL。例如，在本地开发中将
`relay.upstream` 设置为 `http://localhost:8000/`。
要使用本地开发 Sentry 测试处理模式，请使用以下配置：
```
relay:
# Point to your Sentry devserver URL:
upstream: http://localhost:8000/
# Listen to a port other than 3000:
port: 3001
logging:
# Enable full logging and backtraces:
level: trace
enable_backtraces: true
limits:
# Speed up shutdown on ^C
shutdown_timeout: 0
processing:
# Enable processing mode with store normalization and post data to 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 开发服务器也会在端口
`3000` 上以类似配置启动一个处于处理模式的 Relay。该 Relay 不会干扰您的开发构建。为确保 SDK 发送到您的开发实例，请更新 DSN 中的端口：
```
http://@localhost:3001/
```
### 发布管理
我们使用 GitHub actions 来发布新版本。
有两个独立的项目需要发布：
- **Relay 二进制文件**会每月与 `sentry` 一起使用[日历版本控制](https://calver.org/)自动发布（参见 ），因此应该没有理由手动创建发布。话虽如此，也可以通过 ["Release" action](https://github.com/getsentry/relay/actions/workflows/release_binary.yml) 进行手动发布。在运行该 action 之前，请确保 [`CHANGELOG.md`](./CHANGELOG.md) 是最新的。
- **Relay Python 库**连同 C-ABI 会通过 ["Release Library" action](https://github.com/getsentry/relay/actions/workflows/release_library.yml) 发布。在运行该 action 之前，请确保 [`py/CHANGELOG.md`](./py/CHANGELOG.md) 是最新的。点击“Run workflow”并选择一个新版本。我们使用[语义化版本控制](https://semver.org/)，并在开发周期内发布。
### 更新日志说明
对于向 _Python 包_公开的更改，请在 `py/CHANGELOG.md` 中添加条目。这包括但不限于事件规范化、PII 脱敏和 protocol。
对于 _Relay 服务器_的更改，请在 `CHANGELOG.md` 中的以下标题下添加条目：
1. `Features`：用于新增的面向用户的功能。
2. `Bug Fixes`：用于面向用户的错误修复。
3. `Internal`：用于内部操作（尤其是处理模式）中的功能和错误修复。
在更新日志条目中，请添加指向此 PR 的链接（建议使用更具描述性的信息）：
```
- ${getCleanTitle()}. (${PR_LINK})
```
如果以上均不适用，您可以通过在 PR 描述中添加 `#skip-changelog` 来选择跳过。标签：Bash脚本, Rust, Sentry, 事件转发, 可视化界面, 搜索引擎查询, 数据代理, 日志收集, 监控代理, 网络流量审计, 逆向工具, 通知系统
