{"id":13806914,"url":"https://github.com/getsentry/relay","last_synced_at":"2026-02-17T09:06:42.581Z","repository":{"id":36957553,"uuid":"117757315","full_name":"getsentry/relay","owner":"getsentry","description":"Sentry event forwarding and ingestion service.","archived":false,"fork":false,"pushed_at":"2025-05-14T22:10:05.000Z","size":330636,"stargazers_count":342,"open_issues_count":73,"forks_count":97,"subscribers_count":62,"default_branch":"master","last_synced_at":"2025-05-14T22:23:25.776Z","etag":null,"topics":["tag-production"],"latest_commit_sha":null,"homepage":"https://docs.sentry.io/product/relay/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getsentry.png","metadata":{"funding":{"custom":["https://sentry.io/pricing/","https://sentry.io/"]},"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-01-16T23:49:43.000Z","updated_at":"2025-05-14T15:04:40.000Z","dependencies_parsed_at":"2023-09-24T11:14:20.773Z","dependency_job_id":"cf3b68d1-42fb-44c9-afa9-86f551711b81","html_url":"https://github.com/getsentry/relay","commit_stats":null,"previous_names":[],"tags_count":184,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Frelay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Frelay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Frelay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsentry%2Frelay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getsentry","download_url":"https://codeload.github.com/getsentry/relay/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493380,"owners_count":22080126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["tag-production"],"created_at":"2024-08-04T01:01:17.933Z","updated_at":"2026-02-17T09:06:42.571Z","avatar_url":"https://github.com/getsentry.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://sentry.io/?utm_source=github\u0026utm_medium=logo\" target=\"_blank\"\u003e\n    \u003cpicture\u003e\n      \u003csource srcset=\"https://sentry-brand.storage.googleapis.com/sentry-logo-white.png\" media=\"(prefers-color-scheme: dark)\" /\u003e\n      \u003csource srcset=\"https://sentry-brand.storage.googleapis.com/sentry-logo-black.png\" media=\"(prefers-color-scheme: light), (prefers-color-scheme: no-preference)\" /\u003e\n      \u003cimg src=\"https://sentry-brand.storage.googleapis.com/sentry-logo-black.png\" alt=\"Sentry\" width=\"280\"\u003e\n    \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# Official Sentry Relay\n\n[![CI](https://github.com/getsentry/relay/workflows/CI/badge.svg?branch=master)](https://github.com/getsentry/relay/actions?query=workflow%3ACI+branch%3Amaster)\n[![GitHub Release](https://img.shields.io/github/release/getsentry/relay.svg)](https://github.com/getsentry/relay/releases/latest)\n[![PyPI](https://img.shields.io/pypi/v/sentry-relay.svg)](https://pypi.python.org/pypi/sentry-relay)\n\n\u003cp align=\"center\"\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/getsentry/relay/blob/master/artwork/relay-logo.png?raw=true\" alt=\"Relay\" width=\"480\"\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\nThe Sentry Relay is a service that pushes some functionality from the Sentry\nSDKs as well as the Sentry server into a proxy process.\n\n## Documentation\n\n- Product documentation can be found at: [https://docs.sentry.io/product/relay/](https://docs.sentry.io/product/relay).\n- Code and development documentation can be found at:\n  [https://getsentry.github.io/relay/](https://getsentry.github.io/relay/).\n\n## License\n\nLike Sentry, Relay is licensed under the FSL. See the `LICENSE.md` file and [this\nblog post](https://blog.sentry.io/introducing-the-functional-source-license-freedom-without-free-riding/)\nfor more information.\n\n## Development\n\nTo build Relay, we require the **latest stable Rust** (install via [rustup](https://rustup.rs/)). The crate is split into a\nworkspace with multiple features, so when running building or running tests\nalways make sure to pass the `--all` and `--all-features` flags.\nThe `processing` feature additionally requires a C compiler and CMake.\n\nTo install the development environment, run `direnv allow` then `devenv sync`.\n([Install devenv](https://github.com/getsentry/devenv/?tab=readme-ov-file#install) if you haven't already.)\n\nWe use VSCode for development. This repository contains settings files\nconfiguring code style, linters, and useful features. When opening the project\nfor the first time, make sure to _install the Recommended Extensions_, as they\nwill allow editor assist during coding.\n\nThe root of the repository contains a `Makefile` with useful commands for\ndevelopment:\n\n- `make check`: Runs code formatting checks and linters. This is useful before\n  opening a pull request.\n- `make test`: Runs unit tests, integration tests and Python package tests (see\n  below for more information).\n- `make all`: Runs all checks and tests. This runs most of the tasks that are\n  also performed in CI.\n- `make clean`: Removes all build artifacts, the virtualenv and cached files.\n\nFor more available make targets, please, run `make help`.\n\nIntegration tests require Redis and Kafka running in their default\nconfiguration. The most convenient way to get all required services is via\n[`devservices`](https://develop.sentry.dev/development-infrastructure/devservices/), which\nrequires an up-to-date Sentry development environment.\n\n### Building and Running\n\nThe easiest way to rebuild and run Relay for development is using `cargo`.\nDepending on the configuration, you may need to have a local instance of Sentry\nrunning.\n\n```bash\n# Update rust\nrustup update\n\n# Initialize Relay for the first time\ncargo run --all-features -- config init\n\n# Rebuild and run with all features\ncargo run --all-features -- run\n```\n\nThe standard build commands are also available as `make` targets. Note that\nrelease builds still generate debug information.\n\n```bash\n# Build without optimizations in debug mode.\nmake build\n\n# Build with release optimizations and debug information.\nmake release\n```\n\nFor quickly verifying that Relay compiles after making some changes, you can\nalso use `cargo check`:\n\n```bash\ncargo check --all --all-features\n```\n\n### Features\n\nBy default, Relay compiles without _processing_ mode. This is the configuration\nused for Relays operating as proxys. There are two optional features:\n\n- **`processing`**: Enables event processing and ingestion functionality. This\n  allows to enable processing in config. When enabled, Relay will produce events\n  into a Kafka topic instead of forwarding to the configured upstream. Also, it\n  will perform full event normalization, filtering, and rate limiting.\n\n- **`crash-handler`**: Allows native crash reporting for segfaults and\n  out-of-memory situations when internal error reporting to Sentry is enabled.\n\nTo enable a feature, pass it to the cargo invocation. For example, to run tests\nacross all workspace crates with the `processing` feature enabled, run:\n\n```bash\ncargo run --features=processing\n```\n\n### Tests\n\nThe test suite comprises unit tests, an integration test suite and a separate\ntest suite for the Python package. Unit tests are implemented as part of the\nRust crates and can be run via:\n\n```bash\n# Tests for default features\nmake test-rust\n\n# Run Rust tests for all features\nmake test-rust-all\n```\n\nThe integration test suite requires Python. The required version is specified\nin the `.python-version` file. By default, the integration test suite will\ncreate a virtualenv, build the Relay binary with processing enabled, and run\na set of integration tests:\n\n```bash\n# Make sure that all dependencies are running\ndevservices up relay\n\n# Create a new virtualenv, build Relay and run integration tests\nmake test-integration\n\n# Build and run a single test manually\nmake build\n.venv/bin/pytest tests/integration -k \u003ctest_name\u003e\n```\n\n#### Snapshot tests\n\nWe use `insta` for snapshot testing. It will run as part of the `make test` command\nto validate schema/protocol changes. To install the `insta` tool for reviewing snapshots run:\n\n```bash\ncargo install cargo-insta\n```\n\nAfter that you'll be able to review and automatically update snapshot files by running:\n\n```bash\ncargo insta review\n```\n\nMake sure to run the command if you've made any changes to the event schema/protocol.\nFor more information see https://insta.rs/docs/.\n\n### Linting\n\nWe use `rustfmt` and `clippy` from the latest stable channel for code formatting\nand linting. To make sure that these tools are set up correctly and running with\nthe right configuration, use the following make targets:\n\n```bash\n# Format the entire codebase\nmake format\n\n# Run clippy on the entire codebase\nmake lint\n```\n\n### Debugging\n\nDeveloper builds do not include debug information by default. If you want to\nattach a debugger to your local Relay, you can use the provided `dev-debug`\nprofile instead with `cargo run --all-features --profile dev-debug`.\n\n### Python and C-ABI\n\nPotentially, new functionality also needs to be added to the Python package.\nThis first requires to expose new functions in the C ABI. For this, refer to the\n[Relay C-ABI readme](https://getsentry.github.io/relay/relay_cabi/).\n\nWe highly recommend to develop and test the python package in a **virtual\nenvironment**. Once the ABI has been updated and tested, ensure the virtualenv\nis active and install the package, which builds the native library. There are\ntwo ways to install this:\n\n```bash\n# Install dependencies:\ndevenv sync\n\n# Install the release build, recommended:\n.devenv/bin/uv pip install -v -e py\n\n# note: use `direnv allow` to put .devenv/bin on PATH, or alternatively\n#       you can install uv yourself\n\n# Install the debug build, faster installation but much slower runtime:\nRELAY_DEBUG=1 uv pip install -v -e py\n```\n\nFor testing, we use ubiquitous `pytest`. Again, ensure that your virtualenv is\nactive and the latest version of the native library has been installed. Then,\nrun:\n\n```bash\n# Create a new virtualenv, install the release build and run tests\nmake test-python\n\n# Run a single test manually\n.venv/bin/pytest py/tests -k \u003ctest_name\u003e\n```\n\n### Usage with Sentry\n\nTo develop Relay with an existing Sentry devserver, self-hosted Sentry\ninstallation, or Sentry SaaS, configure the upstream to the URL of the Sentry\nserver in `.relay/config.yml` in the project root directory. For example, in local development set\n`relay.upstream` to `http://localhost:8000/`.\n\nTo test processing mode with a local development Sentry, use this configuration:\n\n```yaml\nrelay:\n  # Point to your Sentry devserver URL:\n  upstream: http://localhost:8000/\n  # Listen to a port other than 3000:\n  port: 3001\nlogging:\n  # Enable full logging and backtraces:\n  level: trace\n  enable_backtraces: true\nlimits:\n  # Speed up shutdown on ^C\n  shutdown_timeout: 0\nprocessing:\n  # Enable processing mode with store normalization and post data to Kafka:\n  enabled: true\n  kafka_config:\n    - { name: \"bootstrap.servers\", value: \"127.0.0.1:9092\" }\n    - { name: \"message.max.bytes\", value: 2097176 }\n  redis: \"redis://127.0.0.1\"\n```\n\nNote that the Sentry devserver also starts a Relay in processing mode on port\n`3000` with similar configuration. That Relay does not interfere with your\ndevelopment build. To ensure SDKs send to your development instance, update the\nport in the DSN:\n\n```\nhttp://\u003ckey\u003e@localhost:3001/\u003cid\u003e\n```\n\n### Release Management\n\nWe use GitHub actions to release new versions.\nThere are two separate projects to publish:\n\n- **Relay binary** is automatically released using [Calendar Versioning](https://calver.org/) on a monthly basis together with `sentry` (see https://develop.sentry.dev/self-hosted/releases/), so there should be no reason to create a release manually. That said, manual releases are possible with the [\"Release\" action](https://github.com/getsentry/relay/actions/workflows/release_binary.yml). Make sure that [`CHANGELOG.md`](./CHANGELOG.md) is up-to-date before running the action.\n\n- **Relay Python library** along with the C-ABI are released with the [\"Release Library\" action](https://github.com/getsentry/relay/actions/workflows/release_library.yml). Make sure that [`py/CHANGELOG.md`](./py/CHANGELOG.md) is up-to-date before running the action. Press \"Run workflow\" and choose a new version. We use [Semantic Versioning](https://semver.org/) and release during the development cycle.\n\n### Instructions for changelogs\n\nFor changes exposed to the _Python package_, add an entry to `py/CHANGELOG.md`. This includes, but is not limited to, event normalization, PII scrubbing, and the protocol.\nFor changes to the _Relay server_, please add an entry to `CHANGELOG.md` under the following heading:\n\n1. `Features`: for new user-visible functionality.\n2. `Bug Fixes`: for user-visible bug fixes.\n3. `Internal`: for features and bug fixes in internal operation, especially processing mode.\n\nTo the changelog entry, please add a link to this PR (consider a more descriptive message):\n\n```md\n- ${getCleanTitle()}. (${PR_LINK})\n```\n\nIf none of the above apply, you can opt out by adding `#skip-changelog` to the PR description.\n","funding_links":["https://sentry.io/pricing/","https://sentry.io/"],"categories":["Projects"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Frelay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetsentry%2Frelay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsentry%2Frelay/lists"}