feat: add Grafana and Prometheus monitoring stack

README.md

@@ -198,6 +198,43 @@ Configuration is managed through `.env`. Environment variables can override thes
 
 API documentation is generated using Swagger. The documentation is available at `http://localhost:8080/swagger/index.html`.
 
+## 📊 Monitoring & Observability
+
+The template includes a comprehensive monitoring stack with Grafana and Prometheus:
+
+### Monitoring Stack
+
+- **Prometheus**: Time-series database for metrics collection
+- **Grafana**: Visualization and dashboard platform
+- **Jaeger**: Distributed tracing
+- **Application Metrics**: Built-in Prometheus metrics middleware
+
+### Quick Start for Monitoring
+
+1. Start the monitoring stack:
+
+```bash
+make docker_up
+```
+
+2. Access the monitoring tools:
+
+- **Grafana**: http://localhost:3000 (admin/admin)
+- **Prometheus**: http://localhost:9090
+- **Jaeger**: http://localhost:16686
+- **Application Metrics**: http://localhost:8080/metrics
+
+### Pre-configured Dashboards
+
+The template includes a pre-configured Grafana dashboard with:
+
+- Request rate and response time metrics
+- Error rates by status code
+- HTTP method distribution
+- 95th percentile response times
+
+For detailed monitoring setup instructions, see [monitoring/README.md](monitoring/README.md).
+
 ## Prometheus Metrics
 
 Prometheus metrics are exposed at `http://localhost:8080/metrics`.

docker-compose.yml

@@ -108,6 +108,50 @@ services:
     networks:
       - app_network
 
+  # ───────────────────────────────────────────────────────────
+  # 🌟 PROMETHEUS
+  # ───────────────────────────────────────────────────────────
+  prometheus:
+    image: prom/prometheus:latest
+    container_name: prometheus
+    restart: always
+    ports:
+      - "9090:9090"
+    volumes:
+      - ./monitoring/prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
+      - prometheus_data:/prometheus
+    command:
+      - '--config.file=/etc/prometheus/prometheus.yml'
+      - '--storage.tsdb.path=/prometheus'
+      - '--web.console.libraries=/etc/prometheus/console_libraries'
+      - '--web.console.templates=/etc/prometheus/consoles'
+      - '--storage.tsdb.retention.time=200h'
+      - '--web.enable-lifecycle'
+    networks:
+      - app_network
+
+  # ───────────────────────────────────────────────────────────
+  # 🌟 GRAFANA
+  # ───────────────────────────────────────────────────────────
+  grafana:
+    image: grafana/grafana:latest
+    container_name: grafana
+    restart: always
+    ports:
+      - "3000:3000"
+    environment:
+      - GF_SECURITY_ADMIN_USER=admin
+      - GF_SECURITY_ADMIN_PASSWORD=admin
+      - GF_USERS_ALLOW_SIGN_UP=false
+    volumes:
+      - grafana_data:/var/lib/grafana
+      - ./monitoring/grafana/provisioning:/etc/grafana/provisioning
+      - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards
+    depends_on:
+      - prometheus
+    networks:
+      - app_network
+
 
 # ───────────────────────────────────────────────────────────
 # 🌟 NETWORK & VOLUME CONFIGURATION
@@ -118,3 +162,5 @@ networks:
 volumes:
   db_data:
   redis_data:
+  prometheus_data:
+  grafana_data:

monitoring/README.md

