@mytechtoday/augment-extensions 1.4.0 → 1.5.0

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

@@ -0,0 +1,253 @@
+# Go Microservices - Distributed Tracing
+
+## Overview
+
+Distributed tracing enables tracking requests across multiple microservices. This document defines best practices for implementing distributed tracing using OpenTelemetry in Go.
+
+## Core Principles
+
+1. **Context Propagation**: Pass trace context across service boundaries
+2. **Span Creation**: Create spans for significant operations
+3. **Attribute Enrichment**: Add relevant attributes to spans
+4. **Error Recording**: Record errors and exceptions in spans
+5. **Sampling**: Use appropriate sampling strategies
+
+## Rules
+
+### GOL.3.2.3.1: Initialize OpenTelemetry Tracer
+
+**Rule**: Initialize OpenTelemetry tracer provider on application startup.
+
+**Severity**: ERROR
+
+**Rationale**: Enables distributed tracing across all services.
+
+**✅ Good**:
+```go
+import (
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/exporters/jaeger"
+    "go.opentelemetry.io/otel/sdk/resource"
+    sdktrace "go.opentelemetry.io/otel/sdk/trace"
+    semconv "go.opentelemetry.io/otel/semconv/v1.4.0"
+)
+
+func initTracer(serviceName, jaegerEndpoint string) (*sdktrace.TracerProvider, error) {
+    // Create Jaeger exporter
+    exporter, err := jaeger.New(jaeger.WithCollectorEndpoint(jaeger.WithEndpoint(jaegerEndpoint)))
+    if err != nil {
+        return nil, err
+    }
+    
+    // Create resource with service name
+    res, err := resource.New(
+        context.Background(),
+        resource.WithAttributes(
+            semconv.ServiceNameKey.String(serviceName),
+        ),
+    )
+    if err != nil {
+        return nil, err
+    }
+    
+    // Create tracer provider
+    tp := sdktrace.NewTracerProvider(
+        sdktrace.WithBatcher(exporter),
+        sdktrace.WithResource(res),
+        sdktrace.WithSampler(sdktrace.AlwaysSample()),
+    )
+    
+    // Set global tracer provider
+    otel.SetTracerProvider(tp)
+    
+    return tp, nil
+}
+
+func main() {
+    tp, err := initTracer("user-service", "http://jaeger:14268/api/traces")
+    if err != nil {
+        log.Fatal(err)
+    }
+    defer func() {
+        if err := tp.Shutdown(context.Background()); err != nil {
+            log.Printf("Error shutting down tracer provider: %v", err)
+        }
+    }()
+    
+    // Start server...
+}
+```
+
+### GOL.3.2.3.2: Create Spans for Operations
+
+**Rule**: Create spans for significant operations (HTTP requests, database queries, external calls).
+
+**Severity**: WARNING
+
+**✅ Good**:
+```go
+import (
+    "go.opentelemetry.io/otel"
+    "go.opentelemetry.io/otel/attribute"
+    "go.opentelemetry.io/otel/codes"
+)
+
+func (s *UserService) GetUser(ctx context.Context, id int64) (*User, error) {
+    tracer := otel.Tracer("user-service")
+    
+    // Create span
+    ctx, span := tracer.Start(ctx, "GetUser")
+    defer span.End()
+    
+    // Add attributes
+    span.SetAttributes(
+        attribute.Int64("user.id", id),
+    )
+    
+    // Perform operation
+    user, err := s.repo.GetUser(ctx, id)
+    if err != nil {
+        // Record error
+        span.RecordError(err)
+        span.SetStatus(codes.Error, err.Error())
+        return nil, err
+    }
+    
+    // Add result attributes
+    span.SetAttributes(
+        attribute.String("user.name", user.Name),
+        attribute.String("user.email", user.Email),
+    )
+    
+    return user, nil
+}
+```
+
+### GOL.3.2.3.3: Propagate Context in HTTP Requests
+
+**Rule**: Propagate trace context in HTTP headers for cross-service calls.
+
+**Severity**: ERROR
+
+**Rationale**: Enables end-to-end tracing across service boundaries.
+
+**✅ Good - HTTP Client**:
+```go
+import (
+    "go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
+)
+
+func NewHTTPClient() *http.Client {
+    return &http.Client{
+        Transport: otelhttp.NewTransport(http.DefaultTransport),
+        Timeout:   30 * time.Second,
+    }
+}
+
+func (c *Client) CallExternalService(ctx context.Context, url string) (*Response, error) {
+    tracer := otel.Tracer("user-service")
+    ctx, span := tracer.Start(ctx, "CallExternalService")
+    defer span.End()
+    
+    req, err := http.NewRequestWithContext(ctx, "GET", url, nil)
+    if err != nil {
+        span.RecordError(err)
+        return nil, err
+    }
+    
+    // Context is automatically propagated via otelhttp.Transport
+    resp, err := c.httpClient.Do(req)
+    if err != nil {
+        span.RecordError(err)
+        return nil, err
+    }
+    defer resp.Body.Close()
+    
+    // Process response...
+    return processResponse(resp)
+}
+```
+
+**✅ Good - HTTP Server**:
+```go
+func setupRoutes() http.Handler {
+    r := chi.NewRouter()
+    
+    // Add OpenTelemetry middleware
+    r.Use(otelhttp.NewMiddleware("user-service"))
+    
+    r.Get("/users/{id}", handleGetUser)
+    
+    return r
+}
+```
+
+### GOL.3.2.3.4: Instrument gRPC with Tracing
+
+**Rule**: Use OpenTelemetry interceptors for gRPC tracing.
+
+**Severity**: WARNING
+
+**✅ Good**:
+```go
+import (
+    "go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc"
+)
+
+// Server
+func NewGRPCServer() *grpc.Server {
+    return grpc.NewServer(
+        grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor()),
+        grpc.StreamInterceptor(otelgrpc.StreamServerInterceptor()),
+    )
+}
+
+// Client
+func NewGRPCClient(addr string) (*grpc.ClientConn, error) {
+    return grpc.Dial(addr,
+        grpc.WithInsecure(),
+        grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor()),
+        grpc.WithStreamInterceptor(otelgrpc.StreamClientInterceptor()),
+    )
+}
+```
+
+### GOL.3.2.3.5: Add Custom Span Attributes
+
+**Rule**: Add relevant business context as span attributes.
+
+**Severity**: INFO
+
+**✅ Good**:
+```go
+func (s *OrderService) CreateOrder(ctx context.Context, order *Order) error {
+    tracer := otel.Tracer("order-service")
+    ctx, span := tracer.Start(ctx, "CreateOrder")
+    defer span.End()
+    
+    // Add business context
+    span.SetAttributes(
+        attribute.String("order.id", order.ID),
+        attribute.String("customer.id", order.CustomerID),
+        attribute.Float64("order.total", order.Total),
+        attribute.Int("order.item_count", len(order.Items)),
+    )
+    
+    // Process order...
+    if err := s.processOrder(ctx, order); err != nil {
+        span.RecordError(err)
+        span.SetStatus(codes.Error, "failed to process order")
+        return err
+    }
+    
+    span.SetStatus(codes.Ok, "order created successfully")
+    return nil
+}
+```
+
+## References
+
+- [OpenTelemetry Go](https://opentelemetry.io/docs/instrumentation/go/)
+- [Jaeger Tracing](https://www.jaegertracing.io/)
+- [OpenTelemetry Best Practices](https://opentelemetry.io/docs/concepts/signals/traces/)
+

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

@@ -0,0 +1,257 @@
+# Go Microservices - gRPC Patterns
+
+## Overview
+
+gRPC is a high-performance RPC framework ideal for microservices communication. This document defines best practices for implementing gRPC services in Go.
+
+## Core Principles
+
+1. **Protocol Buffers**: Use proto3 for service definitions
+2. **Error Handling**: Use gRPC status codes and error details
+3. **Streaming**: Leverage streaming for large datasets and real-time updates
+4. **Interceptors**: Use interceptors for cross-cutting concerns
+5. **Context Propagation**: Pass context for timeouts and cancellation
+
+## Rules
+
+### GOL.3.2.1.1: Define Services with Protocol Buffers
+
+**Rule**: Define all gRPC services using Protocol Buffers (proto3).
+
+**Severity**: ERROR
+
+**Rationale**: Protocol Buffers provide type safety, versioning, and cross-language compatibility.
+
+**✅ Good - user.proto**:
+```protobuf
+syntax = "proto3";
+
+package user.v1;
+
+option go_package = "github.com/example/user/v1;userv1";
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (GetUserResponse);
+  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
+  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);
+  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
+  rpc DeleteUser(DeleteUserRequest) returns (DeleteUserResponse);
+  
+  // Streaming example
+  rpc StreamUsers(StreamUsersRequest) returns (stream User);
+}
+
+message User {
+  int64 id = 1;
+  string name = 2;
+  string email = 3;
+  int64 created_at = 4;
+}
+
+message GetUserRequest {
+  int64 id = 1;
+}
+
+message GetUserResponse {
+  User user = 1;
+}
+```
+
+### GOL.3.2.1.2: Implement Proper Error Handling
+
+**Rule**: Use gRPC status codes and structured error details.
+
+**Severity**: ERROR
+
+**Rationale**: Proper error handling enables clients to handle failures appropriately.
+
+**✅ Good**:
+```go
+import (
+    "google.golang.org/grpc/codes"
+    "google.golang.org/grpc/status"
+)
+
+func (s *UserService) GetUser(ctx context.Context, req *userv1.GetUserRequest) (*userv1.GetUserResponse, error) {
+    if req.Id <= 0 {
+        return nil, status.Error(codes.InvalidArgument, "user ID must be positive")
+    }
+    
+    user, err := s.repo.GetUser(ctx, req.Id)
+    if err != nil {
+        if errors.Is(err, ErrNotFound) {
+            return nil, status.Error(codes.NotFound, "user not found")
+        }
+        return nil, status.Error(codes.Internal, "failed to get user")
+    }
+    
+    return &userv1.GetUserResponse{
+        User: &userv1.User{
+            Id:        user.ID,
+            Name:      user.Name,
+            Email:     user.Email,
+            CreatedAt: user.CreatedAt.Unix(),
+        },
+    }, nil
+}
+```
+
+**gRPC Status Code Mapping**:
+- `codes.OK` - Success
+- `codes.InvalidArgument` - Invalid input
+- `codes.NotFound` - Resource not found
+- `codes.AlreadyExists` - Resource already exists
+- `codes.PermissionDenied` - Authorization failure
+- `codes.Unauthenticated` - Authentication required
+- `codes.Internal` - Server error
+- `codes.Unavailable` - Service unavailable
+- `codes.DeadlineExceeded` - Timeout
+
+### GOL.3.2.1.3: Use Interceptors for Cross-Cutting Concerns
+
+**Rule**: Implement unary and stream interceptors for logging, auth, metrics.
+
+**Severity**: WARNING
+
+**Rationale**: Interceptors provide a clean way to add middleware-like functionality.
+
+**✅ Good**:
+```go
+// Unary interceptor for logging
+func loggingUnaryInterceptor(logger *slog.Logger) 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)
+        
+        logger.Info("gRPC call",
+            "method", info.FullMethod,
+            "duration_ms", time.Since(start).Milliseconds(),
+            "error", err,
+        )
+        
+        return resp, err
+    }
+}
+
+// Stream interceptor for logging
+func loggingStreamInterceptor(logger *slog.Logger) grpc.StreamServerInterceptor {
+    return func(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error {
+        start := time.Now()
+        
+        err := handler(srv, ss)
+        
+        logger.Info("gRPC stream",
+            "method", info.FullMethod,
+            "duration_ms", time.Since(start).Milliseconds(),
+            "error", err,
+        )
+        
+        return err
+    }
+}
+
+// Server setup with interceptors
+func NewServer(logger *slog.Logger) *grpc.Server {
+    return grpc.NewServer(
+        grpc.ChainUnaryInterceptor(
+            loggingUnaryInterceptor(logger),
+            authUnaryInterceptor(),
+            metricsUnaryInterceptor(),
+        ),
+        grpc.ChainStreamInterceptor(
+            loggingStreamInterceptor(logger),
+            authStreamInterceptor(),
+        ),
+    )
+}
+```
+
+### GOL.3.2.1.4: Implement Server-Side Streaming
+
+**Rule**: Use server-side streaming for large result sets and real-time updates.
+
+**Severity**: INFO
+
+**✅ Good**:
+```go
+func (s *UserService) StreamUsers(req *userv1.StreamUsersRequest, stream userv1.UserService_StreamUsersServer) error {
+    ctx := stream.Context()
+    
+    // Check for cancellation
+    if err := ctx.Err(); err != nil {
+        return status.Error(codes.Canceled, "stream canceled")
+    }
+    
+    // Stream users in batches
+    offset := 0
+    limit := 100
+    
+    for {
+        users, err := s.repo.ListUsers(ctx, offset, limit)
+        if err != nil {
+            return status.Error(codes.Internal, "failed to list users")
+        }
+        
+        if len(users) == 0 {
+            break
+        }
+        
+        for _, user := range users {
+            if err := stream.Send(&userv1.User{
+                Id:        user.ID,
+                Name:      user.Name,
+                Email:     user.Email,
+                CreatedAt: user.CreatedAt.Unix(),
+            }); err != nil {
+                return status.Error(codes.Internal, "failed to send user")
+            }
+        }
+        
+        offset += len(users)
+        
+        if len(users) < limit {
+            break
+        }
+    }
+    
+    return nil
+}
+```
+
+### GOL.3.2.1.5: Set Appropriate Timeouts
+
+**Rule**: Always set timeouts for gRPC calls using context.
+
+**Severity**: ERROR
+
+**Rationale**: Prevents hanging requests and resource exhaustion.
+
+**✅ Good - Client**:
+```go
+func (c *UserClient) GetUser(ctx context.Context, id int64) (*User, error) {
+    // Set timeout for this specific call
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+    
+    resp, err := c.client.GetUser(ctx, &userv1.GetUserRequest{
+        Id: id,
+    })
+    if err != nil {
+        return nil, err
+    }
+    
+    return &User{
+        ID:    resp.User.Id,
+        Name:  resp.User.Name,
+        Email: resp.User.Email,
+    }, nil
+}
+```
+
+## References
+
+- [gRPC Go Quick Start](https://grpc.io/docs/languages/go/quickstart/)
+- [gRPC Best Practices](https://grpc.io/docs/guides/performance/)
+- [Protocol Buffers](https://developers.google.com/protocol-buffers)
+