Skip to content

Django Observability Stack

Django Prometheus Grafana Loki Python Docker

A complete tutorial & guide for building observability in Django applications

Start Tutorial View on GitHub

👋 Welcome

This project is a hands-on tutorial for adding observability to your Django applications. Whether you're a beginner or experienced developer, you'll learn how to:

  • 📊 Monitor metrics - Track request rates, latency, errors
  • 📝 Aggregate logs - Centralize logs from all services
  • 🔔 Set up alerts - Get notified when things go wrong
  • 📈 Visualize data - Create dashboards to understand your app
  • 🤖 Integrate AI - Use MCP server for AI-powered insights

🎯 What You'll Learn

By the end of this tutorial, you'll be able to

Skill What You'll Master
Metrics Auto-instrument Django with Prometheus
Logs Ship JSON logs to Loki with Promtail
Visualization Create Grafana dashboards
Alerting Set up Slack notifications for critical issues
Docker Containerize the entire stack
AI Integration Use MCP server for AI-powered analysis

🚀 Quick Start

Prerequisites

  • Docker Desktop installed
  • Basic Django knowledge
  • Terminal access

Get Started in 3 Steps

# 1. Clone the repository
git clone https://github.com/MdAshiqurRahmanZayed/django-observability.git
cd django-observability

# 2. Configure environment
cp django_app/.env.example django_app/.env

# 3. Start everything
docker compose -f django_app/docker-compose.yml up -d --build

Access Your Stack

Service URL What It Does
🌐 Django App http://localhost Your application
📊 Grafana http://localhost:3000 Dashboards & visualization
📈 Prometheus http://localhost:9090 Metrics & queries
🔔 Alertmanager http://localhost:9093 Alert routing
📝 Loki http://localhost:3100 Log aggregation
🗄️ pgAdmin http://localhost:5050 Database admin

📚 Tutorial Path

Follow these steps in order:

Step 1: Setup

→ Getting Started - Install and configure the stack

Step 2: Understand

→ Architecture Overview - Learn how everything connects

Step 3: Explore Modules

→ Django App - Understand the application

→ Prometheus - Learn metrics collection

→ Grafana - Create dashboards

→ Loki - Aggregate logs

→ Alertmanager - Set up alerts

Step 4: Advanced

→ MCP Server - AI integration

🏗️ Architecture at a Glance

Architecture Diagram

Application Metrics

Mermaid Code

graph TB
    subgraph "Application"
        U[Browser] --> N[Nginx :80]
        N --> D[Django :9000]
        D --> DB[(PostgreSQL)]
    end

    subgraph "Metrics"
        D -->|/metrics| P[Prometheus :9090]
        NE[Node Exporter] --> P
        P -->|alerts| AM[Alertmanager :9093]
        AM -->|notify| S[Slack]
    end

    subgraph "Logs"
        D -->|writes| PT[Promtail]
        PT -->|push| L[Loki :3100]
    end

    subgraph "Visualization"
        P --> G[Grafana :3000]
        L --> G
    end

Data Flow

Layer Component Flow
Application Browser → Nginx → Django → PostgreSQL HTTP requests
Metrics Django → Prometheus → Alertmanager → Slack /metrics scrape
Logs Django → Promtail → Loki JSON log push
Visualization Prometheus + Loki → Grafana Dashboards

📦 What's Included

Component Technology Purpose
Django App Python 5.x Todo application
Prometheus Latest Metrics collection
Grafana Latest Visualization
Loki 2.9.0 Log aggregation
Promtail 2.9.0 Log shipping
Alertmanager Latest Alert routing
Nginx Alpine Reverse proxy
PostgreSQL 16 Database
MCP Server Python AI integration

🎓 Who Is This For?

  • Django developers who want to monitor their applications
  • DevOps engineers setting up observability stacks
  • Students learning modern monitoring practices
  • Anyone interested in Prometheus, Grafana, and Loki

🤝 Contributing

We welcome contributions from the community! Whether you're fixing a bug, adding a feature, or improving documentation, your help makes this project better for everyone.

Ways to Contribute

Contribution Type Description
🐛 Bug Reports Found something broken? Let us know!
💡 Feature Requests Have an idea? We'd love to hear it!
📝 Documentation Improve guides, fix typos, add examples
🔧 Code Fix bugs, add features, improve tests
📷 Screenshots Add screenshots for different setups

How to Contribute

1. Fork & Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR-USERNAME/django-observability.git
cd django-observability

2. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

3. Make Changes

  • Follow existing code style
  • Add tests if applicable
  • Update documentation as needed

4. Test Your Changes

# Start the stack
docker compose -f django_app/docker-compose.yml up -d

# Verify everything works
curl http://localhost:9000/metrics
curl http://localhost:9090/-/healthy
curl http://localhost:3000/api/health

5. Submit a Pull Request

git add .
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Contribution Guidelines

  • ✅ Keep PRs focused on a single change
  • ✅ Write clear commit messages
  • ✅ Update documentation for new features
  • ✅ Test your changes before submitting
  • ✅ Be respectful and constructive

Getting Help

Contributors

Thank you to everyone who has contributed to this project! 🎉

View Contributors

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

This project is primarily for educational purposes - demonstrating observability best practices with Django.

Ready to start? 👇

Get Started Now