@@ -0,0 +1,189 @@
+# Monitoring Setup with Grafana and Prometheus
+
+This directory contains the monitoring configuration for the Go REST API template using Grafana and Prometheus.
+
+## Overview
+
+The monitoring stack consists of:
+
+- **Prometheus**: Time-series database for storing metrics
+- **Grafana**: Visualization and dashboard platform
+- **Go Application**: Exposes metrics at `/metrics` endpoint
+
+## Architecture
+
+```sh
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│   Grafana   │◄───│  Prometheus │◄───│ Go App     │
+│   :3000     │    │   :9090     │    │ :8080      │
+└─────────────┘    └─────────────┘    └─────────────┘
+```
+
+## Metrics Collected
+
+The Go application exposes the following Prometheus metrics:
+
+- `http_requests_total`: Total number of HTTP requests (counter)
+- `http_request_duration_seconds`: HTTP request duration (histogram)
+
+These metrics are labeled with:
+
+- `code`: HTTP status code
+- `method`: HTTP method (GET, POST, etc.)
+- `path`: Request path
+
+## Getting Started
+
+### 1. Start the Monitoring Stack
+
+```bash
+# Start all services including monitoring
+docker-compose up -d
+
+# Or start only monitoring services
+docker-compose up -d prometheus grafana
+```
+
+### 2. Access the Services
+
+- **Grafana**: http://localhost:3000
+  - Username: `admin`
+  - Password: `admin`
+- **Prometheus**: http://localhost:9090
+- **Go Application**: http://localhost:8080
+- **Application Metrics**: http://localhost:8080/metrics
+
+### 3. Import Dashboard
+
+The Go REST API dashboard is automatically provisioned and includes:
+
+- Request rate over time
+- 95th percentile response time
+- Success/error rates by status code
+- Requests by HTTP method
+- Requests by status code
+
+## Configuration Files
+
+### Prometheus Configuration (`monitoring/prometheus/prometheus.yml`)
+
+- Scrapes metrics from the Go application every 5 seconds
+- Stores data for 200 hours
+- Includes Redis monitoring (optional)
+
+### Grafana Configuration
+
+- **Datasources**: Automatically configured to connect to Prometheus
+- **Dashboards**: Pre-configured dashboard for Go REST API monitoring
+- **Provisioning**: Automatic setup of datasources and dashboards
+
+## Customization
+
+### Adding Custom Metrics
+
+To add custom metrics to your Go application:
+
+```go
+import (
+    "github.com/prometheus/client_golang/prometheus"
+    "github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+    customCounter = promauto.NewCounter(prometheus.CounterOpts{
+        Name: "my_custom_counter",
+        Help: "Description of my custom counter",
+    })
+)
+```
+
+### Creating Custom Dashboards
+
+1. Access Grafana at http://localhost:3000
+2. Create a new dashboard
+3. Add panels with Prometheus queries
+4. Export the dashboard JSON and place it in `monitoring/grafana/dashboards/`
+
+### Alerting
+
+To set up alerts:
+
+1. Configure alerting rules in Prometheus
+2. Set up alert manager
+3. Configure notification channels in Grafana
+
+## Useful Prometheus Queries
+
+### Request Rate
+
+```promql
+rate(http_requests_total[5m])
+```
+
+### Error Rate
+
+```promql
+rate(http_requests_total{code=~"5.."}[5m])
+```
+
+### 95th Percentile Response Time
+
+```promql
+histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
+```
+
+### Success Rate
+
+```promql
+sum(rate(http_requests_total{code=~"2.."}[5m])) / sum(rate(http_requests_total[5m]))
+```
+
+## Troubleshooting
+
+### Prometheus Not Scraping Metrics
+
+1. Check if the Go application is running: `docker-compose ps`
+2. Verify metrics endpoint: `curl http://localhost:8080/metrics`
+3. Check Prometheus targets: http://localhost:9090/targets
+
+### Grafana Can't Connect to Prometheus
+
+1. Verify Prometheus is running: `docker-compose ps prometheus`
+2. Check Prometheus logs: `docker-compose logs prometheus`
+3. Verify network connectivity between containers
+
+### Dashboard Not Loading
+
+1. Check if the dashboard JSON is valid
+2. Verify the datasource is properly configured
+3. Check Grafana logs: `docker-compose logs grafana`
+
+## Production Considerations
+
+### Security
+
+- Change default Grafana credentials
+- Use environment variables for sensitive configuration
+- Consider using reverse proxy with authentication
+- Enable HTTPS for production deployments
+
+### Performance
+
+- Adjust Prometheus retention period based on storage requirements
+- Configure appropriate scrape intervals
+- Monitor Prometheus and Grafana resource usage
+- Consider using Prometheus federation for large deployments
+
+### High Availability
+
+- Use external storage for Prometheus data
+- Set up Prometheus federation
+- Configure Grafana with external database
+- Use load balancers for multiple instances
+
+## Additional Resources
+
+- [Prometheus Documentation](https://prometheus.io/docs/)
+- [Grafana Documentation](https://grafana.com/docs/)
+- [Prometheus Client Go](https://github.com/prometheus/client_golang)
+- [Grafana Dashboards](https://grafana.com/grafana/dashboards/)