Skip to content

Gate Sentry export by span level, add Level enums#11

Open
loks0n wants to merge 1 commit into
mainfrom
feat/span-warn-level
Open

Gate Sentry export by span level, add Level enums#11
loks0n wants to merge 1 commit into
mainfrom
feat/span-warn-level

Conversation

@loks0n

@loks0n loks0n commented Jun 15, 2026

Copy link
Copy Markdown
Contributor

Summary

The span Sentry exporter previously sent every span carrying a Throwable and always reported it at error. This gates export on the span's level instead:

  • Spans at warning or above are sent, each reported at its own level.
  • A caught exception finished at Level::Warn now shows in Sentry as warning (not error).
  • A caught exception downgraded to Level::Info/Level::Debug is now suppressed (previously any Throwable was sent).
  • error/fatal behave as before.

Enums (no backward compat)

  • Utopia\Span\Level — the library's vocabulary, following Grafana Loki's detected_level terms: debug / info / warn / error / fatal (note warn, not warning). This is the type accepted by Span::finish().
  • Utopia\Span\Exporter\Sentry\Level — Sentry's own terms, with fromSpan() translating warn → Sentry's warning on the wire. Kept distinct so the core stays Loki-native and the Sentry contract lives in the exporter.

So a span finished at Level::Warn reads as warn in the Stdout/Pretty exporters and serializes to "level":"warning" in the Sentry envelope.

Notes

  • The envelope is still exception-shaped: a warning span carrying no Throwable passes the gate but produces no event (no stacktrace to send). A captureMessage-style path for exception-less warnings could be added later if needed.
  • Span::finish() signature changed from ?string $level to ?Level $level. The only in-repo caller (client) uses finish() with no level arg, so it's unaffected.

Testing

bin/monorepo check span (pint/phpstan/rector) and bin/monorepo test span (99 tests) pass.

🤖 Generated with Claude Code

The Sentry exporter previously sent every span carrying a Throwable and
always reported it at `error`. Gate export on the span's level instead:
spans at warning or above are sent, each reported at its own level, so a
caught exception finished at `warn` shows as a warning and one downgraded
to `info`/`debug` is suppressed.

Introduce a `Utopia\Span\Level` enum (Grafana Loki `detected_level`
vocabulary — `debug/info/warn/error/fatal`) as the type for `finish()`,
and a `Utopia\Span\Exporter\Sentry\Level` enum for Sentry's own terms,
translating `warn` to Sentry's `warning` on the wire.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant