ghcr.io/getsentry/relay:4622f74bba43211328e271150e446f13eba2530e

官方 Sentry Relay

Sentry Relay 是一项服务，它将 Sentry SDK 以及 Sentry 服务器的部分功能迁移到代理进程中。

文档

• 产品文档可查阅：[***]
• 代码和开发文档可查阅：https://getsentry.github.io/relay/%E3%80%82

许可协议

与 Sentry 一样，Relay 基于 FSL 许可协议发布。有关更多信息，请参见 LICENSE.md 文件和此博客文章。

LICENSE.md

开发

Relay 项目对 AI 使用有严格规定。请参见 HOWTOAI.md。

要构建 Relay，需要最新的稳定版 Rust（通过 rustup 安装）。该 crate 分为包含多个功能的工作区，因此在构建或运行测试时，务必传递 --all 和 --all-features 标志。processing 功能还需要 C 编译器和 CMake。

--all
--all-features
processing

要安装 cmake，请运行 brew install cmake。

brew install cmake

要安装开发环境，请运行 direnv allow，然后运行 devenv sync。（如果尚未安装 devenv，请先安装。）

direnv allow
devenv sync

我们使用 VSCode 进行开发。此仓库包含配置代码风格、代码检查器和实用功能的设置文件。首次打开项目时，请确保安装推荐扩展（Recommended Extensions），以便在编码过程中获得编辑器辅助。

仓库根目录包含一个 Makefile，其中包含用于开发的实用命令：

Makefile

• make check：运行代码格式检查和代码检查器。在提交拉取请求（pull request）前使用此命令非常有用。
• make test：运行单元测试、集成测试和 Python 包测试（详见下文）。
• make all：运行所有检查和测试。此命令会执行 CI 中运行的大部分任务。
• make clean：删除所有构建产物、虚拟环境（virtualenv）和缓存文件。

有关更多可用的 make 目标，请运行 make help。

make help

集成测试需要 Redis 和 Kafka 以默认配置运行。获取所有所需服务的最便捷方式是通过 devservices，这需要最新的 Sentry 开发环境。

devservices

与 Sentry 配合使用

要使用现有的 Sentry devserver、自托管 Sentry 安装或 Sentry SaaS 开发 Relay，请在项目根目录的 .relay/config.yml 中配置上游为 Sentry 服务器的 URL。例如，在本地开发中，将 relay.upstream 设置为 http://localhost:8000/。

要使用本地开发的 Sentry 测试处理模式，请使用以下配置：

relay:
  # 指向您的 Sentry devserver URL：
  upstream: http://localhost:8000/
  # 监听 3000 以外的端口：
  port: 3001
logging:
  # 启用完整日志和回溯：
  level: trace
  enable_backtraces: true
limits:
  # 加速 ^C 关闭
  shutdown_timeout: 0
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"

[!NOTE] Sentry devserver 也会在端口 3000 上启动一个具有类似配置的处理模式 Relay。该 Relay 不会干扰您的开发构建。要确保 SDK 发送到您的开发实例，请更新 DSN 中的端口：

3000 改为 http://<key>@localhost:3001/

发布管理

我们使用 GitHub Actions 发布新版本。有两个独立的项目需要发布：

• Relay 二进制文件会与 Sentry 一起每月使用日历版本控制（Calendar Versioning）自动发布（参见 [***] CHANGELOG.md 是最新的。

• Relay Python 库及 C-ABI 通过“Release Library”操作发布。运行该操作前，请确保 py/CHANGELOG.md 是最新的。点击“Run workflow”并选择新版本。我们使用语义化版本控制（Semantic Versioning）并在开发周期中发布。

变更日志说明

对于 Python 包中暴露的变更，请在 py/CHANGELOG.md 中添加条目。这包括但不限于事件标准化、PII 清理和协议。对于 Relay 服务器的变更，请在 CHANGELOG.md 中以下标题下添加条目：

• Features：用于新的用户可见功能。
• Bug Fixes：用于用户可见的错误修复。
• Internal：用于内部操作（尤其是处理模式）中的功能和错误修复。

请在变更日志条目中添加指向此 PR 的链接（考虑使用更具描述性的消息）：

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

如果以上情况均不适用，您可以通过在 PR 描述中添加 #skip-changelog 来选择不添加。

使用发布优化和调试信息构建

make release

