edutap.observability-settings 0.1.3__tar.gz

edutap_observability_settings-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Nothing here is locked: uv.lock is git-ignored and every requirement is a lower
+  # bound. A suite that passed last week can fail today with nothing changed here.
+  schedule:
+    - cron: "17 5 * * 1"
+  # Callable, so the release workflow runs *these* checks rather than its own copy.
+  # A release gate that drifts from CI is a gate that passes what CI would have
+  # stopped -- and it drifts silently, because nobody reads two files side by side.
+  workflow_call:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: .venv/bin/python -m pytest -v
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: .venv/bin/python -m ruff check src tests
+      - run: .venv/bin/python -m ruff format --check src tests
+      - run: .venv/bin/python -m ty check src

edutap_observability_settings-0.1.3/.github/workflows/release.yaml

@@ -0,0 +1,90 @@
+---
+name: Build & upload PyPI package
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  release:
+    types:
+      - published
+  workflow_dispatch:
+
+# Without ``github.event_name`` in the group, the ``push`` event fired
+# by tagging a release and the ``release`` event fired by publishing
+# it land in the same group. ``cancel-in-progress: true`` then kills
+# whichever arrived second — typically the ``release`` run that
+# uploads to pypi.org, leaving the tag unpublished.
+concurrency:
+  group: release-${{ github.ref }}-${{ github.event_name }}
+  cancel-in-progress: true
+
+jobs:
+  # The repository's own CI, called rather than copied. A release gate that
+  # restates the checks drifts from them, and it drifts silently.
+  tests:
+    uses: "./.github/workflows/ci.yml"
+
+  # Always build & lint package.
+  build-package:
+    name: Build & verify package
+    needs:
+      - tests
+    runs-on: ubuntu-latest
+    permissions:
+      attestations: write
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: hynek/build-and-inspect-python-package@v3.0.1
+        with:
+          attest-build-provenance-github: 'true'
+
+  # Upload to Test PyPI on every commit on main.
+  release-test-pypi:
+    name: Publish in-dev package to test.pypi.org
+    environment: release-test-pypi
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs:
+      - build-package
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download packages built by build-and-inspect-python-package
+        uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+
+      - name: Upload package to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # Upload to real PyPI on GitHub Releases.
+  release-pypi:
+    name: Publish released package to pypi.org
+    environment: release-pypi
+    if: github.event.action == 'published'
+    runs-on: ubuntu-latest
+    needs:
+      - build-package
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download packages built by build-and-inspect-python-package
+        uses: actions/download-artifact@v8
+        with:
+          name: Packages
+          path: dist
+
+      - name: Upload package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

edutap_observability_settings-0.1.3/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/
+.env
+docs/_build/
+uv.lock
+
+.superpowers/
+
+# mutmut copies the whole project here to run the suite against each mutant.
+mutants/

edutap_observability_settings-0.1.3/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml

edutap_observability_settings-0.1.3/CLAUDE.md

