omgkit 2.12.0 → 2.15.0

package/plugin/skills/microservices/distributed-tracing/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: distributed-tracing
+description: Comprehensive distributed tracing with Jaeger, Zipkin, OpenTelemetry, correlation IDs, and span design.
+---
+
+# Distributed Tracing
+
+Comprehensive distributed tracing with Jaeger, Zipkin, OpenTelemetry, correlation IDs, and span design.
+
+## Overview
+
+Distributed tracing tracks requests as they flow through multiple services, enabling debugging and performance analysis in microservices architectures.
+
+## Key Concepts
+
+### Trace Model
+- **Trace**: End-to-end request journey
+- **Span**: Single operation within a trace
+- **Span Context**: Propagated trace information
+- **Baggage**: Custom key-value pairs carried across services
+
+### Span Attributes
+- **Operation Name**: What the span represents
+- **Start/End Time**: Duration measurement
+- **Tags**: Indexed metadata for querying
+- **Logs**: Time-stamped events within span
+- **Status**: Success, error, or unset
+
+## OpenTelemetry Implementation
+
+### Instrumentation Setup
+```javascript
+// Node.js OpenTelemetry setup
+const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+const { SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
+const { ExpressInstrumentation } = require('@opentelemetry/instrumentation-express');
+
+const provider = new NodeTracerProvider();
+
+provider.addSpanProcessor(
+  new SimpleSpanProcessor(
+    new JaegerExporter({
+      endpoint: 'http://jaeger:14268/api/traces',
+    })
+  )
+);
+
+provider.register();
+
+registerInstrumentations({
+  instrumentations: [
+    new HttpInstrumentation(),
+    new ExpressInstrumentation(),
+  ],
+});
+```
+
+### Manual Span Creation
+```javascript
+const { trace } = require('@opentelemetry/api');
+
+const tracer = trace.getTracer('my-service');
+
+async function processOrder(orderId) {
+  return tracer.startActiveSpan('processOrder', async (span) => {
+    try {
+      span.setAttribute('order.id', orderId);
+
+      // Child span for database operation
+      await tracer.startActiveSpan('db.query', async (dbSpan) => {
+        dbSpan.setAttribute('db.system', 'postgresql');
+        dbSpan.setAttribute('db.statement', 'SELECT * FROM orders WHERE id = $1');
+        await db.query('SELECT * FROM orders WHERE id = $1', [orderId]);
+        dbSpan.end();
+      });
+
+      span.setStatus({ code: SpanStatusCode.OK });
+    } catch (error) {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
+      span.recordException(error);
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}
+```
+
+### Context Propagation
+```javascript
+const { context, propagation } = require('@opentelemetry/api');
+
+// Extract context from incoming request
+app.use((req, res, next) => {
+  const ctx = propagation.extract(context.active(), req.headers);
+  context.with(ctx, next);
+});
+
+// Inject context into outgoing request
+async function callService(url) {
+  const headers = {};
+  propagation.inject(context.active(), headers);
+
+  return fetch(url, { headers });
+}
+```
+
+## Jaeger Configuration
+
+### Kubernetes Deployment
+```yaml
+apiVersion: jaegertracing.io/v1
+kind: Jaeger
+metadata:
+  name: jaeger
+spec:
+  strategy: production
+  storage:
+    type: elasticsearch
+    elasticsearch:
+      nodeCount: 3
+      resources:
+        requests:
+          cpu: 1
+          memory: 4Gi
+  collector:
+    maxReplicas: 5
+  query:
+    replicas: 2
+```
+
+### Sampling Strategies
+```yaml
+# Jaeger sampling configuration
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: jaeger-sampling
+data:
+  sampling: |
+    {
+      "service_strategies": [
+        {
+          "service": "order-service",
+          "type": "probabilistic",
+          "param": 0.5
+        },
+        {
+          "service": "payment-service",
+          "type": "ratelimiting",
+          "param": 100
+        }
+      ],
+      "default_strategy": {
+        "type": "probabilistic",
+        "param": 0.1
+      }
+    }
+```
+
+## Span Design Guidelines
+
+### Naming Conventions
+```
+HTTP spans:    HTTP {METHOD} {route}
+               HTTP GET /api/users/:id
+
+Database:      {db.system}.{operation}
+               postgresql.query
+
+Message:       {messaging.system} {operation} {destination}
+               kafka send orders-topic
+
+RPC:           {rpc.system}/{service}/{method}
+               grpc/UserService/GetUser
+```
+
+### Essential Attributes
+```javascript
+// HTTP spans
+span.setAttribute('http.method', 'GET');
+span.setAttribute('http.url', 'https://api.example.com/users/123');
+span.setAttribute('http.status_code', 200);
+span.setAttribute('http.request_content_length', 0);
+span.setAttribute('http.response_content_length', 1234);
+
+// Database spans
+span.setAttribute('db.system', 'postgresql');
+span.setAttribute('db.name', 'mydb');
+span.setAttribute('db.statement', 'SELECT * FROM users WHERE id = $1');
+span.setAttribute('db.operation', 'SELECT');
+
+// Messaging spans
+span.setAttribute('messaging.system', 'kafka');
+span.setAttribute('messaging.destination', 'orders');
+span.setAttribute('messaging.operation', 'send');
+```
+
+## Best Practices
+
+1. **Consistent Naming**: Follow semantic conventions
+2. **Don't Over-Trace**: Sample appropriately
+3. **Meaningful Spans**: Business-relevant operations
+4. **Error Recording**: Always record exceptions
+5. **Context Propagation**: Ensure trace continuity
+
+## Sampling Strategies
+
+### Head-Based Sampling
+- Decision made at trace start
+- Simpler, consistent
+- May miss interesting traces
+
+### Tail-Based Sampling
+- Decision made at trace end
+- Keeps all errors and slow traces
+- More resource intensive
+
+### Adaptive Sampling
+- Adjusts rate based on traffic
+- Balances cost and coverage
+- Best for variable traffic
+
+## Anti-Patterns
+
+- Creating spans for every function call
+- Not propagating context across service boundaries
+- Ignoring span errors
+- Sampling 100% in production
+- Not correlating traces with logs
+
+## When to Use
+
+- Microservices with complex request flows
+- Debugging latency issues
+- Understanding service dependencies
+- Capacity planning
+
+## When NOT to Use
+
+- Monolithic applications
+- Very high-throughput systems without sampling
+- When storage costs are a concern

