• Stars
    star
    246
  • Rank 164,726 (Top 4 %)
  • Language
    Rust
  • License
    Other
  • Created almost 7 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Sentry event forwarding and ingestion service.

Sentry

Official Sentry Relay

CI GitHub Release PyPI

Relay

The Sentry Relay is a service that pushes some functionality from the Sentry SDKs as well as the Sentry server into a proxy process.

Documentation

License

Like Sentry, Relay is licensed under the BSL. See the LICENSE file and this forum post for more information.

Development

To build Relay, we require the latest stable Rust. The crate is split into a workspace with multiple features, so when running building or running tests always make sure to pass the --all and --all-features flags. The processing feature additionally requires a C compiler and CMake.

To install the development environment, librdkafka must be installed and on the path. On macOS, we require to install it with brew install librdkafka, as the installation script uses brew --prefix to determine the correct location.

We use VSCode for development. This repository contains settings files configuring code style, linters, and useful features. When opening the project for the first time, make sure to install the Recommended Extensions, as they will allow editor assist during coding.

The root of the repository contains a Makefile with useful commands for development:

  • make check: Runs code formatting checks and linters. This is useful before opening a pull request.
  • make test: Runs unit tests, integration tests and Python package tests (see below for more information).
  • make all: Runs all checks and tests. This runs most of the tasks that are also performed in CI.
  • make clean: Removes all build artifacts, the virtualenv and cached files.

For more avalibale make targets, please, run make help.

Integration tests require Redis and Kafka running in their default configuration. The most convenient way to get all required services is via sentry devservices, which requires an up-to-date Sentry development environment.

Building and Running

The easiest way to rebuild and run Relay for development is using cargo. Depending on the configuration, you may need to have a local instance of Sentry running.

# Initialize Relay for the first time
cargo run --all-features -- config init

# Rebuild and run with all features
cargo run --all-features -- run

The standard build commands are also available as make targets. Note that release builds still generate debug information.

# Build without optimizations in debug mode.
make build

# Build with release optimizations and debug information.
make release

For quickly verifying that Relay compiles after making some changes, you can also use cargo check:

cargo check --all --all-features

Features

By default, Relay compiles without processing mode. This is the configuration used for Relays operating as proxys. There are two optional features:

  • processing: Enables event processing and ingestion functionality. This allows to enable processing in config. When enabled, Relay will produce events into a Kafka topic instead of forwarding to the configured upstream. Also, it will perform full event normalization, filtering, and rate limiting.

  • crash-handler: Allows native crash reporting for segfaults and out-of-memory situations when internal error reporting to Sentry is enabled.

To enable a feature, pass it to the cargo invocation. For example, to run tests across all workspace crates with the processing feature enabled, run:

cargo run --features=processing

Tests

The test suite comprises unit tests, an integration test suite and a separate test suite for the Python package. Unit tests are implemented as part of the Rust crates and can be run via:

# Tests for default features
make test-rust

# Run Rust tests for all features
make test-rust-all

The integration test suite requires python. By default, the integration test suite will create a virtualenv, build the Relay binary with processing enabled, and run a set of integration tests:

# Create a new virtualenv, build Relay and run integration tests
make test-integration

# Build and run a single test manually
make build
.venv/bin/pytest tests/integration -k <test_name>

Snapshot tests

We use insta for snapshot testing. It will run as part of the make test command to validate schema/protocol changes. To install the insta tool for reviewing snapshots run:

cargo install cargo-insta

After that you'll be able to review and automatically update snapshot files by running:

cargo insta review

Make sure to run the command if you've made any changed to the event schema/protocol. For more information see https://insta.rs/docs/.

Linting

We use rustfmt and clippy from the latest stable channel for code formatting and linting. To make sure that these tools are set up correctly and running with the right configuration, use the following make targets:

# Format the entire codebase
make format

# Run clippy on the entire codebase
make lint

Python and C-ABI

Potentially, new functionality also needs to be added to the Python package. This first requires to expose new functions in the C ABI. For this, refer to the Relay C-ABI readme.

We highly recommend to develop and test the python package in a virtual environment. Once the ABI has been updated and tested, ensure the virtualenv is active and install the package, which builds the native library. There are two ways to install this:

# Install the release build, recommended:
pip install --editable ./py

# Install the debug build, faster installation but much slower runtime:
RELAY_DEBUG=1 pip install --editable ./py

For testing, we use ubiquitous pytest. Again, ensure that your virtualenv is active and the latest version of the native library has been installed. Then, run:

# Create a new virtualenv, install the release build and run tests
make test-python

# Run a single test manually
.venv/bin/pytest py/tests -k <test_name>

Usage with Sentry

To develop Relay with an existing Sentry devserver, self-hosted Sentry installation, or Sentry SaaS, configure the upstream to the URL of the Sentry server in .relay/config.yml. For example, in local development set relay.upstream to http://localhost:8000/.

To test processing mode with a local development Sentry, use this configuration:

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 backraces:
  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"

