Python Production Blueprint

A single-page guide to building, securing, observing, and deploying production-grade Python services.

Application Development DevOps DevSecOps Logging APM & Tracing Observability
View Reference Repo Explore Architecture

Architecture at a Glance

Hover or tap each layer to see the tools and best practices that power it.

Application Development

Python 3.11+FastAPIPydanticUvicornpyproject.tomlpytestruff

DevOps & Packaging

DockerDocker ComposeGitHub ActionsMulti-stage buildsHealth checks

DevSecOps & Compliance

TrivyBanditpip-auditGitleakspre-commitDependabot

Structured Logging

structlogpython-json-loggercorrelation IDsstdout + file

APM, Tracing & Metrics

OpenTelemetryPrometheusJaegerRED metricsSLOs

Observability Platform

VectorKafkaElasticsearchKibanaGrafana

Application Development

Build the service with modern, type-safe Python patterns that are easy to test and reason about.

Key Tools
Python 3.11+FastAPIPydanticUvicornpyproject.tomlpytestruffhttpx
Best Practices
  • Use an application factory and lifespan events.
  • Validate at the edge with Pydantic models.
  • Organize routes with APIRouter and version URLs with /api/v1/.
  • Write async tests with pytest-asyncio and httpx.
  • Lint and format with ruff; keep a single pyproject.toml.

Tools & Best Practices by Area

A reference of what to use and why, grouped by responsibility.

Application Development

  • Async-first APIs with FastAPI and Pydantic.
  • Type-safe config with pydantic-settings.
  • Application factory + lifespan for startup/shutdown.
  • Versioned routers, consistent error models.
  • Unit + integration tests with pytest and httpx.
FastAPIPydanticUvicornpyproject.tomlpytestruffpydantic-settings

DevOps & Packaging

  • Single source of truth in pyproject.toml.
  • Multi-stage Docker images; non-root user.
  • Docker Compose for local/dev parity.
  • CI pipeline: lint → test → SAST → build → scan.
  • Health, readiness, and metrics endpoints from day one.
DockerDocker ComposeGitHub ActionsBuildKitHealth checks

DevSecOps & Compliance

  • Shift-left with pre-commit hooks.
  • SAST with Bandit; secret scanning with Gitleaks.
  • Dependency auditing with pip-audit and Dependabot.
  • Container CVE scanning with Trivy.
  • Generate and track SBOMs for compliance.
TrivyBanditpip-auditGitleakspre-commitDependabot

Structured Logging

  • Emit JSON logs, not plain text.
  • Bind request-scoped correlation IDs.
  • Use stdout in containers; rotate files on hosts.
  • Log events, not sentences: item_created not "Item created".
  • Include context fields: request_id, user_id, duration_ms.
structlogpython-json-loggercontextvarsmiddleware

APM, Tracing & Metrics

  • Auto-instrument FastAPI with OpenTelemetry.
  • Collect RED metrics: Rate, Errors, Duration.
  • Send traces to Jaeger for latency analysis.
  • Define SLOs and alert on error budget burn.
  • Keep cardinality under control in metrics.
OpenTelemetryPrometheusJaegerRED methodSLOs

Observability Platform

  • Collect logs with lightweight Vector agents.
  • Buffer and fan-out with Kafka.
  • Parse, enrich, and route with Vector aggregators.
  • Store and search logs in Elasticsearch.
  • Visualize with Kibana dashboards and Grafana.
VectorKafkaElasticsearchKibanaGrafana

One-Page Best-Practice Checklist

The distilled rules that tie the blueprint together.

Do

  • Use an app factory and async lifespan events.
  • Validate all inputs with Pydantic.
  • Emit structured JSON logs with correlation IDs.
  • Instrument with OpenTelemetry and expose Prometheus metrics.
  • Containerize with multi-stage Docker builds.
  • Run security scans in CI and on schedule.
  • Store production secrets in Vault, not .env.
  • Define health/readiness endpoints.
  • Handle SIGTERM gracefully.

Avoid

  • Global app instances at module level.
  • Plain-text logs and print() debugging.
  • Hardcoded secrets or env files in production.
  • Blocking I/O inside async handlers.
  • Exposing Swagger docs in production.
  • Skipping linting, tests, or SAST in CI.
  • Unbounded log growth on disk.
  • Deploying without health checks.

Want the Code?

The reference repository implements this blueprint end-to-end.

python-production-blueprint