edutap.observability_settings

Error reporting, tracing and structured logging, wired the same way in every eduTAP service — and one decision written down: what a service may say about a person.

Why this exists

Because the options are the point, not the code. Three lines would start Sentry. Which options those three lines carry decides whether a bearer token or a person's identifier leaves the process, and each of the options below was chosen against a measurement rather than against a backend's recommendation. Separated from the sentry_sdk.init() call that applies them, those measurements are worth nothing — which is why this is a package and not a paragraph in a README.

Because a person's identifier is not an opaque handle. At a university a person_uid resolves to a human being for far more people than hold directory administration rights; at the LMU it is the LMU identifier with @lmu.de appended. Pseudonymised it remains personal data. What a deployment decides here is not whether it is personal data but who may see it.

Which artefact is running

Set EDUTAP_RELEASE (or the per-service prefix a consumer uses) to the image tag of what is deployed:

EDUTAP_RELEASE: "2026-08-28_1859"

It reaches Sentry as release, and an error tracker needs it to answer the one question that follows every fix: is this still happening in what we shipped? Bugsink builds "resolved in the next release" on the same field.

Unset, the service_version passed to install_observability is used instead -- better than nothing, and honest about what it is: for a service that is typically a placeholder like 1.0.0.dev0 which stays the same across a hundred deployments.

Transport chatter is not a defect

Kafka clients log at ERROR for every failed connection attempt while a broker is unreachable -- and they retry, and they recover. Sentry's LoggingIntegration turns each of those records into an event. install_observability therefore silences the loggers listed in NOISY_LOGGERS for the tracker.

The trade-off is deliberate: a genuinely permanent broker outage produces no event in the tracker either. It produces log lines, it produces metrics, and the consumer's own failures report as before. An error tracker is for defects; an outage is for monitoring, and mixing the two is how a tracker becomes unread.

Usage

from edutap.observability_settings import install_observability, person_label

install_observability(service_name="lmu_edutap_worker")   # first thing in main()

log.warning("no view for person", person=person_label(uid, settings))

Call it before the service resolves the settings it needs to run, so that a process refusing to start is reported rather than silently absent. Nothing here can fail for want of a value.

FastAPI services

from edutap.observability_settings import install_observability, instrument_fastapi_safely

install_observability(service_name="edutap.image_service")
instrument_fastapi_safely(app)

Needs the fastapi extra. It exists because logfire.instrument_fastapi() exports the request path: a service whose identifier sits in its URL exports that identifier on every span, whatever person_uid_mode says. In omit and pseudonym the path attributes are replaced by the route template and captured endpoint arguments are dropped; in plain the call is a straight pass-through, because a deployment that asked to see identifiers gets to see them.

Configuration

One prefix for the whole estate, EDUTAP_. These fields are defined by an eduTAP package, and another university deploying them should not have to learn an LMU name.

Why the endpoint is not one of ours

A Sentry DSN names a project, so it belongs to the service and every service gets its own. An OTLP endpoint names a receiver, normally one per host or cluster, and which service sent a span rides in the resource attributes rather than in the address. Every OpenTelemetry SDK already reads OTEL_EXPORTER_OTLP_ENDPOINT by itself; a field under EDUTAP_ would be a second name for the same value.

A shared prefix means shared *names*, not shared *values*. `EDUTAP_SENTRY_DSN` differs
per service by being set in that service's own compose `environment:` block. Only
genuinely stack-wide values belong in the shared `.env`.

The three modes for a person

pseudonym without EDUTAP_PSEUDONYM_SALT yields nothing, never the raw value: a deployment that asked for pseudonyms and forgot the key has to lose the datum rather than publish it. An empty salt counts as no salt — compose writes ${VAR:-}, which sets a variable to the empty string, and an HMAC under an empty key is a plain digest of a small, enumerable value space and reversible by anyone who can hash the directory.

What the three backends do

Sentry takes errors. An OTLP collector takes traces, metrics and log records. structlog produces the events that reach both, and two bridges carry them to the collector:

• A log record per event, on the logs signal. This is what a log backend receives, with service name, environment, severity and the trace id of the span the event was written in. The body is the event as a string; every other field is an attribute, and anything that is not a scalar arrives as JSON. An exception arrives as exception.type, exception.message and exception.stacktrace.
• A zero-duration span per event, on the traces signal, made by logfire.StructlogProcessor. It keeps a trace showing what was logged inside it. Despite its name, this bridge does not produce log records.

Log records are only made with telemetry on and OTEL_EXPORTER_OTLP_ENDPOINT set. Every line still goes to stdout as JSON, so docker service logs keeps working. A deployment that also ships container logs to the same backend holds each line twice, distinguished by service_name; EDUTAP_EXPORT_LOG_RECORDS=false turns the records off where that is not wanted.

The records leave only because logfire attaches an OTLP log exporter to the logger
provider it registers. That is logfire's internal wiring, not a documented contract.
`tests/test_log_records.py` sends real OTLP to a loopback receiver, so a logfire
upgrade that changes it fails the suite instead of losing the logs silently.

Nothing travels two paths: Sentry's own tracing stays off (traces_sample_rate=0), because the spans already go to the collector and Bugsink — the tracker this estate runs — states that it does not support traces.

`send_to_logfire=False` is not a detail. The library defaults it to `True`, so leaving
it unset would ship spans to a hosted third party the first time a token happened to
be present.

While no collector exists, the console stands in. Measured against logfire 4.40: with send_to_logfire=False and no OTEL_EXPORTER_OTLP_ENDPOINT, no exporter is installed at all, so an instrumented service would be indistinguishable from an uninstrumented one — which is how instrumentation reaches production broken. Once the endpoint is set, the console stands down.

Development

make venv
make lint
make test-local

tox runs the suite across every supported Python version.

Design records

Under docs/superpowers/specs/.