From 08c28ca0975b909b53edd68b2add31e61bad3b54 Mon Sep 17 00:00:00 2001 From: drew2a Date: Thu, 23 May 2024 14:25:57 +0200 Subject: [PATCH] Add Sentry error reporting documentation Introduced a detailed README for the Sentry error reporting mechanism in Tribler. The document explains how we've customized Sentry to respect user privacy and control over data sharing. It outlines the three operating modes of our modified Sentry, and describes our advanced Scrubber that removes sensitive information from user reports. --- src/tribler/core/sentry_reporter/README.md | 57 ++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 src/tribler/core/sentry_reporter/README.md diff --git a/src/tribler/core/sentry_reporter/README.md b/src/tribler/core/sentry_reporter/README.md new file mode 100644 index 00000000000..63a552fe005 --- /dev/null +++ b/src/tribler/core/sentry_reporter/README.md @@ -0,0 +1,57 @@ +# Tribler Error Reporting with Sentry + +For collecting errors from users' machines, we use [Sentry](https://docs.sentry.io/). +Due to the specific nature of our application, we cannot automatically collect +errors (which is the default behavior of Sentry). Therefore, we had to modify +the usual Sentry mechanism. +https://github.com/Tribler/tribler/blob/main/src/tribler/core/sentry_reporter/sentry_reporter.py + +The changes we made allow us to control Sentry and limit its error reporting +capabilities. By default, in Tribler, sending Sentry messages is suppressed. +When an error occurs, the user is presented with a dialog where they must explicitly +indicate that the error should be sent to the Tribler team. + +## Modified Sentry Modes + +The modified Sentry has three operating modes: + +```python +class SentryStrategy(Enum): + """Class describes all available Sentry Strategies + + SentryReporter can work with 3 strategies: + 1. Send reports are allowed + 2. Send reports are allowed with a confirmation dialog + 3. Send reports are suppressed (but the last event will be stored) + """ + + SEND_ALLOWED = auto() + SEND_ALLOWED_WITH_CONFIRMATION = auto() + SEND_SUPPRESSED = auto() +``` + +Immediately after Tribler starts, the mode is set to `SEND_ALLOWED_WITH_CONFIRMATION`. +As soon as the UI loads, Sentry switches to `SEND_SUPPRESSED`. + +`SEND_ALLOWED` is used only on developers' machines if they explicitly set +`TRIBLER_TEST_SENTRY_URL` in the environment variables. + +## Scrubber + +We use an advanced Scrubber to remove all sensitive parts from the user's report. +Our Scrubber processes all fields of the Sentry event and replaces sensitive parts +with placeholders. + +Parts considered sensitive: +- User name +- User machine name +- User-specific folder names +- IP addresses +- Torrent hashes + +For placeholders, we use words generated by [Faker](https://pypi.org/project/Faker/) +based on the string. This way, we can understand when the same strings repeat in +the report, but we cannot determine what the actual value of the string was on +the user's machine. + +https://github.com/Tribler/tribler/blob/main/src/tribler/core/sentry_reporter/sentry_scrubber.py