feat(api): backfill alert name and tags - #3029

🦋 Changeset detected

Latest commit: ea67086

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hyperdx-oss	Ready	Preview	Aug 29, 2026 2:26am
hyperdx-storybook	Ready	Preview	Aug 29, 2026 2:26am

🔴 Tier 4 — Critical

Touches authentication, tenancy data models, the public API or shipped database config — or substantially changes the query rendering engine, background tasks, the OTel pipeline, image build, or release CI.

Why this tier:

• Background tasks or delivery pipeline substantially modified — 49 lines (bar: 30):
  • packages/api/src/tasks/checkAlerts/template.ts

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

Greptile Summary

The PR adds an idempotent startup migration that derives missing alert names and tags from saved searches, dashboard tiles, or inline chart configuration, and makes malformed alert title templates fall back to their raw text.

• Adds the alert tags schema field and name/tag derivation with unit and integration coverage.
• Runs the backfill during API startup using conditional bulk updates.
• Makes alert-title rendering resilient to malformed Handlebars templates.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking scalability concern in how the startup migration discovers records to batch.

The migration's writes are guarded and its behavioral changes are covered, but every API restart performs an unindexed scan and retains all matching alert IDs before bounded processing begins.

Files Needing Attention: packages/api/src/migrations.ts

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Start[API startup] --> Connect[Connect to MongoDB]
  Connect --> Query[Find alerts missing name or tags]
  Query --> Batch[Process alert IDs in batches]
  Batch --> Sources[Load referenced saved searches and dashboards]
  Sources --> Derive[Derive normalized name and tags]
  Derive --> Write[Conditionally bulk-update alerts]
  Write --> Serve[Complete startup]

_{Reviews (1): Last reviewed commit: "feat(api): backfill alert name and tags ..." | Re-trigger Greptile}

Deep Review

✅ No critical issues found. The largest reviewer claim — that the startup backfill blocks Kubernetes readiness and can crash-loop a rollout — was refuted by inspection: /ready (packages/api/src/routers/api/root.ts:46) returns 200 as soon as isMongoConnected() is true, which connectDBWithRetry() establishes before runStartupMigrations() runs, and the HTTP servers are already listening. The backfill delays only start()'s continuation (local-app-mode defaults), not readiness. The remaining findings are efficiency, a behavior change, logging, and test-coverage concerns.

🟡 P2 -- recommended

• packages/api/src/migrations.ts:70 -- Because the new tags field defaults to undefined, every untaggable alert (all INLINE, untagged saved searches, dangling refs) permanently matches the missing-name/tags filter, so the unindexed Alert.find COLLSCAN and per-batch SavedSearch/Dashboard hydration re-run on every boot of every replica with no completion marker or config kill-switch and never converge.
  • Fix: Gate the backfill behind a persisted completion marker or a config env flag so it becomes a no-op after the first successful run.
  • _{maintainability, data-migrations, performance, reliability, correctness}
• packages/api/src/tasks/checkAlerts/template.ts:245 -- Backfilling user-authored saved-search/dashboard/tile names into alert.name makes them executable Handlebars title templates, so a name containing valid syntax like {{alert.channel.webhookId}} or {{source}} is now compiled against the full notification view and rendered into the delivered title, a behavior these alerts did not have before.
  • Fix: Store the derived display name in a field distinct from the title-template, or neutralize {{ sequences when backfilling.
  • _{adversarial, data-migrations}
• packages/api/src/tasks/checkAlerts/template.ts:255 -- A backfilled name that is malformed Handlebars (e.g. truncated mid-expression) now logs at error level on every alert evaluation instead of once, and the backfill widens the population of names that were never authored as templates, so a single unfixable name can emit an error-log stream that trips error-rate monitors.
  • Fix: Log the compile failure at warn/debug and/or validate the template once at write/backfill time instead of on every render.
  • _adversarial
• packages/api/src/__tests__/migrations.int.test.ts:166 -- The inputsUnchangedFilter optimistic-concurrency guard (the mechanism that prevents writing a name derived from stale inputs) and the >BACKFILL_BATCH_SIZE (>500) multi-batch loop are both unexercised, so a regression weakening either would pass CI.
  • Fix: Add tests that mutate an alert's source/reference between read and write asserting no stale write, and that seed >500 backfillable alerts asserting every batch is processed.
  • _{testing, correctness, kieran-typescript, data-migrations}

Reviewers (8): correctness, testing, maintainability, data-migrations, reliability, adversarial, performance, kieran-typescript.

Testing gaps:

• No end-to-end test that a backfilled name containing valid {{...}} Handlebars renders as a live title template (the injection/behavior-change path).
• No test that a backfilled malformed-Handlebars name falls back to the raw string and does not throw across TILE/INLINE sources (only SAVED_SEARCH asserted).
• No multibyte/surrogate-pair case for the 512-char truncation (only ASCII 'x'.repeat(600)).
• No assertion that the steady state (zero backfillable alerts) or repeated runs against permanently-unfillable alerts perform no writes.

Note on prior comments: the 2 existing PR comments are automated (changeset-bot, vercel-bot) with no substantive human feedback to verify, so the previous-comments reviewer was not spawned.

E2E Test Results

✅ All tests passed • 324 passed • 1 skipped • 1124s

Tests ran across 4 shards in parallel.

View full report →