package/plugin/skills/microservices/service-discovery/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: service-discovery
+description: Service discovery patterns with Consul, Kubernetes DNS, Eureka, health checks, and client-side load balancing.
+---
+
+# Service Discovery
+
+Service discovery patterns with Consul, Kubernetes DNS, Eureka, health checks, and client-side load balancing.
+
+## Overview
+
+Service discovery enables services to find and communicate with each other dynamically without hardcoded addresses.
+
+## Discovery Patterns
+
+### Client-Side Discovery
+- Client queries registry
+- Client performs load balancing
+- Examples: Eureka, Consul client
+
+### Server-Side Discovery
+- Load balancer queries registry
+- Load balancer routes requests
+- Examples: Kubernetes Services, AWS ELB
+
+### DNS-Based Discovery
+- Services registered as DNS records
+- Standard DNS resolution
+- Examples: Kubernetes DNS, Consul DNS
+
+## Kubernetes Service Discovery
+
+### ClusterIP Service
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: user-service
+spec:
+  selector:
+    app: user-service
+  ports:
+    - port: 80
+      targetPort: 8080
+  type: ClusterIP
+```
+
+### Headless Service (Direct Pod Discovery)
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: user-service-headless
+spec:
+  clusterIP: None
+  selector:
+    app: user-service
+  ports:
+    - port: 8080
+```
+
+### DNS Resolution
+```
+# ClusterIP service
+user-service.default.svc.cluster.local
+
+# Headless service returns all pod IPs
+# SRV records for port discovery
+_http._tcp.user-service.default.svc.cluster.local
+```
+
+### EndpointSlices
+```yaml
+apiVersion: discovery.k8s.io/v1
+kind: EndpointSlice
+metadata:
+  name: user-service-abc
+  labels:
+    kubernetes.io/service-name: user-service
+addressType: IPv4
+endpoints:
+  - addresses:
+      - "10.0.0.1"
+    conditions:
+      ready: true
+      serving: true
+ports:
+  - port: 8080
+    protocol: TCP
+```
+
+## Consul Service Discovery
+
+### Service Registration
+```json
+{
+  "service": {
+    "name": "user-service",
+    "id": "user-service-1",
+    "port": 8080,
+    "tags": ["v1", "production"],
+    "meta": {
+      "version": "1.0.0"
+    },
+    "check": {
+      "http": "http://localhost:8080/health",
+      "interval": "10s",
+      "timeout": "5s"
+    }
+  }
+}
+```
+
+### Health Checks
+```json
+{
+  "checks": [
+    {
+      "id": "http-check",
+      "name": "HTTP Health Check",
+      "http": "http://localhost:8080/health",
+      "interval": "10s",
+      "timeout": "5s"
+    },
+    {
+      "id": "tcp-check",
+      "name": "TCP Check",
+      "tcp": "localhost:8080",
+      "interval": "10s"
+    },
+    {
+      "id": "script-check",
+      "name": "Script Check",
+      "args": ["/opt/check.sh"],
+      "interval": "30s"
+    }
+  ]
+}
+```
+
+### Service Query
+```bash
+# DNS query
+dig @127.0.0.1 -p 8600 user-service.service.consul
+
+# HTTP API
+curl http://localhost:8500/v1/catalog/service/user-service
+
+# Health-filtered
+curl http://localhost:8500/v1/health/service/user-service?passing=true
+```
+
+## Client-Side Load Balancing
+
+### gRPC with Service Discovery
+```go
+import (
+    "google.golang.org/grpc"
+    "google.golang.org/grpc/resolver"
+)
+
+// Custom resolver for Consul
+type consulResolver struct {
+    consulClient *api.Client
+    serviceName  string
+}
+
+func (r *consulResolver) ResolveNow(options resolver.ResolveNowOptions) {
+    services, _, _ := r.consulClient.Health().Service(
+        r.serviceName, "", true, nil)
+
+    var addrs []resolver.Address
+    for _, s := range services {
+        addrs = append(addrs, resolver.Address{
+            Addr: fmt.Sprintf("%s:%d", s.Service.Address, s.Service.Port),
+        })
+    }
+    r.cc.UpdateState(resolver.State{Addresses: addrs})
+}
+
+// Usage
+conn, _ := grpc.Dial(
+    "consul:///user-service",
+    grpc.WithDefaultServiceConfig(`{"loadBalancingPolicy":"round_robin"}`),
+)
+```
+
+### Node.js with Consul
+```javascript
+const Consul = require('consul');
+const consul = new Consul();
+
+async function discoverService(serviceName) {
+  const services = await consul.health.service({
+    service: serviceName,
+    passing: true
+  });
+
+  return services.map(s => ({
+    address: s.Service.Address,
+    port: s.Service.Port,
+    meta: s.Service.Meta
+  }));
+}
+
+// Client-side load balancing
+class ServiceClient {
+  constructor(serviceName) {
+    this.serviceName = serviceName;
+    this.instances = [];
+    this.currentIndex = 0;
+    this.refresh();
+    setInterval(() => this.refresh(), 30000);
+  }
+
+  async refresh() {
+    this.instances = await discoverService(this.serviceName);
+  }
+
+  getNextInstance() {
+    if (this.instances.length === 0) {
+      throw new Error('No instances available');
+    }
+    const instance = this.instances[this.currentIndex];
+    this.currentIndex = (this.currentIndex + 1) % this.instances.length;
+    return instance;
+  }
+}
+```
+
+## Health Check Patterns
+
+### Liveness vs Readiness
+```yaml
+# Kubernetes probes
+livenessProbe:
+  httpGet:
+    path: /health/live
+    port: 8080
+  initialDelaySeconds: 10
+  periodSeconds: 10
+  failureThreshold: 3
+
+readinessProbe:
+  httpGet:
+    path: /health/ready
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 5
+  failureThreshold: 3
+```
+
+### Health Endpoint Implementation
+```javascript
+app.get('/health/live', (req, res) => {
+  // Basic liveness - can the app respond?
+  res.status(200).json({ status: 'alive' });
+});
+
+app.get('/health/ready', async (req, res) => {
+  // Readiness - can it serve traffic?
+  const checks = {
+    database: await checkDatabase(),
+    cache: await checkCache(),
+    dependencies: await checkDependencies()
+  };
+
+  const allHealthy = Object.values(checks).every(c => c.healthy);
+  res.status(allHealthy ? 200 : 503).json({
+    status: allHealthy ? 'ready' : 'not ready',
+    checks
+  });
+});
+```
+
+## Best Practices
+
+1. **Health Checks**: Always implement meaningful health checks
+2. **Graceful Shutdown**: Deregister before stopping
+3. **Client Caching**: Cache discovery results with TTL
+4. **Fallback**: Handle discovery failures gracefully
+5. **Monitoring**: Track discovery latency and failures
+
+## Anti-Patterns
+
+- Hardcoding service addresses
+- Not implementing health checks
+- Too frequent discovery polling
+- Not handling discovery failures
+- Ignoring service metadata
+
+## When to Use
+
+- Dynamic environments (containers, cloud)
+- Frequently scaling services
+- Multiple instances of services
+- Zero-downtime deployments
+
+## When NOT to Use
+
+- Static infrastructure
+- Single instance services
+- When DNS is sufficient
+- Very simple architectures