@@ -0,0 +1,85 @@
+# CLAUDE.md — edutap.observability_settings
+
+Repository-specific rules. They take precedence over the global defaults.
+
+## Language
+
+**English only.** This repository belongs to eduTAP proper, not to any single
+institution: README, changelog, documentation, docstrings, code comments, commit
+messages, pull request titles and bodies, and replies to review comments.
+
+The language follows the repository, not the conversation. A discussion held in
+German still produces English artefacts here.
+
+## What this package is
+
+Error reporting, tracing and structured logging, wired the same way in every eduTAP
+service, plus the decision about what a service may say about a person. It is
+installed before a service resolves its own settings.
+
+## Guard rails
+
+**Every option here is a decision about what leaves the process.** The Sentry options
+are not defaults someone liked; each was chosen against a measurement and each
+contradicts the backend's own recommendation. Changing one means repeating the
+measurement and recording it, not reasoning about it.
+
+**`pseudonym` without a salt yields nothing, never the raw value.** A deployment that
+asked for pseudonyms and forgot the key has to lose the datum. Any code path that
+falls back to the plain `person_uid` defeats the whole package.
+
+**`send_to_logfire` stays `False`.** The library defaults it to `True`. This estate
+exports to its own collector, and an unset value ships spans to a hosted third party
+the first time a token happens to be present.
+
+**Never import from an eduTAP service.** This is installed before a service resolves
+its settings; it can know nothing about them. Depending on `edutap.data_models` is
+the one exception, and it is a library.
+
+**Options are returned before they are applied.** `sentry_options` and
+`logfire_options` are pure so a test can assert the exact set rather than assert that
+something was configured. Do not inline them into the `init` call.
+
+**No `uv.lock`.** This is a library; pinning here would push a resolution onto every
+consumer.
+
+## Working practice
+
+Branch first, never commit on `main`. Push only when asked. `make lint` and
+`make test-local` green before opening a pull request.
+
+Design records live under `docs/superpowers/`. They are records of a decision at a
+point in time — do not rewrite them to match a later state; write a new one.
+
+## Sources and confidentiality
+
+
+**No vendor internals — from any vendor, not just the ones currently in play.**
+Neither in files nor in commit messages.
+
+The standard is academic: a statement counts as reliable only where it can be
+evidenced from public information, with a link. Everything else was obtained either
+by our own testing or through insider knowledge, and the three are not
+interchangeable:
+
+* **Documented** — public source, linked. May be written as fact.
+* **Verified, not citable** — obtained by a person from an access-protected area and
+  checked there; the reference is recorded internally but must not be published; and
+  the statement has been reduced to what is not confidential. May be written as fact,
+  carrying this label. It is the rule journalism uses for source protection: the claim
+  stands, we know where it comes from, the reader does not get the source.
+
+  The four conditions hold together. A statement for which nobody can name the
+  internal reference does not fall here — that is insider knowledge.
+* **Measured** — established by our own tests. May be written down, but always marked
+  as such, because it describes what a platform did on the day we looked, not what it
+  guarantees. It can change with the next release, without notice and without an
+  entry in any changelog.
+* **Insider knowledge** — is not written down at all.
+
+What a platform's behaviour *means for us* stays documentable even where the
+mechanism does not: "the platform enforces a deadline, it is self-healing, it is
+outside our control" carries the design consequence without disclosing anything.
+
+Contract and regulatory material is wanted and citable: eduPersonAssurance, GÉANT and
+eduGAIN terms, published wallet programme obligations.

edutap_observability_settings-0.1.3/LICENSE

@@ -0,0 +1,11 @@
+SPDX-License-Identifier: EUPL-1.2
+
+Licensed under the European Union Public Licence, Version 1.2 (the "EUPL").
+
+You may obtain a copy of the licence at:
+
+    https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
+WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

edutap_observability_settings-0.1.3/Makefile

@@ -0,0 +1,25 @@
+PYTHON := .venv/bin/python
+VENV   := .venv
+
+.DEFAULT_GOAL := help
+.PHONY: help venv lint reformat test-local
+
+help: ## Show available targets
+	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+		| awk -F':.*?## ' '{printf "  %-14s %s\n", $$1, $$2}'
+
+venv: ## Create .venv and install the package with its dev extra
+	test -d $(VENV) || uv venv
+	uv pip install -U -e ".[dev]"
+
+lint: venv ## Run ruff checks and the type checker
+	$(PYTHON) -m ruff check src tests
+	$(PYTHON) -m ruff format --check src tests
+	$(PYTHON) -m ty check src
+
+reformat: venv ## Autoformat and autofix
+	$(PYTHON) -m ruff format src tests
+	$(PYTHON) -m ruff check --fix src tests
+
+test-local: venv ## Run the test suite
+	$(PYTHON) -m pytest -v

