ghcr.io/getsentry/relay:44b374d767d3a17dda4baaa9238e640052349436

官方 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

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

direnv allow devenv sync

我们使用 VSCode 进行开发。此仓库包含配置代码风格、lint 工具和实用功能的设置文件。首次打开项目时，请确保安装推荐的扩展，它们将在编码过程中提供编辑器辅助。

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

Makefile

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

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

make help

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

devservices

与 Sentry 一起使用

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

在 .relay/config.yml 中设置 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"

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

3000

http:// @localhost:3001/

发布管理

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

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

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

cargo check --all --all-features

特性

默认情况下，Relay 编译时不包含 处理（processing） 模式。这是 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/%E3%80%82

我们强烈建议在 虚拟环境 中开发和测试 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 二进制文件 使用 日历版本控制（Calendar Versioning） 每月与 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”并选择新版本。我们使用 语义化版本控制（Semantic Versioning） 并在开发周期中发布。

变更日志说明

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

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

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

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

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