@mytechtoday/augment-extensions 1.4.0 → 1.5.0

package/augment-extensions/coding-standards/go/rules/microservices/metrics.md

@@ -0,0 +1,278 @@
+# Go Microservices - Metrics and Monitoring
+
+## Overview
+
+Metrics enable monitoring and observability of microservices. This document defines best practices for implementing Prometheus metrics in Go microservices.
+
+## Core Principles
+
+1. **RED Method**: Track Rate, Errors, Duration for all services
+2. **Metric Types**: Use appropriate metric types (Counter, Gauge, Histogram, Summary)
+3. **Labels**: Add relevant labels for filtering and aggregation
+4. **Naming**: Follow Prometheus naming conventions
+5. **Performance**: Minimize overhead in hot paths
+
+## Rules
+
+### GOL.3.2.4.1: Implement RED Metrics
+
+**Rule**: Track Rate, Errors, and Duration for all service endpoints.
+
+**Severity**: WARNING
+
+**Rationale**: RED metrics provide essential service health indicators.
+
+**✅ Good**:
+```go
+import (
+    "github.com/prometheus/client_golang/prometheus"
+    "github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+    // Rate: Total requests
+    requestsTotal = promauto.NewCounterVec(
+        prometheus.CounterOpts{
+            Name: "service_requests_total",
+            Help: "Total number of requests",
+        },
+        []string{"method", "endpoint", "status"},
+    )
+    
+    // Errors: Failed requests
+    requestsErrors = promauto.NewCounterVec(
+        prometheus.CounterOpts{
+            Name: "service_requests_errors_total",
+            Help: "Total number of failed requests",
+        },
+        []string{"method", "endpoint", "error_type"},
+    )
+    
+    // Duration: Request latency
+    requestDuration = promauto.NewHistogramVec(
+        prometheus.HistogramOpts{
+            Name:    "service_request_duration_seconds",
+            Help:    "Request duration in seconds",
+            Buckets: prometheus.DefBuckets,
+        },
+        []string{"method", "endpoint"},
+    )
+)
+
+func instrumentHandler(method, endpoint string, handler func() error) error {
+    start := time.Now()
+    
+    err := handler()
+    
+    duration := time.Since(start).Seconds()
+    requestDuration.WithLabelValues(method, endpoint).Observe(duration)
+    
+    status := "success"
+    if err != nil {
+        status = "error"
+        requestsErrors.WithLabelValues(method, endpoint, err.Error()).Inc()
+    }
+    
+    requestsTotal.WithLabelValues(method, endpoint, status).Inc()
+    
+    return err
+}
+```
+
+### GOL.3.2.4.2: Use Appropriate Metric Types
+
+**Rule**: Choose the correct Prometheus metric type for each use case.
+
+**Severity**: ERROR
+
+**Rationale**: Wrong metric types lead to incorrect aggregations and alerts.
+
+**Metric Types**:
+- **Counter**: Monotonically increasing values (requests, errors)
+- **Gauge**: Values that can go up or down (active connections, queue size)
+- **Histogram**: Distribution of values (request duration, response size)
+- **Summary**: Similar to histogram but calculates quantiles client-side
+
+**✅ Good**:
+```go
+var (
+    // Counter: Monotonically increasing
+    httpRequestsTotal = promauto.NewCounter(prometheus.CounterOpts{
+        Name: "http_requests_total",
+        Help: "Total HTTP requests",
+    })
+    
+    // Gauge: Can increase or decrease
+    activeConnections = promauto.NewGauge(prometheus.GaugeOpts{
+        Name: "active_connections",
+        Help: "Number of active connections",
+    })
+    
+    // Histogram: Distribution of values
+    requestSize = promauto.NewHistogram(prometheus.HistogramOpts{
+        Name:    "http_request_size_bytes",
+        Help:    "HTTP request size in bytes",
+        Buckets: prometheus.ExponentialBuckets(100, 10, 8),
+    })
+)
+
+func handleRequest(w http.ResponseWriter, r *http.Request) {
+    httpRequestsTotal.Inc()
+    activeConnections.Inc()
+    defer activeConnections.Dec()
+    
+    requestSize.Observe(float64(r.ContentLength))
+    
+    // Handle request...
+}
+```
+
+### GOL.3.2.4.3: Instrument gRPC Services
+
+**Rule**: Add Prometheus metrics to all gRPC methods.
+
+**Severity**: WARNING
+
+**✅ Good**:
+```go
+var (
+    grpcRequestsTotal = promauto.NewCounterVec(
+        prometheus.CounterOpts{
+            Name: "grpc_requests_total",
+            Help: "Total gRPC requests",
+        },
+        []string{"method", "status"},
+    )
+    
+    grpcRequestDuration = promauto.NewHistogramVec(
+        prometheus.HistogramOpts{
+            Name:    "grpc_request_duration_seconds",
+            Help:    "gRPC request duration",
+            Buckets: prometheus.DefBuckets,
+        },
+        []string{"method"},
+    )
+)
+
+func metricsUnaryInterceptor() grpc.UnaryServerInterceptor {
+    return func(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
+        start := time.Now()
+        
+        resp, err := handler(ctx, req)
+        
+        duration := time.Since(start).Seconds()
+        grpcRequestDuration.WithLabelValues(info.FullMethod).Observe(duration)
+        
+        status := "success"
+        if err != nil {
+            status = "error"
+        }
+        grpcRequestsTotal.WithLabelValues(info.FullMethod, status).Inc()
+        
+        return resp, err
+    }
+}
+```
+
+### GOL.3.2.4.4: Expose Metrics Endpoint
+
+**Rule**: Expose Prometheus metrics on `/metrics` endpoint.
+
+**Severity**: ERROR
+
+**Rationale**: Enables Prometheus to scrape metrics.
+
+**✅ Good**:
+```go
+import (
+    "github.com/prometheus/client_golang/prometheus/promhttp"
+)
+
+func setupRoutes() http.Handler {
+    r := chi.NewRouter()
+    
+    // Metrics endpoint
+    r.Handle("/metrics", promhttp.Handler())
+    
+    // Application routes
+    r.Get("/api/users", handleUsers)
+    
+    return r
+}
+```
+
+### GOL.3.2.4.5: Add Business Metrics
+
+**Rule**: Track business-specific metrics beyond technical metrics.
+
+**Severity**: INFO
+
+**✅ Good**:
+```go
+var (
+    ordersCreated = promauto.NewCounter(prometheus.CounterOpts{
+        Name: "orders_created_total",
+        Help: "Total orders created",
+    })
+    
+    orderValue = promauto.NewHistogram(prometheus.HistogramOpts{
+        Name:    "order_value_dollars",
+        Help:    "Order value in dollars",
+        Buckets: prometheus.LinearBuckets(0, 50, 20),
+    })
+    
+    userRegistrations = promauto.NewCounterVec(
+        prometheus.CounterOpts{
+            Name: "user_registrations_total",
+            Help: "Total user registrations",
+        },
+        []string{"source"},
+    )
+)
+
+func (s *OrderService) CreateOrder(ctx context.Context, order *Order) error {
+    // Create order...
+    
+    // Track business metrics
+    ordersCreated.Inc()
+    orderValue.Observe(order.Total)
+    
+    return nil
+}
+
+func (s *UserService) RegisterUser(ctx context.Context, user *User, source string) error {
+    // Register user...
+    
+    userRegistrations.WithLabelValues(source).Inc()
+    
+    return nil
+}
+```
+
+### GOL.3.2.4.6: Use Metric Labels Wisely
+
+**Rule**: Use labels for dimensions, but avoid high cardinality.
+
+**Severity**: WARNING
+
+**Rationale**: High cardinality labels cause memory issues in Prometheus.
+
+**✅ Good**:
+```go
+// Low cardinality labels
+requestsTotal.WithLabelValues("GET", "/api/users", "200").Inc()
+requestsTotal.WithLabelValues("POST", "/api/orders", "201").Inc()
+```
+
+**❌ Bad**:
+```go
+// High cardinality - user_id creates millions of time series
+requestsTotal.WithLabelValues("GET", "/api/users", userID).Inc()
+```
+
+## References
+
+- [Prometheus Best Practices](https://prometheus.io/docs/practices/naming/)
+- [RED Method](https://www.weave.works/blog/the-red-method-key-metrics-for-microservices-architecture/)
+- [Prometheus Go Client](https://github.com/prometheus/client_golang)
+

package/augment-extensions/coding-standards/go/rules/microservices/service-discovery.md

@@ -0,0 +1,249 @@
+# Go Microservices - Service Discovery
+
+## Overview
+
+Service discovery enables microservices to find and communicate with each other dynamically. This document defines best practices for implementing service discovery in Go microservices.
+
+## Core Principles
+
+1. **Dynamic Registration**: Services register themselves on startup
+2. **Health Checks**: Implement health endpoints for service monitoring
+3. **Load Balancing**: Use client-side or server-side load balancing
+4. **Failure Handling**: Handle service unavailability gracefully
+5. **Configuration**: Use environment variables for service discovery endpoints
+
+## Rules
+
+### GOL.3.2.2.1: Implement Service Registration
+
+**Rule**: Register service with discovery system (Consul, etcd, Kubernetes) on startup.
+
+**Severity**: ERROR
+
+**Rationale**: Enables dynamic service discovery and load balancing.
+
+**✅ Good - Consul Registration**:
+```go
+import (
+    "github.com/hashicorp/consul/api"
+)
+
+type ServiceRegistry struct {
+    client     *api.Client
+    serviceID  string
+    serviceName string
+    port       int
+}
+
+func NewServiceRegistry(consulAddr, serviceName string, port int) (*ServiceRegistry, error) {
+    config := api.DefaultConfig()
+    config.Address = consulAddr
+    
+    client, err := api.NewClient(config)
+    if err != nil {
+        return nil, err
+    }
+    
+    return &ServiceRegistry{
+        client:      client,
+        serviceID:   fmt.Sprintf("%s-%s", serviceName, uuid.New().String()),
+        serviceName: serviceName,
+        port:        port,
+    }, nil
+}
+
+func (r *ServiceRegistry) Register(ctx context.Context) error {
+    registration := &api.AgentServiceRegistration{
+        ID:      r.serviceID,
+        Name:    r.serviceName,
+        Port:    r.port,
+        Address: getLocalIP(),
+        Check: &api.AgentServiceCheck{
+            HTTP:                           fmt.Sprintf("http://%s:%d/health", getLocalIP(), r.port),
+            Interval:                       "10s",
+            Timeout:                        "3s",
+            DeregisterCriticalServiceAfter: "30s",
+        },
+    }
+    
+    return r.client.Agent().ServiceRegister(registration)
+}
+
+func (r *ServiceRegistry) Deregister() error {
+    return r.client.Agent().ServiceDeregister(r.serviceID)
+}
+```
+
+### GOL.3.2.2.2: Implement Health Check Endpoints
+
+**Rule**: Provide `/health` and `/ready` endpoints for service health monitoring.
+
+**Severity**: ERROR
+
+**Rationale**: Enables load balancers and orchestrators to route traffic appropriately.
+
+**✅ Good**:
+```go
+type HealthChecker struct {
+    db    *sql.DB
+    cache *redis.Client
+}
+
+// Health returns basic liveness status
+func (h *HealthChecker) Health(w http.ResponseWriter, r *http.Request) {
+    w.WriteHeader(http.StatusOK)
+    json.NewEncoder(w).Encode(map[string]string{
+        "status": "healthy",
+    })
+}
+
+// Ready returns readiness status (checks dependencies)
+func (h *HealthChecker) Ready(w http.ResponseWriter, r *http.Request) {
+    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+    defer cancel()
+    
+    // Check database
+    if err := h.db.PingContext(ctx); err != nil {
+        w.WriteHeader(http.StatusServiceUnavailable)
+        json.NewEncoder(w).Encode(map[string]string{
+            "status": "not_ready",
+            "reason": "database_unavailable",
+        })
+        return
+    }
+    
+    // Check cache
+    if err := h.cache.Ping(ctx).Err(); err != nil {
+        w.WriteHeader(http.StatusServiceUnavailable)
+        json.NewEncoder(w).Encode(map[string]string{
+            "status": "not_ready",
+            "reason": "cache_unavailable",
+        })
+        return
+    }
+    
+    w.WriteHeader(http.StatusOK)
+    json.NewEncoder(w).Encode(map[string]string{
+        "status": "ready",
+    })
+}
+```
+
+### GOL.3.2.2.3: Implement Service Discovery Client
+
+**Rule**: Use service discovery to find and connect to other services.
+
+**Severity**: WARNING
+
+**✅ Good - Consul Service Discovery**:
+```go
+type ServiceDiscovery struct {
+    client *api.Client
+}
+
+func NewServiceDiscovery(consulAddr string) (*ServiceDiscovery, error) {
+    config := api.DefaultConfig()
+    config.Address = consulAddr
+    
+    client, err := api.NewClient(config)
+    if err != nil {
+        return nil, err
+    }
+    
+    return &ServiceDiscovery{client: client}, nil
+}
+
+func (sd *ServiceDiscovery) GetServiceAddress(serviceName string) (string, error) {
+    services, _, err := sd.client.Health().Service(serviceName, "", true, nil)
+    if err != nil {
+        return "", err
+    }
+    
+    if len(services) == 0 {
+        return "", fmt.Errorf("no healthy instances of %s found", serviceName)
+    }
+    
+    // Simple round-robin (use random for better distribution)
+    service := services[rand.Intn(len(services))]
+    
+    return fmt.Sprintf("%s:%d", service.Service.Address, service.Service.Port), nil
+}
+
+// Usage
+func (c *Client) CallUserService(ctx context.Context, userID int64) (*User, error) {
+    addr, err := c.discovery.GetServiceAddress("user-service")
+    if err != nil {
+        return nil, err
+    }
+    
+    conn, err := grpc.Dial(addr, grpc.WithInsecure())
+    if err != nil {
+        return nil, err
+    }
+    defer conn.Close()
+    
+    client := userv1.NewUserServiceClient(conn)
+    resp, err := client.GetUser(ctx, &userv1.GetUserRequest{Id: userID})
+    if err != nil {
+        return nil, err
+    }
+    
+    return &User{
+        ID:   resp.User.Id,
+        Name: resp.User.Name,
+    }, nil
+}
+```
+
+### GOL.3.2.2.4: Implement Graceful Deregistration
+
+**Rule**: Deregister service from discovery system during shutdown.
+
+**Severity**: ERROR
+
+**Rationale**: Prevents routing traffic to terminated services.
+
+**✅ Good**:
+```go
+func main() {
+    registry, err := NewServiceRegistry("localhost:8500", "user-service", 8080)
+    if err != nil {
+        log.Fatal(err)
+    }
+    
+    // Register service
+    if err := registry.Register(context.Background()); err != nil {
+        log.Fatal(err)
+    }
+    
+    // Start server
+    srv := startServer()
+    
+    // Wait for shutdown signal
+    quit := make(chan os.Signal, 1)
+    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
+    <-quit
+    
+    log.Println("Shutting down...")
+    
+    // Deregister from service discovery
+    if err := registry.Deregister(); err != nil {
+        log.Printf("Failed to deregister: %v", err)
+    }
+    
+    // Shutdown server
+    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+    defer cancel()
+    
+    if err := srv.Shutdown(ctx); err != nil {
+        log.Fatal(err)
+    }
+}
+```
+
+## References
+
+- [Consul Service Discovery](https://www.consul.io/docs/discovery/services)
+- [etcd Service Discovery](https://etcd.io/docs/latest/dev-guide/grpc_naming/)
+- [Kubernetes Service Discovery](https://kubernetes.io/docs/concepts/services-networking/service/)
+