edutap_observability_settings-0.1.3/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: edutap.observability_settings
+Version: 0.1.3
+Summary: Error reporting, tracing and structured logging, wired the same way in every eduTAP service
+Project-URL: Source, https://github.com/edutap-collective/edutap.observability_settings
+Project-URL: Issues, https://github.com/edutap-collective/edutap.observability_settings/issues
+Author: eduTAP
+License-Expression: EUPL-1.2
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: edutap-data-models<0.3,>=0.2.1
+Requires-Dist: logfire>=4.40
+Requires-Dist: pydantic-settings>=2.4
+Requires-Dist: pydantic>=2.8
+Requires-Dist: sentry-sdk>=2.67
+Requires-Dist: structlog>=25
+Provides-Extra: dev
+Requires-Dist: pdbp; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx>=8; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# 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*.
+
+## Usage
+
+```python
+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.
+
+## 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.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `EDUTAP_ENVIRONMENT` | `production` | Labels every event and every span. Unset must not masquerade as development. |
+| `EDUTAP_TELEMETRY_ENABLED` | `true` | The deliberate off switch for tracing, metrics and log export. |
+| `EDUTAP_LOG_LEVEL` | `INFO` | A closed set; a misspelled level fails at startup. |
+| `EDUTAP_SENTRY_DSN` | unset | Unset means no error tracker. One project per service. |
+| `EDUTAP_PSEUDONYM_SALT` | unset | The HMAC key behind the person pseudonym. Without it there is no pseudonym at all. |
+| `EDUTAP_PERSON_UID_MODE` | `pseudonym` | `pseudonym` · `plain` · `omit` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | **Not** an `EDUTAP_` field — see below. |
+
+### 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.
+
+```{note}
+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
+
+| Mode | What travels | When it is right |
+|---|---|---|
+| `pseudonym` | a keyed, 12-character label | The default. Correlation survives — forty errors about one person still read as one person — identification does not. |
+| `plain` | the `person_uid` itself | Where the error tracker is read by exactly the people who may read the directory anyway. A configured decision, not an accident. |
+| `omit` | nothing | Where the tracker is read more widely than the directory. |
+
+`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 and metrics. structlog produces
+the records that reach both, bridged by `logfire.StructlogProcessor`, so a log line
+and the span it happened inside share a trace id without the caller doing anything.
+
+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.
+
+```{important}
+`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
+
+```shell
+make venv
+make lint
+make test-local
+```
+
+`tox` runs the suite across every supported Python version.
+
+## Design records
+
+Under [`docs/superpowers/specs/`](docs/superpowers/specs/).

edutap_observability_settings-0.1.3/README.md

@@ -0,0 +1,112 @@
+# 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*.
+
+## Usage
+
+```python
+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.
+
+## 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.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `EDUTAP_ENVIRONMENT` | `production` | Labels every event and every span. Unset must not masquerade as development. |
+| `EDUTAP_TELEMETRY_ENABLED` | `true` | The deliberate off switch for tracing, metrics and log export. |
+| `EDUTAP_LOG_LEVEL` | `INFO` | A closed set; a misspelled level fails at startup. |
+| `EDUTAP_SENTRY_DSN` | unset | Unset means no error tracker. One project per service. |
+| `EDUTAP_PSEUDONYM_SALT` | unset | The HMAC key behind the person pseudonym. Without it there is no pseudonym at all. |
+| `EDUTAP_PERSON_UID_MODE` | `pseudonym` | `pseudonym` · `plain` · `omit` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | unset | **Not** an `EDUTAP_` field — see below. |
+
+### 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.
+
+```{note}
+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
+
+| Mode | What travels | When it is right |
+|---|---|---|
+| `pseudonym` | a keyed, 12-character label | The default. Correlation survives — forty errors about one person still read as one person — identification does not. |
+| `plain` | the `person_uid` itself | Where the error tracker is read by exactly the people who may read the directory anyway. A configured decision, not an accident. |
+| `omit` | nothing | Where the tracker is read more widely than the directory. |
+
+`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 and metrics. structlog produces
+the records that reach both, bridged by `logfire.StructlogProcessor`, so a log line
+and the span it happened inside share a trace id without the caller doing anything.
+
+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.
+
+```{important}
+`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
+
+```shell
+make venv
+make lint
+make test-local
+```
+
+`tox` runs the suite across every supported Python version.
+
+## Design records
+
+Under [`docs/superpowers/specs/`](docs/superpowers/specs/).

edutap_observability_settings-0.1.3/docs/superpowers/README.md

@@ -0,0 +1,15 @@
+# Design records (Claude/Superpowers documents)
+
+* **Spec** (`specs/YYYY-MM-DD-<topic>-design.md`) — the design worked out in dialogue.
+* **Plan** (`plans/YYYY-MM-DD-<topic>.md`) — the implementation derived from it.
+
+| Date | Topic | Spec |
+|---|---|---|
+| 2026-08-10 | Why this package exists, the three backends, and what may be said about a person | [`specs/2026-08-10-observability-settings-design.md`](specs/2026-08-10-observability-settings-design.md) |
+
+Records are snapshots of a decision at a point in time. They are not rewritten to
+match a later state; a changed decision gets a new record.
+
+The Sentry half of the design is inherited rather than invented here: the options and
+the measurements behind them come from `edutap.data_provider`,
+`docs/superpowers/specs/2026-08-04-observability-design.md`.