How xuhpppp/python-opentelemetry works
Project type and purpose
• This is a single‐service, full‐stack backend demo: a FastAPI “Order Service” instrumented with OpenTelemetry, packaged via Docker Compose alongside a PostgreSQL database and an observability stack (Jaeger, Prometheus, cAdvisor, Grafana). Its primary goal is to demonstrate how to collect metrics, logs, and traces from a Python FastAPI app.
File structure
• Top level:
• Dockerfile, docker-compose.yml, .env.example – container builds & orchestration
• init.sql – DB schema/data initialization
• setup/ – monitoring configuration (Grafana datasources, Prometheus rules)
• src/ – application code
• src/ substructure:
• src/main.py – FastAPI entrypoint
• src/config/databases.py – DB connection
• src/orders/ – feature module with models.py, routers.py, services.py, telemetries.py
• No frontend; it’s a backend microservice with a single domain (orders).
README for additional insights
• The README confirms the use of Docker Compose to stand up:
• FastAPI service (port 8080)
• PostgreSQL (5432)
• Jaeger UI (16686)
• cAdvisor (8081)
• Prometheus (9090)
• Grafana (implicitly via setup folder)
• An “Architecture” image is referenced, showing how telemetry flows from the app to the observability tools.
Main components & interactions
• User / Client
• FastAPI Order Service
• PostgreSQL Database
• OpenTelemetry SDK & Exporters (in-app)
• Jaeger Collector & UI
• Prometheus Server
• cAdvisor
• Grafana (dashboards)
• Docker Compose boundary (optional container grouping)
b. Relationships & data flows:
1. HTTP request → FastAPI
2. FastAPI → SQL queries → PostgreSQL
3. OpenTelemetry instrumentation in FastAPI captures:
– Traces → Jaeger
– Metrics → Prometheus (scraped at /metrics)
4. Prometheus also scrapes metrics from cAdvisor
5. Grafana reads from Prometheus (configured via setup/grafana-datasources.yml)
c. Architectural patterns:
– Single microservice with clear separation of concerns (routers, services, models, telemetry)
– Observability pipeline pattern: instrumentation → collectors → storage/visualization
d. Key technologies:
– Python & FastAPI
– OpenTelemetry SDK
– PostgreSQL
– Docker & Docker Compose
– Jaeger, Prometheus, cAdvisor, Grafana
Detail level
• Sub-component only if it adds clarity (e.g., “Orders Router” vs “Order Service”).
• Config files implicitly by noting “Prometheus config” and “Grafana datasource” pointing at the respective services.