craftainer-observability

Observability building blocks for FastAPI services: a health check framework with /live and /ready routes and generic dependency checks, structured JSON logging, OpenTelemetry traces and metrics, a request-ID middleware and opt-in request profiling. It is extracted from template-fastapi and is an instance of template-python-package (see docs/TEMPLATE.md for the conventions shared with every instance). It never imports an application package or craftainer_crud; an import-linter contract enforces that.

Install

The distribution is craftainer-observability, the import package craftainer_observability. The core needs FastAPI only; everything else is an extra, so install what you use:

pip install craftainer-observability                    # health framework, request IDs
pip install "craftainer-observability[otel,redis]"      # plus tracing/metrics/logs, Redis check

logs.py and otel.py import OpenTelemetry at module level, so import them only when [otel] is installed. The package root, health and middleware import with no extra installed (a unit test proves it). Note that opentelemetry-sqlalchemy instrumentation supports SQLAlchemy below 2.1 only, hence the <2.1 bound.

Public API

The details, environment variables and conventions are in src/craftainer_observability/README.md.

Versioning

SemVer, starting at 0.1.0. While the major version is 0, a minor release may change the public API; pin craftainer-observability>=0.x,<0.(x+1) until 1.0. Real-service integration tests for the dependency checks stay in template-fastapi; the unit tests here use fakes and need no backing service.

Development

uv sync
prek run --all-files --hook-stage manual   # lint, types, import contracts, unit tests (100% coverage)
uv run pytest tests/bench --no-cov         # benchmarks (CodSpeed in CI)

Publishing to PyPI

Releases use PyPI trusted publishing (GitHub OIDC): no API token is stored anywhere. make publish is a no-op until you opt in, per repository:

1. Register a "pending publisher" on the index before the first release (PyPI: Your account, Publishing, "Add a new pending publisher"; TestPyPI has its own, separate form on test.pypi.org). Enter the project name from pyproject.toml, the GitHub owner and repository, the workflow name release.yml, and leave the environment empty (or use the one release.yml runs under, if you add one).
2. Set the repository variable PYPI_PUBLISH (Settings, Secrets and variables, Actions, Variables):
   • unset: make publish prints a skip message and the release only attaches the sdist, wheel and SBOM to the GitHub release;
   • testpypi: publish to TestPyPI;
   • pypi: publish to PyPI.
3. Do the first release with testpypi as a dry run (a pre-release channel is enough), confirm that make release-check installs the published version back from TestPyPI, then register the PyPI pending publisher and switch the variable to pypi.

The version lives only in the git tag release.yml computes; pyproject.toml stays at 0.0.0 and make build stamps RELEASE_VERSION into the build without committing it.

License

Licensed under the GNU General Public License v3.0.