# rehansxcbom/fastapi-observability architecture

> Architecture diagram of the GitHub repository rehansxcbom/fastapi-observability, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rehansxcbom/fastapi-observability
- Repository: https://github.com/rehansxcbom/fastapi-observability

## Overview

This repository is a containerized FastAPI observability demo: clients submit metrics or exercise instrumented endpoints; the application stores metric records in TimescaleDB and emits telemetry for collection and exploration. The principal ingestion flow is client → FastAPI → TimescaleDB, with separate traces/metrics and container-log paths into Tempo, Prometheus, and Loki, then Grafana. The excerpts establish application behavior, while the README documents the broader stack; configuration files are represented as service nodes, not as inspected runtime code.

Main entry points: [`main.py`](https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py) (FastAPI API), [`etc/grafana/provisioning/datasources/datasources.yaml`](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/grafana/provisioning/datasources/datasources.yaml) (Grafana), [`etc/otel-collector/otel-collector-config.yaml`](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/otel-collector/otel-collector-config.yaml) (OTel Collector), [`etc/alloy/config.alloy`](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/alloy/config.alloy) (Alloy Log Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application"]
  node_api["FastAPI API<br/>[main.py]"]
  node_request_metrics["Request Metrics<br/>[main.py]"]
  node_metric_ingestion["Metric Ingestion<br/>[main.py]"]
  node_timescale[("TimescaleDB")]
end

subgraph group_collection["Telemetry Collection"]
  node_otel["OpenTelemetry SDK<br/>[main.py]"]
  node_collector["OTel Collector"]
  node_alloy["Alloy Log Agent<br/>[config.alloy]"]
end

subgraph group_backends["Observability Backends"]
  node_tempo[("Tempo Traces<br/>[tempo.yml]")]
  node_prometheus[("Prometheus Metrics<br/>[prometheus.yml]")]
  node_loki[("Loki Logs<br/>[loki.yml]")]
end

subgraph group_visualization["Visualization"]
  node_grafana["Grafana<br/>[datasources.yaml]"]
  node_dashboards["Dashboards"]
end

node_client(("API Client"))

node_client -->|"sends HTTP"| node_api
node_api -->|"dispatches metric routes"| node_metric_ingestion
node_metric_ingestion -->|"writes records"| node_timescale
node_api -->|"records requests"| node_request_metrics
node_request_metrics -->|"writes asynchronously"| node_timescale
node_api -->|"initializes schema"| node_timescale
node_api -->|"emits telemetry"| node_otel
node_otel -.->|"exports OTLP"| node_collector
node_collector -.->|"exports traces"| node_tempo
node_collector -.->|"exports metrics"| node_prometheus
node_api -.->|"writes container logs"| node_alloy
node_alloy -.->|"pushes logs"| node_loki
node_grafana -.->|"queries traces"| node_tempo
node_grafana -.->|"queries metrics"| node_prometheus
node_grafana -.->|"queries logs"| node_loki
node_grafana -.->|"queries SQL"| node_timescale
node_dashboards -->|"provisions dashboards"| node_grafana

click node_api "https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py"
click node_request_metrics "https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py"
click node_metric_ingestion "https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py"
click node_otel "https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py"
click node_collector "https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/otel-collector/otel-collector-config.yaml"
click node_alloy "https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/alloy/config.alloy"
click node_tempo "https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/tempo/tempo.yml"
click node_prometheus "https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/prometheus/prometheus.yml"
click node_loki "https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/loki/loki.yml"
click node_grafana "https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/grafana/provisioning/datasources/datasources.yaml"
click node_dashboards "https://github.com/rehansxcbom/fastapi-observability/tree/main/etc/grafana/provisioning/dashboards"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_request_metrics,node_metric_ingestion,node_timescale,node_client toneBlue
class node_otel,node_collector,node_alloy toneAmber
class node_tempo,node_prometheus,node_loki toneMint
class node_grafana,node_dashboards toneRose
```

## Components

### Application

- [FastAPI API](https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py): `main.py`
- [Request Metrics](https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py): `main.py`
- [Metric Ingestion](https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py): `main.py`
- **TimescaleDB**

### Telemetry Collection

- [OpenTelemetry SDK](https://github.com/rehansxcbom/fastapi-observability/blob/main/main.py): `main.py`
- [OTel Collector](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/otel-collector/otel-collector-config.yaml): `etc/otel-collector/otel-collector-config.yaml`
- [Alloy Log Agent](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/alloy/config.alloy): `etc/alloy/config.alloy`

### Observability Backends

- [Tempo Traces](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/tempo/tempo.yml): `etc/tempo/tempo.yml`
- [Prometheus Metrics](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/prometheus/prometheus.yml): `etc/prometheus/prometheus.yml`
- [Loki Logs](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/loki/loki.yml): `etc/loki/loki.yml`

### Visualization

- [Grafana](https://github.com/rehansxcbom/fastapi-observability/blob/main/etc/grafana/provisioning/datasources/datasources.yaml): `etc/grafana/provisioning/datasources/datasources.yaml`
- [Dashboards](https://github.com/rehansxcbom/fastapi-observability/tree/main/etc/grafana/provisioning/dashboards): `etc/grafana/provisioning/dashboards`

### Other components

- **API Client**

## Connections

- API Client → FastAPI API: sends HTTP
- FastAPI API → Metric Ingestion: dispatches metric routes
- Metric Ingestion → TimescaleDB: writes records
- FastAPI API → Request Metrics: records requests
- Request Metrics → TimescaleDB: writes asynchronously
- FastAPI API → TimescaleDB: initializes schema
- FastAPI API → OpenTelemetry SDK: emits telemetry
- OpenTelemetry SDK → OTel Collector: exports OTLP
- OTel Collector → Tempo Traces: exports traces
- OTel Collector → Prometheus Metrics: exports metrics
- FastAPI API → Alloy Log Agent: writes container logs
- Alloy Log Agent → Loki Logs: pushes logs
- Grafana → Tempo Traces: queries traces
- Grafana → Prometheus Metrics: queries metrics
- Grafana → Loki Logs: queries logs
- Grafana → TimescaleDB: queries SQL
- Dashboards → Grafana: provisions dashboards