feat(weekly-report): adding week over week percentage change to total errors and transactions (#117037)

Resolves
[ID-1587](https://linear.app/getsentry/issue/ID-1587/add-top-level-metric-to-total-errors-and-total-transactions)

To test:
- Start dev environment
- Go to `debug/mail/weekly-reports/`
- Email should render normally -- there shouldn't be any changes to the
email content itself

Adds a percentage change indicator next to Total Errors and Total
Transactions in the weekly email report, showing how the current week
compares to the previous week (e.g., "▲ 50% (vs. last week)"). The
metric is displayed as a gray pill badge with a unicode arrow.

**Feature Flag**
Gated behind feature flag
`organizations:weekly-report-week-over-week-metric`

**Previous-week data fetching using cache-first approach**

We cache the previous week's counts. If it's a cache miss, then one
additional Snuba query per organization fetches last week's accepted
error and transaction counts, reusing the existing
`project_event_counts_for_organization()` function with shifted dates.
The query is instrumented with `@metrics.wraps` and
`sentry_sdk.start_span` for cost monitoring.

**Percentage display**

The percentage is hidden when there's no previous-week data or when the
change rounds to 0%. The debug weekly report view also generates
randomized previous-week data so the indicator is visible in email
previews.

Screenshot (fake data): 
<img width="639" height="265" alt="Screenshot 2026-06-05 at 3 02 47 PM"
src="https://github.com/user-attachments/assets/f42f3a68-6e65-4f95-96b5-63531e3f238a"
/>

Author: amy-chen23

src/sentry/features/temporary.py

@@ -362,6 +362,8 @@ def register_temporary_features(manager: FeatureManager) -> None:
     # Enable high date range options on new explore page
     manager.add("organizations:visibility-explore-range-high", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=True)
 
+    # Enable week-over-week percentage change metric in weekly email reports
+    manager.add("organizations:weekly-report-week-over-week-metric", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=False)
     # Enable logging to debug workflow engine process workflows
     manager.add("organizations:workflow-engine-process-workflows-logs", OrganizationFeature, FeatureHandlerStrategy.FLAGPOLE, api_expose=False)
     # Disable issue stream detector notifications for metric issues

src/sentry/tasks/summaries/organization_report_context_factory.py

@@ -1,5 +1,6 @@
 import sentry_sdk
 
+from sentry import features
 from sentry.constants import DataCategory
 from sentry.models.organization import Organization
 from sentry.models.organizationmember import OrganizationMember
@@ -17,6 +18,7 @@
     project_key_transactions_last_week,
     project_key_transactions_this_week,
 )
+from sentry.tasks.summaries.weekly_report_cache import read_project_metrics
 from sentry.utils import metrics
 from sentry.utils.outcomes import Outcome
 from sentry.utils.snuba import parse_snuba_datetime
@@ -97,6 +99,50 @@ def _append_project_event_counts(self, ctx: OrganizationReportContext) -> None:
                             project_ctx.error_count_by_day.get(timestamp, 0) + total
                         )
 
