Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/adr/0006-structlog-sentry-seam-stays-a-heuristic.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/introduction/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
14 changes: 14 additions & 0 deletions docs/migration/to-2.x.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
58 changes: 58 additions & 0 deletions tests/instruments/test_sentry_instrument.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading