diff --git a/docs/adr/0006-structlog-sentry-seam-stays-a-heuristic.md b/docs/adr/0006-structlog-sentry-seam-stays-a-heuristic.md index b1b2d1d..ee3e26c 100644 --- a/docs/adr/0006-structlog-sentry-seam-stays-a-heuristic.md +++ b/docs/adr/0006-structlog-sentry-seam-stays-a-heuristic.md @@ -15,6 +15,16 @@ subclass without changing the JSON. Independent structlog configurations can opt into that renderer too. Sentry recognizes the marked `LogRecord.msg` even when `event` is absent or non-string; unmarked JSON in those cases stays unchanged. +This recognition covers issue events and breadcrumbs. Opt-in Sentry Logs stays +caller-managed: sentry-sdk 2.70.0 and 2.73.0 pass `before_send_log` an empty hint and +a plain string body, losing the original `LogRecord.msg` marker. Both structlog and +stdlib records carry `sentry.origin="auto.log.stdlib"`. Automatic recognition would +therefore rewrite indistinguishable stdlib JSON or require a global logging patch. +Keep the hook unchanged and document the limit in the migration guide +([#452](https://github.com/modern-python/lite-bootstrap/issues/452), +[SDK handler](https://github.com/getsentry/sentry-python/blob/2.70.0/sentry_sdk/integrations/logging.py), +[SDK hook](https://github.com/getsentry/sentry-python/blob/2.73.0/sentry_sdk/client.py)). + The trap worth knowing before "fixing" it: structlog's own idiomatic `ProcessorFormatter.wrap_for_formatter` is incompatible with this seam. It defers rendering to handler-flush time, so `record.msg` is an `EventDict`, `sentry_sdk` builds `logentry.formatted` from diff --git a/docs/introduction/configuration.md b/docs/introduction/configuration.md index 25715a9..9be8f18 100644 --- a/docs/introduction/configuration.md +++ b/docs/introduction/configuration.md @@ -72,6 +72,12 @@ Two ways to opt out of the appended integration: supply your own `LoggingIntegra `sentry_default_integrations=False`, which suppresses it along with every other default integration. Under either, `sentry_logging_breadcrumb_level` is ignored and lite-bootstrap warns. +Built-in redaction and `skip_sentry` apply to issue events and breadcrumbs, not opt-in +Sentry Logs. A custom `LoggingIntegration` can send raw JSON and suppressed records +through Logs. Keep Logs disabled or handle redaction and suppression in +`sentry_additional_params["before_send_log"]`, which is passed unchanged. See the +[Sentry Logs contract](../migration/to-2.x.md#opt-in-sentry-logs). + ### Sentry auto-enabling integrations sentry-sdk enables an integration for every installed package it has one for: the web frameworks, diff --git a/docs/migration/to-2.x.md b/docs/migration/to-2.x.md index eae923a..dd4477d 100644 --- a/docs/migration/to-2.x.md +++ b/docs/migration/to-2.x.md @@ -220,6 +220,20 @@ its contents alone cannot distinguish structlog from unrelated stdlib JSON FastStream isolates message scopes. Set tags and breadcrumbs per message ([#409](https://github.com/modern-python/lite-bootstrap/pull/409)). +### Opt-in Sentry Logs + +Built-in redaction and `skip_sentry` cover issue events and breadcrumbs only. +Sentry Logs is disabled by default. If you opt in through a custom +`LoggingIntegration`, Logs can contain raw rendered JSON, including sensitive fields +and records marked `skip_sentry=True`. `SentryJSONRenderer` does not protect this +channel ([#452](https://github.com/modern-python/lite-bootstrap/issues/452)). + +Keep Logs disabled or supply application-specific redaction and suppression through +`sentry_additional_params["before_send_log"]`; lite-bootstrap passes that callback +unchanged. `before_send` and `before_breadcrumb` do not process Logs. The Logs hook +receives a plain string body without the original `LogRecord`, so it cannot reliably +distinguish structlog from identical stdlib JSON. + ### Sessions and breadcrumbs Session tracking defaults to off; HTTP crash-free session/user rates stop. diff --git a/tests/instruments/test_sentry_instrument.py b/tests/instruments/test_sentry_instrument.py index b1cce58..fb4ec87 100644 --- a/tests/instruments/test_sentry_instrument.py +++ b/tests/instruments/test_sentry_instrument.py @@ -10,6 +10,7 @@ import pytest import sentry_sdk import structlog +from sentry_sdk.envelope import Envelope from sentry_sdk.integrations.logging import LoggingIntegration from lite_bootstrap.instruments.logging_instrument import LoggingConfig, LoggingInstrument, SentryJSONRenderer @@ -784,6 +785,63 @@ def before_send(event: "sentry_types.Event", _: "sentry_types.Hint") -> "sentry_ sentry.teardown() +@pytest.mark.parametrize("capture_sentry_logs", [False, True], ids=["enable-logs", "capture-sentry-logs"]) +def test_opt_in_sentry_logs_leave_rendered_json_to_the_caller( + minimal_sentry_config: SentryConfig, + sentry_mock: SentryTestTransport, + capsys: pytest.CaptureFixture[str], + *, + capture_sentry_logs: bool, +) -> None: + marker = uuid.uuid4().hex + captured_logs: list[tuple[sentry_types.Log, sentry_types.Hint]] = [] + + def before_send_log(log: "sentry_types.Log", hint: "sentry_types.Hint") -> "sentry_types.Log": + captured_logs.append((copy.deepcopy(log), hint.copy())) + return log + + config = dataclasses.replace( + minimal_sentry_config, + sentry_integrations=[ + LoggingIntegration(capture_sentry_logs=True) if capture_sentry_logs else LoggingIntegration() + ], + sentry_additional_params={ + **minimal_sentry_config.sentry_additional_params, + "enable_logs": not capture_sentry_logs, + "before_send_log": before_send_log, + }, + ) + sentry = SentryInstrument(bootstrap_config=config) + logs = LoggingInstrument(bootstrap_config=LoggingConfig()) + sentry.bootstrap() + logs.bootstrap() + try: + logger.error(password=marker, component="worker") + logger.error("suppressed", password=marker, skip_sentry=True) + first_line, skipped_line = capsys.readouterr().out.splitlines() + assert json.loads(first_line)["password"] == marker + assert json.loads(skipped_line)["skip_sentry"] is True + (issue,) = sentry_mock.mock_envelopes + assert marker.encode() not in issue.serialize() + std_logger.error(first_line) + sentry_sdk.flush() + + assert [log["body"] for log, _ in captured_logs] == [first_line, skipped_line, first_line] + assert all(type(log["body"]) is str and hint == {} for log, hint in captured_logs) + assert all(log["attributes"]["sentry.origin"] == "auto.log.stdlib" for log, _ in captured_logs) + entries = [ + entry + for envelope in sentry_mock.mock_envelopes + for item in Envelope.deserialize(envelope.serialize()).items + if item.type == "log" + for entry in json.loads(item.get_bytes())["items"] + ] + assert [entry["body"] for entry in entries] == [first_line, skipped_line, first_line] + finally: + logs.teardown() + sentry.teardown() + + @pytest.mark.parametrize("template", ["plain %s", "{invalid %s", '{"unrelated":"%s"}']) def test_unstructured_log_keeps_sdk_truncation( minimal_sentry_config: SentryConfig, sentry_mock: SentryTestTransport, template: str