OpenTelemetry FastAPI Boilerplate

A comprehensive boilerplate project for learning and implementing OpenTelemetry (OTEL) with FastAPI, featuring the Grafana LGTM Stack for full observability.

Project Structure

otel_test/
├── server/                    # FastAPI application with OTEL instrumentation
├── observability/            # Grafana LGTM Stack (Loki, Grafana, Tempo, Mimir)
└── README.md                 # This file

Features

• FastAPI Server with CRUD operations
• OpenTelemetry Instrumentation:
  • Automatic FastAPI instrumentation
  • Custom traces, spans, and span events
  • Custom metrics (counters, histograms)
  • Structured logging with trace correlation
  • Semantic attributes
• Grafana LGTM Stack:
  • Loki: Log aggregation
  • Grafana: Unified observability UI
  • Tempo: Distributed tracing
  • Mimir: Prometheus-compatible metrics storage
• OTEL Collector: Central telemetry data pipeline
• Development Tools:
  • VS Code Dev Containers
  • uv for package management
  • ruff for linting and formatting
  • pytest with full coverage

Quick Start

Prerequisites

• Docker and Docker Compose
• VS Code with Dev Containers extension (optional, for development)
• Python 3.14+ (if running locally without Docker)

1. Start the Observability Stack

cd observability
docker-compose up -d

This starts:

• Grafana on http://localhost:3000 (admin/admin)
• OTEL Collector on ports 4317 (gRPC) and 4318 (HTTP)
• Tempo, Loki, and Mimir (accessed via Grafana)

2. Run the FastAPI Server

Option A: Using Docker

cd server
docker-compose up --build

Option B: Using VS Code Dev Container

1. Open the server folder in VS Code
2. Click "Reopen in Container" when prompted
3. Run: uv run uvicorn src.main:app --reload --host 0.0.0.0

Option C: Local Development

cd server
uv sync
uv run uvicorn src.main:app --reload

3. Access the Services

• FastAPI: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Grafana: http://localhost:3000

Usage Examples

Create an Item

curl -X POST http://localhost:8000/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Item", "description": "A test item"}'

List Items

curl http://localhost:8000/items

Get Item by ID

curl http://localhost:8000/items/1

Update Item

curl -X PUT http://localhost:8000/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Item", "description": "Updated description"}'

Delete Item

curl -X DELETE http://localhost:8000/items/1

Observability

Viewing Traces in Grafana

1. Open Grafana at http://localhost:3000
2. Go to Explore → Select "Tempo" datasource
3. Search for traces or use TraceQL queries

Viewing Logs in Grafana

1. Go to Explore → Select "Loki" datasource
2. Use LogQL to query logs: {service_name="otel-fastapi-server"}
3. Logs are automatically correlated with traces

Viewing Metrics in Grafana

1. Go to Explore → Select "Mimir" datasource
2. Query custom metrics like items_created_total or items_deleted_total
3. Pre-configured dashboards are available

Development

Running Tests

cd server
uv run pytest

Running Tests with Coverage

cd server
uv run pytest --cov=src --cov-report=html

Linting and Formatting

cd server
uv run ruff check .
uv run ruff format .

Architecture

The project follows a clean architecture pattern:

• API Layer (src/api/): HTTP endpoints
• Service Layer (src/services/): Business logic
• Models (src/models/): Data models
• Telemetry (src/telemetry/): OTEL configuration and instrumentation

OpenTelemetry Features Demonstrated

1. Automatic Instrumentation: FastAPI requests/responses
2. Custom Spans: Service layer operations with parent-child relationships
3. Span Attributes: Custom and semantic attributes
4. Span Events: Marking significant operations
5. Custom Metrics: Counters and histograms
6. Structured Logging: JSON logs with trace context
7. Context Propagation: Trace IDs across service boundaries

License

MIT