Note that the Sentry devserver also starts a Relay in processing mode on port 3000 with similar configuration. That Relay does not interfere with your development build. To ensure SDKs send to your development instance, update the port in the DSN:

http://<key>@localhost:3001/<id>

Release Management

We use GitHub actions to release new versions. There are two separate projects to publish:

Instructions for changelogs

For 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. For changes to the Relay server, please add an entry to CHANGELOG.md under the following heading:

  1. Features: for new user-visible functionality.
  2. Bug Fixes: for user-visible bug fixes.
  3. Internal: for features and bug fixes in internal operation, especially processing mode.

To the changelog entry, please add a link to this PR (consider a more descriptive message):

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

If none of the above apply, you can opt out by adding #skip-changelog to the PR description.

More Repositories

1

sentry

Developer-first error tracking and performance monitoring
Python
38,989
star
2

sentry-javascript

Official Sentry SDKs for JavaScript
TypeScript
7,952
star
3

self-hosted

Sentry, feature-complete and packaged up for low-volume deployments and proofs-of-concept
Shell
7,663
star
4

responses

A utility for mocking out the Python Requests library.
Python
4,127
star
5

sentry-php

The official PHP SDK for Sentry (sentry.io)
PHP
1,817
star
6

raven-python

Raven is the legacy Python client for Sentry (getsentry.com) — replaced by sentry-python
Python
1,678
star
7

sentry-react-native

Official Sentry SDK for React Native
TypeScript
1,566
star
8

sentry-python

The official Python SDK for Sentry.io
Python
1,533
star
9

sentry-laravel

The official Laravel SDK for Sentry (sentry.io)
PHP
1,157
star
10

sentry-java

A Sentry SDK for Java, Android and other JVM languages.
Kotlin
1,154
star
11

sentry-ruby

Sentry SDK for Ruby
Ruby
927
star
12

sentry-go

The official Go SDK for Sentry (sentry.io)
Go
917
star
13

sentry-cli

A command line utility to work with Sentry.
Rust
833
star
14

sentry-cocoa

The official Sentry SDK for iOS, tvOS, macOS, watchOS.
Objective-C
803
star
15

milksnake

A setuptools/wheel/cffi extension to embed a binary data in wheels
Python
764
star
16

sentry-symfony

The official Symfony SDK for Sentry (sentry.io)
PHP
687
star
17

sentry-webpack-plugin

Repo moved to https://github.com/getsentry/sentry-javascript-bundler-plugins. Please open any issues/PRs there.
JavaScript
662
star
18

freight

Freight is a service which aims to make application deployments better.
Python
610
star
19

sentry-elixir

The official Elixir SDK for Sentry (sentry.io)
Elixir
597
star
20

sentry-dotnet

Sentry SDK for .NET
C#
576
star
21

raven-go

Sentry client in Go
Go
560
star
22

sentry-rust

Official Sentry SDK for Rust
Rust
515
star
23

raven-node

A standalone (Node.js) client for Sentry
JavaScript
457
star
24

symbolic

Stack trace symbolication library written in Rust
Rust
440
star
25

action-release

GitHub Action for creating a release on Sentry
TypeScript
424
star
26

sentry-kubernetes

Kubernetes event reporter for Sentry
Python
408
star
27

sentry-native

Sentry SDK for C, C++ and native applications.
C
397
star
28

pdb

A parser for Microsoft PDB (Program Database) debugging information
Rust
385
star
29

symbolicator

Native Symbolication as a Service
Rust
357
star
30

spotlight

Your Universal Debug Toolbar
TypeScript
356
star
31

docker-sentry

Docker Official Image packaging for Sentry
Python
348
star
32

sentry-docs

Sentry's documentation (and tools to build it)
MDX
331
star
33

rb

Routing and connection management for Redis in Python
Python
300
star
34

sentry-php-sdk

This is a meta package to ship sentry-php with a recommend http client.
298
star
35

snuba

Search the seas for your lost treasure.
Python
272
star
36

raven-csharp

Superseded by: https://github.com/getsentry/sentry-dotnet
C#
232
star
37

sentry-electron

The official Sentry SDK for Electron
TypeScript
217
star
38

sentry-plugins

Official plugins for Sentry server
Python
212
star
39

zeus

WIP: A dashboard for CI
Python
209
star
40

sentry-unity

Development of Sentry SDK for Unity
C#
208
star
41

sentry-wizard

Sentry Project Setup Wizard
TypeScript
192
star
42

rust-sourcemap

A library for rust that implements basic sourcemap handling
Rust
188
star
43

action-github-app-token

Gets a GitHub auth token for a GitHub App installation
TypeScript
184
star
44

sentry-android-gradle-plugin

Gradle plugin for Sentry Android. Upload proguard, debug files, and more.
Kotlin
142
star
45

sentry-fastlane-plugin

Official fastlane plugin for Sentry
Ruby
136
star
46

sentry-slack

DEPRECATED Slack integration for Sentry
Python
135
star
47

sentry-javascript-bundler-plugins

