Skip to content

feat: expose the Sentry settings that cost RPS - #231

Merged
lesnik512 merged 3 commits into
mainfrom
feat/186-sentry-rps-knobs
Sep 20, 2026
Merged

lesnik512 merged 3 commits into
mainfrom
feat/186-sentry-rps-knobs

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Closes #186.

Three Sentry settings that measurably cost RPS were reachable only by hand-building
sentry_integrations or stuffing sentry_additional_params. All three are now config fields.

What changed

  • sentry_logs_level=None by default. Unless sentry_integrations already contains a
    LoggingIntegration, SentryInstrument appends
    LoggingIntegration(level=sentry_logging_breadcrumb_level, sentry_logs_level=None).
  • sentry_auto_session_tracking: bool = True, passed to sentry_sdk.init. Default unchanged.
  • sentry_logging_breadcrumb_level: int | None = logging.INFO, the breadcrumb handler's level.
    Default unchanged; None disables breadcrumbs.

Why the appended integration is behaviour-preserving

sentry_sdk.integrations.setup_integrations builds {integration.identifier: integration} and only
fills a default in if integration_cls.identifier not in integrations, so a user-supplied
LoggingIntegration still wins. The appended one differs from sentry-sdk's own default integration
in exactly one handler: EventHandler(ERROR) and BreadcrumbHandler(INFO) are untouched, only
SentryLogsHandler goes away.

That handler is pure waste here. lite-bootstrap never sets enable_logs, so Sentry Logs is off, but
SentryLogsHandler.emit calls self.format(record) before it checks
has_logs_enabled(client.options) — filed upstream as
getsentry/sentry-python#7402. Even if that
lands, sentry_logs_level=None remains the correct configuration while the feature is unsupported.

When sentry_default_integrations=False the integration is not appended. Appending it would add
an integration the user explicitly disabled, so the opt-out has to win.

sentry_additional_params now overrides instead of colliding

Adding auto_session_tracking as an explicit init kwarg broke every user who had reached it the
documented way — the issue itself describes these settings as reachable "by stuffing
sentry_additional_params":

TypeError: sentry_sdk._init_implementation._init() got multiple values for keyword argument 'auto_session_tracking'

bootstrap() now builds an init_params dict that sentry_additional_params updates, so it
overrides the explicit kwargs for every field rather than colliding with them. Nothing that works
today changes behaviour: a key collision was already a TypeError.

An ignored knob warns

sentry_logging_breadcrumb_level cannot apply when the user supplies their own LoggingIntegration
or sets sentry_default_integrations=False. Rather than fail silently, it goes through
warn_at_caller, naming which of the two reasons applies — the same shape as
"swagger_path differs from docs_url, ... will be used" in fastapi_bootstrapper.py. The warning
only fires when the field is off its default, so a user who never touched it never sees it.

Docs and benchmarks

docs/introduction/configuration.md documents the three fields, the appended integration and both
opt-outs, linking benchmarks/README.md §4c for the numbers rather than copying the table.

benchmarks/README.md asserted the opposite of the code in several places, some of it stale since
before this branch:

  • §4a was titled "two knobs lite-bootstrap does not expose" and said "There is no configuration
    surface for a sampler anywhere in lite-bootstrap
    ". Both OpenTelemetry sampler is not configurable #184 and Pass exclude_spans to FastAPIInstrumentor so ASGI send/receive spans are opt-out #185 have since shipped as
    opentelemetry_sampler and opentelemetry_exclude_spans.
  • §6's tuned configuration hand-built LoggingIntegration(level=None, sentry_logs_level=None) and
    sentry_additional_params={"auto_session_tracking": False}, and carried the OTel knobs as a
    comment reading "not expressible today". It now uses the real fields throughout. I ran the new
    spelling and confirmed it produces an identical client: _breadcrumb_handler None,
    _sentry_logs_handler None, _handler EventHandler(ERROR), auto_session_tracking False.
  • §7 was headed "nothing implemented" while listing three issues that are now implemented.

Not done, deliberately

  • No sentry_logs_level config field, despite the symmetry with the breadcrumb knob. Any
    non-None value is pure waste while lite-bootstrap does not support Sentry Logs, so the knob would
    be generality with no need behind it.
  • No ADR. The decision is a one-line reversal and its rationale lives in the configuration docs,
    so it fails the "hard to reverse" test.

Testing

Nine new tests in tests/instruments/test_sentry_instrument.py covering the disabled logs handler,
a user-supplied integration winning, sentry_default_integrations=False, both knobs reaching the
client, sentry_additional_params overriding, and the warning firing and staying quiet.

307 tests pass; ruff format, ruff check, ty and a strict mkdocs build are clean.

@lesnik512
lesnik512 force-pushed the feat/186-sentry-rps-knobs branch from 65559f2 to 78ff6ee Compare September 20, 2026 09:45
@lesnik512
lesnik512 merged commit 0b45991 into main Sep 20, 2026
13 checks passed
@lesnik512
lesnik512 deleted the feat/186-sentry-rps-knobs branch September 20, 2026 09:47
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.

Expose the Sentry settings that cost RPS (sentry_logs_level, breadcrumb level, auto_session_tracking)

1 participant