+    @metrics.wraps("weekly_report.create_context.project_event_counts_previous_week")
+    def _append_project_event_counts_previous_week(self, ctx: OrganizationReportContext) -> None:
+        """Populate previous-week accepted error/transaction counts for week-over-week comparison.
+
+        Reads from Redis cache first (written by cache_project_metrics() at the end of each
+        weekly report run), then falls back to a Snuba query for any cache misses.
+        """
+        with sentry_sdk.start_span(op="weekly_reports.project_event_counts_previous_week"):
+            project_ids = list(ctx.projects_context_map.keys())
+            cached = read_project_metrics(ctx.organization.id, project_ids)
+
+            for project_id, values in cached.items():
+                project_ctx = ctx.projects_context_map[project_id]
+                project_ctx.prev_week_accepted_error_count = values.get("e", 0)
+                project_ctx.prev_week_accepted_transaction_count = values.get("t", 0)
+
+            missed_project_ids = set(project_ids) - set(cached.keys())
+            if not missed_project_ids:
+                return
+
+            # Snuba fallback for cache misses (e.g. new projects, first report run)
+            prev_start = ctx.start - (ctx.end - ctx.start)
+            prev_end = ctx.start
+            event_counts = project_event_counts_for_organization(
+                start=prev_start,
+                end=prev_end,
+                ctx=ctx,
+                referrer=Referrer.REPORTS_OUTCOMES.value,
+            )
+            for data in event_counts:
+                project_id = data["project_id"]
+                if project_id not in missed_project_ids:
+                    continue
+                if project_id not in ctx.projects_context_map:
+                    continue
+                project_ctx = ctx.projects_context_map[project_id]
+                total = data["total"]
+                if data["outcome"] != Outcome.ACCEPTED:
+                    continue
+                if data["category"] == DataCategory.TRANSACTION:
+                    project_ctx.prev_week_accepted_transaction_count += total
+                elif data["category"] in DataCategory.error_categories():
+                    project_ctx.prev_week_accepted_error_count += total
+
     @metrics.wraps("weekly_report.create_context.issue_substatus_summaries")
     def _append_organization_project_issue_substatus_summaries(
         self, ctx: OrganizationReportContext
@@ -177,6 +223,8 @@ def create_context(self) -> OrganizationReportContext:
         with metrics.timer("weekly_report.create_context.duration"):
             self._append_user_project_ownership(ctx)
             self._append_project_event_counts(ctx)
+            if features.has("organizations:weekly-report-week-over-week-metric", self.organization):
+                self._append_project_event_counts_previous_week(ctx)
             self._append_organization_project_issue_substatus_summaries(ctx)
 
             # Enhanced privacy flag hides issue titles, transaction names, and source details

src/sentry/tasks/summaries/utils.py

@@ -72,6 +72,9 @@ class ProjectContext:
     accepted_replay_count = 0
     dropped_replay_count = 0
 
+    prev_week_accepted_error_count = 0
+    prev_week_accepted_transaction_count = 0
+
     new_substatus_count = 0
     ongoing_substatus_count = 0
     escalating_substatus_count = 0

src/sentry/tasks/summaries/weekly_reports.py

@@ -19,7 +19,7 @@
 from taskbroker_client.retry import Retry
 from taskbroker_client.worker.workerchild import ProcessingDeadlineExceeded
 
-from sentry import analytics
+from sentry import analytics, features
 from sentry.analytics.events.weekly_report import WeeklyReportSent
 from sentry.models.group import Group, GroupStatus
 from sentry.models.grouphistory import GroupHistoryStatus
@@ -496,6 +496,18 @@ def record_delivery(self) -> bool:
 }
 
 