JavaScript Bundler Plugins for Sentry
TypeScript
133
star
48

action-git-diff-suggestions

This GitHub Action will take the current git changes and apply them as GitHub code review suggestions
TypeScript
122
star
49

examples

Collection of all different kinds of Sentry SDKs and integrations
C#
119
star
50

craft

The universal Sentry release CLI 🚀
TypeScript
118
star
51

sentry-capacitor

The official Sentry SDK for Capacitor
TypeScript
117
star
52

sentry-kotlin-multiplatform

Sentry SDK for Kotlin Multiplatform
Kotlin
104
star
53

sentry-clj

Sentry SDK for Clojure
Clojure
103
star
54

raven-objc

This SDK is deprecated. Use https://github.com/getsentry/sentry-cocoa
Objective-C
98
star
55

sentry-jira

A Plugin for sentry that lets you create JIRA issues
Python
95
star
56

raven-aiohttp

An aiohttp transport for raven-python
Python
90
star
57

sentry-android

MOVED: https://github.com/getsentry/sentry-java
87
star
58

sentry-unreal

Unreal Engine
C++
84
star
59

pytest-responses

py.test integration for responses
Python
83
star
60

sentry-github

A Sentry extension which integrates with GitHub.
Python
79
star
61

libsourcemap

DEPRECATED: Implements efficient sourcemap processing for Python in Rust
Rust
78
star
62

sentry-rrweb

Moved to: https://github.com/getsentry/sentry-javascript/tree/master/packages/replay#sentry-session-replay
TypeScript
73
star
63

sentry-cordova

The official Sentry SDK for Cordova
TypeScript
68
star
64

sentry-dart-plugin

A Dart Build Plugin that uploads debug symbols for Android, iOS/macOS and source maps for Web to Sentry via sentry-cli
Dart
66
star
65

sourcemaps.io

Web-based Source Map validator
TypeScript
58
star
66

breakpad-tools

Prebuilt tools and examples to work with Breakpad's minidumps
Makefile
56
star
67

dotnet-assembly-alias

Tool to rename .NET assemblies and references
C#
53
star
68

sentry-webhooks

An extension for Sentry which allows creation various web hooks.
Python
52
star
69

sentry-netlify-build-plugin

The Sentry Netlify build plugin automatically notifies Sentry of new releases being deployed to your site.
JavaScript
46
star
70

sentry-mobile-release-health-app

Sentry Mobile App
Dart
44
star
71

sentry-xamarin

Sentry for Xamarin Native and Xamarin.Forms
C#
44
star
72

develop

TypeScript
43
star
73

babel-gettext-extractor

A fork of babel-gettext-plugin that works with older versions of node and supports comment and location extraction
JavaScript
43
star
74

raven-swift

This SDK is deprecated. Use https://github.com/getsentry/sentry-cocoa
40
star
75

pytest-sentry

Track flaky tests in Sentry
Python
39
star
76

sentry-auth-github

GitHub SSO provider for Sentry
Python
39
star
77

arroyo

A library to build streaming applications that consume from and produce to Kafka.
Python
39
star
78

action-visual-snapshot

Save and compare your visual snapshots
TypeScript
38
star
79

sentry-fullstory

The Sentry-FullStory integration seamlessly integrates the Sentry and FullStory platforms.
TypeScript
37
star
80

sentry-phabricator

A Sentry extension which integrates with Phabricator
Python
36
star
81

platformicons

A platform and framework icon font.
TypeScript
36
star
82

sentry-auth-google

Google Apps SSO provider for Sentry
Python
34
star
83

integration-platform-example

An example kanban application which explores the ways developers can build apps on Sentry's integration platform
TypeScript
32
star
84

unity

Unity SDK UPM package
Objective-C
31
star
85

vanguard

TypeScript
29
star
86

profiling-node

The code for this repo now lives in https://github.com/getsentry/sentry-javascript/tree/develop/packages/profiling-node
TypeScript
29
star
87

symbol-collector

Clients and Server to collect system symbols.
C#
29
star
88

sentry-vscode

VSCode editor integration for Sentry
TypeScript
28
star
89

probot-report

Probot app that sends periodic reminder emails for outstanding PR reviews
JavaScript
28
star
90

hackweek-coda

A queue thing with a sprinkle of Italian
Python
27
star
91

sentry-replay

Moved to http://github.com/getsentry/sentry-javascript
TypeScript
27
star
92

perl-raven

A perl sentry client
Perl
26
star
93

sentry_airflow

Airflow integration with Sentry (https://sentry.io)
Python
26
star
94

cloud-run-typescript-template

Template for Google Cloud Run (typescript)
JavaScript
24
star
95

symsynd

C++
23
star
96

sentry-relay-attic

A relay server for Sentry (https://getsentry.com)
Rust
23
star
97

freight-cli

A command line interface to Freight
Python
22
star
98

xds

xDS service for Envoy
Go
22
star
99

atlas

A map to your company
Python
22
star
100

gib-potato

More Potato, more awesome 🥔
PHP
21
star