package/plugin/skills/microservices/service-mesh/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: service-mesh
+description: Advanced service mesh implementation with Istio, Linkerd, traffic management, mTLS, and observability.
+---
+
+# Service Mesh
+
+Advanced service mesh implementation with Istio, Linkerd, traffic management, mTLS, and observability.
+
+## Overview
+
+Service mesh provides infrastructure-level features for service-to-service communication including traffic management, security, and observability without changing application code.
+
+## Key Concepts
+
+### Traffic Management
+- **Virtual Services**: Route traffic based on rules
+- **Destination Rules**: Configure load balancing, connection pools
+- **Gateways**: Manage ingress/egress traffic
+- **Service Entries**: Add external services to mesh
+
+### Security
+- **mTLS**: Mutual TLS between services
+- **Authorization Policies**: Fine-grained access control
+- **Peer Authentication**: Identity verification
+- **Request Authentication**: JWT validation
+
+### Observability
+- **Distributed Tracing**: Automatic trace propagation
+- **Metrics**: Automatic metric collection
+- **Access Logging**: Request/response logging
+- **Service Graph**: Visualization of dependencies
+
+## Istio Patterns
+
+### Traffic Routing
+```yaml
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: reviews-route
+spec:
+  hosts:
+    - reviews
+  http:
+    - match:
+        - headers:
+            end-user:
+              exact: jason
+      route:
+        - destination:
+            host: reviews
+            subset: v2
+    - route:
+        - destination:
+            host: reviews
+            subset: v1
+```
+
+### Canary Deployment
+```yaml
+apiVersion: networking.istio.io/v1beta1
+kind: VirtualService
+metadata:
+  name: my-service
+spec:
+  hosts:
+    - my-service
+  http:
+    - route:
+        - destination:
+            host: my-service
+            subset: v1
+          weight: 90
+        - destination:
+            host: my-service
+            subset: v2
+          weight: 10
+```
+
+### Circuit Breaker
+```yaml
+apiVersion: networking.istio.io/v1beta1
+kind: DestinationRule
+metadata:
+  name: my-service
+spec:
+  host: my-service
+  trafficPolicy:
+    connectionPool:
+      tcp:
+        maxConnections: 100
+      http:
+        h2UpgradePolicy: UPGRADE
+        http1MaxPendingRequests: 100
+        http2MaxRequests: 1000
+    outlierDetection:
+      consecutive5xxErrors: 5
+      interval: 30s
+      baseEjectionTime: 30s
+      maxEjectionPercent: 50
+```
+
+### mTLS Configuration
+```yaml
+apiVersion: security.istio.io/v1beta1
+kind: PeerAuthentication
+metadata:
+  name: default
+  namespace: istio-system
+spec:
+  mtls:
+    mode: STRICT
+```
+
+## Linkerd Patterns
+
+### Service Profile
+```yaml
+apiVersion: linkerd.io/v1alpha2
+kind: ServiceProfile
+metadata:
+  name: my-service.default.svc.cluster.local
+spec:
+  routes:
+    - name: GET /api/users
+      condition:
+        method: GET
+        pathRegex: /api/users
+      responseClasses:
+        - condition:
+            status:
+              min: 500
+              max: 599
+          isFailure: true
+```
+
+### Traffic Split
+```yaml
+apiVersion: split.smi-spec.io/v1alpha1
+kind: TrafficSplit
+metadata:
+  name: my-service-split
+spec:
+  service: my-service
+  backends:
+    - service: my-service-v1
+      weight: 900m
+    - service: my-service-v2
+      weight: 100m
+```
+
+## Best Practices
+
+1. **Start with Observability**: Enable tracing before traffic management
+2. **Gradual mTLS Rollout**: Use permissive mode first
+3. **Circuit Breaker Tuning**: Start conservative, adjust based on data
+4. **Avoid Mesh Complexity**: Don't over-engineer routing rules
+5. **Resource Limits**: Set appropriate proxy resource limits
+
+## Anti-Patterns
+
+- Putting business logic in routing rules
+- Ignoring sidecar resource consumption
+- Not monitoring mesh control plane
+- Over-complicating traffic policies
+- Skipping gradual rollout of mesh features
+
+## When to Use
+
+- Multiple services needing consistent traffic management
+- Zero-trust security requirements
+- Need for advanced observability without code changes
+- Complex deployment strategies (canary, blue-green)
+
+## When NOT to Use
+
+- Simple applications with few services
+- When latency is extremely critical (adds ~1ms)
+- Teams without Kubernetes expertise
+- Tight resource constraints