+def _pct_change(current: int, previous: int) -> str | None:
+    """Returns a formatted string like '▲ 50%' or '▼ 25%', or None if not meaningful."""
+    if previous == 0:
+        return None
+    change = (current - previous) / previous
+    pct = round(change * 100)
+    if pct == 0:
+        return None
+    arrow = "▲" if change > 0 else "▼"
+    return f"{arrow} {abs(pct)}%"
+
+
 def get_group_status_badge(group: Group) -> tuple[str, str, str]:
     """
     Returns a tuple of (text, background_color, border_color)
@@ -669,12 +681,21 @@ def sum_event_counts(project_ctxs):
                     }
                 )
             series.append((to_datetime(t), project_series))
+        prev_week_error = sum(
+            p.prev_week_accepted_error_count for p in projects_associated_with_user
+        )
+        prev_week_transaction = sum(
+            p.prev_week_accepted_transaction_count for p in projects_associated_with_user
+        )
+
         return {
             "legend": legend,
             "series": series,
             "total_error_count": total_error,
             "total_transaction_count": total_transaction,
             "total_replay_count": total_replays,
+            "error_pct_change": _pct_change(total_error, prev_week_error),
+            "transaction_pct_change": _pct_change(total_transaction, prev_week_transaction),
             "error_maximum": max(  # The max error count on any single day
                 sum(value["error_count"] for value in values) for timestamp, values in series
             ),
@@ -783,6 +804,9 @@ def issue_summary():
         "user_project_count": len(user_projects),
         "notification_uuid": notification_uuid,
         "enhanced_privacy": ctx.organization.flags.enhanced_privacy,
+        "show_week_over_week_metric": features.has(
+            "organizations:weekly-report-week-over-week-metric", ctx.organization
+        ),
     }
 
 

src/sentry/templates/sentry/emails/reports/body.html

@@ -231,7 +231,13 @@ <h1>
 
     <td class="project-breakdown-graph-cell {% if has_replay_graph %}errors-wide{% else %}errors{% endif %}" {% if has_replay_graph %}colspan="2"{% endif %}>
     <h4 class="total-count-title">Total Project Errors</h4>
-    <h1 style="margin: 0;" class="total-count">{{ trends.total_error_count|small_count:1 }}</h1>
+    <h1 style="margin: 0;" class="total-count">
+      {{ trends.total_error_count|small_count:1 }}
+      {% if show_week_over_week_metric and trends.error_pct_change %}
+      <span style="font-size: 14px; font-weight: 500; margin-left: 8px; padding: 2px 8px; border-radius: 12px; vertical-align: middle; background-color: #F2F0FA; color: #80708F;">{{ trends.error_pct_change }}</span>
+      <span style="font-size: 12px; font-weight: normal; color: #80708F; margin-left: 4px; vertical-align: middle;">(vs. last week)</span>
+      {% endif %}
+    </h1>
     {% url 'sentry-organization-issue-list' organization.slug as issue_list %}
     {% querystring referrer="weekly_report" notification_uuid=notification_uuid as query %}
     <a href="{% org_url organization issue_list query=query %}"
@@ -273,7 +279,13 @@ <h1 style="margin: 0;" class="total-count">{{ trends.total_error_count|small_cou
     {% if trends.total_transaction_count > 0 %}
     <td class="project-breakdown-graph-cell {% if has_replay_graph %}transactions-below{% else %}transactions{% endif %} {% if has_replay_graph and trends.total_replay_count == 0 %}some-empty-below{% endif %}">
       <h4 class="total-count-title">Total Project Transactions</h4>
-      <h1 style="margin: 0;" class="total-count">{{ trends.total_transaction_count|small_count:1 }}</h1>
+      <h1 style="margin: 0;" class="total-count">
+        {{ trends.total_transaction_count|small_count:1 }}
+        {% if show_week_over_week_metric and trends.transaction_pct_change %}
+        <span style="font-size: 14px; font-weight: 500; margin-left: 8px; padding: 2px 8px; border-radius: 12px; vertical-align: middle; background-color: #F2F0FA; color: #80708F;">{{ trends.transaction_pct_change }}</span>
+        <span style="font-size: 12px; font-weight: normal; color: #80708F; margin-left: 4px; vertical-align: middle;">(vs. last week)</span>
+        {% endif %}
+      </h1>
       {% url 'sentry-organization-performance' organization.slug as performance_landing %}
       {% querystring referrer="weekly_report_view_all" notification_uuid=notification_uuid as query %}
       <a href="{% org_url organization performance_landing query=query %}"

src/sentry/web/frontend/debug/debug_weekly_report.py

@@ -90,6 +90,12 @@ def get_context(self, request):
             project_context.dropped_replay_count = int(
                 random.weibullvariate(5, 1) * random.paretovariate(0.2)
             )
+            project_context.prev_week_accepted_error_count = int(
+                project_context.accepted_error_count * random.uniform(0.5, 1.5)
+            )
+            project_context.prev_week_accepted_transaction_count = int(
+                project_context.accepted_transaction_count * random.uniform(0.5, 1.5)
+            )
             project_context.key_errors_by_group = [
                 (g, random.randint(0, 1000)) for g in Group.objects.all()[:3]
             ]
@@ -125,7 +131,12 @@ def get_context(self, request):
 
         user_id = request.user.id
         ctx.project_ownership[user_id] = {pid for pid in ctx.projects_context_map}
-        return render_template_context(ctx, user_id)
+        context = render_template_context(ctx, user_id)
+        if context is not None:
+            context["show_week_over_week_metric"] = (
+                request.GET.get("show_week_over_week_metric", "1") != "0"
+            )
+        return context
 
     @property
     def html_template(self) -> str:

tests/sentry/tasks/test_weekly_reports.py

@@ -40,6 +40,7 @@
 )
 from sentry.tasks.summaries.weekly_reports import (
     OrganizationReportBatch,
+    _pct_change,
     date_format,
     group_status_to_color,
     prepare_organization_report,
@@ -1536,3 +1537,123 @@ def test_enhanced_privacy_email_does_not_contain_sensitive_data(self) -> None:
             assert "sensitive error title xyz123" not in html
             assert "enhanced privacy" in html.lower()
             assert "Total Project Errors" in html
+
+    @with_feature("organizations:weekly-report-week-over-week-metric")
+    @mock.patch("sentry.tasks.summaries.weekly_reports.MessageBuilder")
+    def test_pct_change_with_previous_week(self, message_builder: mock.MagicMock) -> None:
+        user = self.create_user()
+        self.create_member(teams=[self.team], user=user, organization=self.organization)
+
+        self.store_event_outcomes(
+            self.organization.id, self.project.id, self.three_days_ago, num_times=10
+        )
+        self.store_event_outcomes(
+            self.organization.id,
+            self.project.id,
+            self.three_days_ago,
+            num_times=20,
+            category=DataCategory.TRANSACTION,
+        )
+
+        prev_week = self.three_days_ago - timedelta(days=7)
+        self.store_event_outcomes(self.organization.id, self.project.id, prev_week, num_times=5)
+        self.store_event_outcomes(
+            self.organization.id,
+            self.project.id,
+            prev_week,
+            num_times=40,
+            category=DataCategory.TRANSACTION,
+        )
+
+        prepare_organization_report(
+            self.timestamp, ONE_DAY * 7, self.organization.id, self._dummy_batch_id
+        )
+
+        for call_args in message_builder.call_args_list:
+            context = call_args.kwargs["context"]
+            assert context["trends"]["error_pct_change"] == "▲ 100%"
+            assert context["trends"]["transaction_pct_change"] == "▼ 50%"
+            assert context["show_week_over_week_metric"] is True
+
+    @with_feature("organizations:weekly-report-week-over-week-metric")
+    @mock.patch("sentry.tasks.summaries.weekly_reports.MessageBuilder")
+    def test_pct_change_no_previous_week(self, message_builder: mock.MagicMock) -> None:
+        user = self.create_user()
+        self.create_member(teams=[self.team], user=user, organization=self.organization)
+
+        self.store_event_outcomes(
+            self.organization.id, self.project.id, self.three_days_ago, num_times=10
+        )
+
+        prepare_organization_report(
+            self.timestamp, ONE_DAY * 7, self.organization.id, self._dummy_batch_id
+        )
+
+        for call_args in message_builder.call_args_list:
+            context = call_args.kwargs["context"]
+            assert context["trends"]["error_pct_change"] is None
+            assert context["trends"]["transaction_pct_change"] is None
+            assert context["show_week_over_week_metric"] is True
+
+    @mock.patch("sentry.tasks.summaries.weekly_reports.MessageBuilder")
+    def test_pct_change_hidden_without_feature_flag(self, message_builder: mock.MagicMock) -> None:
+        user = self.create_user()
+        self.create_member(teams=[self.team], user=user, organization=self.organization)
+
+        self.store_event_outcomes(
+            self.organization.id, self.project.id, self.three_days_ago, num_times=10
+        )
+
+        prev_week = self.three_days_ago - timedelta(days=7)
+        self.store_event_outcomes(self.organization.id, self.project.id, prev_week, num_times=5)
+
+        prepare_organization_report(
+            self.timestamp, ONE_DAY * 7, self.organization.id, self._dummy_batch_id
+        )
+
+        for call_args in message_builder.call_args_list:
+            context = call_args.kwargs["context"]
+            assert context["trends"]["error_pct_change"] is None
+            assert context["trends"]["transaction_pct_change"] is None
+            assert context["show_week_over_week_metric"] is False
+
+    @with_feature("organizations:weekly-report-week-over-week-metric")
+    @mock.patch("sentry.tasks.summaries.weekly_reports.MessageBuilder")
+    def test_pct_change_from_cache(self, message_builder: mock.MagicMock) -> None:
+        from sentry.tasks.summaries.weekly_report_cache import cache_project_metrics
+
+        user = self.create_user()
+        self.create_member(teams=[self.team], user=user, organization=self.organization)
+
+        self.store_event_outcomes(
+            self.organization.id, self.project.id, self.three_days_ago, num_times=10
+        )
+        self.store_event_outcomes(
+            self.organization.id,
+            self.project.id,
+            self.three_days_ago,
+            num_times=20,
+            category=DataCategory.TRANSACTION,
+        )
+
+        cache_project_metrics(
+            self.organization.id,
+            {self.project.id: {"e": 5, "t": 40}},
+        )
+
+        prepare_organization_report(
+            self.timestamp, ONE_DAY * 7, self.organization.id, self._dummy_batch_id
+        )
+
+        for call_args in message_builder.call_args_list:
+            context = call_args.kwargs["context"]
+            assert context["trends"]["error_pct_change"] == "▲ 100%"
+            assert context["trends"]["transaction_pct_change"] == "▼ 50%"
+
+    def test_pct_change_helper(self) -> None:
+        assert _pct_change(150, 100) == "▲ 50%"
+        assert _pct_change(50, 100) == "▼ 50%"
+        assert _pct_change(0, 100) == "▼ 100%"
+        assert _pct_change(100, 0) is None
+        assert _pct_change(0, 0) is None
+        assert _pct_change(100, 100) is None