若要快速验证修改后Relay是否可编译，也可使用`cargo check`：
```bash
cargo check --all --all-features

特性

默认情况下，Relay编译时不包含处理模式。这是Relay作为代理运行时的配置。有两个可选特性：

• processing：启用事件处理和摄入功能。这允许在配置中启用处理模式。启用后，Relay会将事件输出到Kafka主题，而非转发到配置的上游。此外，它将执行完整的事件标准化、过滤和速率限制。

• crash-handler：当启用向Sentry的内部错误报告时，允许对段错误和内存不足情况进行原生崩溃报告。

要启用特性，需将其传递给cargo调用。例如，要在所有工作区 crate 中启用processing特性运行测试，执行：

cargo run --features=processing

测试

测试套件包括单元测试、集成测试套件和Python包的独立测试套件。单元测试作为Rust crate的一部分实现，可通过以下命令运行：

# 测试默认特性
make test-rust

# 运行所有特性的Rust测试
make test-rust-all

集成测试套件需要Python。所需版本在.python-version文件中指定。默认情况下，集成测试套件会创建虚拟环境，构建启用处理模式的Relay二进制文件，并运行一系列集成测试：

# 确保所有依赖服务正在运行
devservices up relay

# 创建新虚拟环境、构建Relay并运行集成测试
make test-integration

# 手动构建并运行单个测试
make build
.venv/bin/pytest tests/integration -k

快照测试

我们使用insta进行快照测试。它会作为make test命令的一部分运行，以验证架构/协议变更。要安装用于审查快照的insta工具，执行：

cargo install cargo-insta

之后，你可以通过运行以下命令审查并自动更新快照文件：

cargo insta review

如果你对事件架构/协议进行了任何更改，请务必运行此命令。有关更多信息，请参见。

代码检查

我们使用最新稳定通道的rustfmt和clippy进行代码格式化和检查。为确保这些工具正确设置并使用正确配置运行，请使用以下make目标：

# 格式化整个代码库
make format

# 在整个代码库上运行clippy
make lint

调试

开发构建默认不包含调试信息。如果要将调试器附加到本地Relay，可以使用提供的dev-debug配置文件，执行cargo run --all-features --profile dev-debug。

Python和C-ABI

新功能可能还需要添加到Python包中。这首先需要在C ABI中公开新函数。有关此操作，请参阅https://getsentry.github.io/relay/relay_cabi/。

我们强烈建议在虚拟环境中开发和测试Python包。更新并测试ABI后，确保虚拟环境处于激活状态，然后安装包（这将构建原生库）。有两种安装方式：

# 安装依赖：
devenv sync

# 安装发布版本（推荐）：
.devenv/bin/uv pip install -v -e py

# 注意：使用`direnv allow`将.devenv/bin添加到PATH，或者你也可以自行安装uv

# 安装调试版本（安装更快但运行时慢得多）：
RELAY_DEBUG=1 uv pip install -v -e py

对于测试，我们使用常用的pytest。同样，确保虚拟环境已激活且已安装最新版本的原生库。然后运行：

# 创建新虚拟环境、安装发布版本并运行测试
make test-python

# 手动运行单个测试
.venv/bin/pytest py/tests -k

与Sentry配合使用

要使用现有Sentry开发服务器、自托管Sentry安装或Sentry SaaS开发Relay，需在项目根目录的.relay/config.yml中配置上游为Sentry服务器的URL。例如，在本地开发中，将relay.upstream设置为http://localhost:8000/。

要使用本地开发Sentry测试处理模式，请使用以下配置：

relay:
  # 指向你的Sentry开发服务器URL：
  upstream: http://localhost:8000/
  # 监听3000以外的端口：
  port: 3001
logging:
  # 启用完整日志记录和回溯：
  level: trace
  enable_backtraces: true
limits:
  # 加速^C的关闭过程
  shutdown_timeout: 0
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开发服务器也会在端口3000上启动一个具有类似配置的处理模式Relay。该Relay不会干扰你的开发构建。要确保SDK发送到你的开发实例，请更新DSN中的端口：

http:// @localhost:3001/

发布管理

我们使用GitHub Actions发布新版本。有两个独立的项目需要发布：

• Relay二进制文件使用日历版本控制每月自动发布，与sentry一起（参见），因此无需手动创建发布。不过，可通过https://github.com/getsentry/relay/actions/workflows/release_binary.yml进行手动发布。运行操作前，请确保CHANGELOG.md是最新的。

• Relay Python库及C-ABI通过https://github.com/getsentry/relay/actions/workflows/release_library.yml发布。运行操作前，请确保py/CHANGELOG.md是最新的。点击“Run workflow”并选择新版本。我们使用语义化版本控制并在开发周期中发布。

变更日志说明

对于Python包公开的变更，请在py/CHANGELOG.md中添加条目。这包括但不限于事件标准化、PII清理和协议。 对于Relay服务器的变更，请在CHANGELOG.md的以下标题下添加条目：

1. Features：用户可见的新功能。
2. Bug Fixes：用户可见的错误修复。
3. Internal：内部操作（尤其是处理模式）的功能和错误修复。

请在变更日志条目中添加指向此PR的链接（考虑使用更具描述性的消息）：

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

如果以上均不适用，可在PR描述中添加#skip-changelog选择不添加。