@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/monitoring-expert/references/capacity-planning.md

@@ -0,0 +1,344 @@
+# Capacity Planning
+
+## Growth Projection
+
+### Linear Projection
+
+```python
+import pandas as pd
+import numpy as np
+from sklearn.linear_model import LinearRegression
+
+# Historical data
+data = pd.DataFrame({
+    'month': range(1, 13),
+    'requests_per_second': [100, 120, 145, 160, 180, 200, 220, 245, 270, 290, 310, 330]
+})
+
+# Train model
+model = LinearRegression()
+X = data[['month']].values
+y = data['requests_per_second'].values
+model.fit(X, y)
+
+# Forecast next 6 months
+future_months = np.array([[13], [14], [15], [16], [17], [18]])
+predictions = model.predict(future_months)
+
+print("Projected RPS in 6 months:", predictions[-1])
+```
+
+### Prometheus Queries for Trends
+
+```promql
+# Monthly growth rate
+(
+  rate(http_requests_total[30d])
+  /
+  rate(http_requests_total[30d] offset 30d)
+) - 1
+
+# Predict resource exhaustion
+predict_linear(
+  node_memory_MemAvailable_bytes[1h],
+  3600 * 24 * 30  # 30 days ahead
+)
+
+# Storage growth
+predict_linear(
+  node_filesystem_avail_bytes[7d],
+  3600 * 24 * 90  # 90 days ahead
+)
+```
+
+## Resource Forecasting
+
+### CPU Requirements
+
+```javascript
+// Current capacity
+const currentRPS = 1000;
+const currentCPU = 0.65;  // 65% utilization
+const targetCPU = 0.70;   // Target 70% max
+
+// Projected load
+const projectedRPS = 2500;
+
+// Required CPU capacity
+const cpuScalingFactor = projectedRPS / currentRPS;
+const requiredCPU = (currentCPU * cpuScalingFactor) / targetCPU;
+
+console.log(`Current: ${currentRPS} RPS @ ${currentCPU * 100}% CPU`);
+console.log(`Projected: ${projectedRPS} RPS requires ${requiredCPU.toFixed(2)}x CPU`);
+```
+
+### Memory Requirements
+
+```javascript
+// Memory per request (average)
+const avgMemoryPerRequest = 2048;  // bytes
+const concurrentRequests = 500;
+const overhead = 1.3;  // 30% overhead for GC, OS, etc.
+
+const requiredMemory = (avgMemoryPerRequest * concurrentRequests * overhead) / (1024 ** 3);
+console.log(`Required memory: ${requiredMemory.toFixed(2)} GB`);
+```
+
+### Database Connections
+
+```javascript
+// Connections per instance
+const connectionsPerInstance = 100;
+const instances = 5;
+const utilizationTarget = 0.75;
+
+// Available connections
+const totalConnections = connectionsPerInstance * instances;
+const effectiveConnections = totalConnections * utilizationTarget;
+
+// RPS capacity
+const avgRequestsPerConnection = 10;
+const maxRPS = effectiveConnections * avgRequestsPerConnection;
+
+console.log(`Max sustainable RPS: ${maxRPS}`);
+```
+
+## Scaling Strategies
+
+### Horizontal Scaling Calculator
+
+```javascript
+function calculateInstances(targetRPS, instanceCapacity, bufferPercent = 20) {
+  // Account for buffer
+  const effectiveCapacity = instanceCapacity * (1 - bufferPercent / 100);
+
+  // Calculate required instances
+  const requiredInstances = Math.ceil(targetRPS / effectiveCapacity);
+
+  // Account for availability zones
+  const minInstancesPerAZ = 2;
+  const zones = 3;
+  const minTotal = minInstancesPerAZ * zones;
+
+  return Math.max(requiredInstances, minTotal);
+}
+
+console.log(calculateInstances(5000, 1000));  // 7 instances
+```
+
+### Auto-scaling Configuration
+
+```yaml
+# Kubernetes HPA
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: app-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: app
+  minReplicas: 3
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: 80
+    - type: Pods
+      pods:
+        metric:
+          name: http_requests_per_second
+        target:
+          type: AverageValue
+          averageValue: "1000"
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies:
+        - type: Percent
+          value: 50
+          periodSeconds: 60
+    scaleUp:
+      stabilizationWindowSeconds: 0
+      policies:
+        - type: Percent
+          value: 100
+          periodSeconds: 30
+        - type: Pods
+          value: 4
+          periodSeconds: 30
+      selectPolicy: Max
+```
+
+### AWS Auto Scaling
+
+```json
+{
+  "AutoScalingGroupName": "app-asg",
+  "MinSize": 3,
+  "MaxSize": 20,
+  "DesiredCapacity": 5,
+  "TargetTrackingScalingPolicies": [
+    {
+      "TargetValue": 70.0,
+      "PredefinedMetricSpecification": {
+        "PredefinedMetricType": "ASGAverageCPUUtilization"
+      },
+      "ScaleInCooldown": 300,
+      "ScaleOutCooldown": 60
+    },
+    {
+      "TargetValue": 1000.0,
+      "CustomizedMetricSpecification": {
+        "MetricName": "RequestCountPerTarget",
+        "Namespace": "AWS/ApplicationELB",
+        "Statistic": "Sum"
+      }
+    }
+  ]
+}
+```
+
+## Performance Budgets
+
+### Response Time Budget
+
+```javascript
+const performanceBudget = {
+  // Page load budgets
+  ttfb: 200,          // Time to First Byte (ms)
+  fcp: 1000,          // First Contentful Paint (ms)
+  lcp: 2500,          // Largest Contentful Paint (ms)
+
+  // API budgets
+  apiP50: 100,        // 50th percentile (ms)
+  apiP95: 500,        // 95th percentile (ms)
+  apiP99: 1000,       // 99th percentile (ms)
+
+  // Resource budgets
+  jsBundle: 200,      // JavaScript bundle size (KB)
+  cssBundle: 50,      // CSS bundle size (KB)
+  images: 500,        // Total images (KB)
+
+  // Infrastructure budgets
+  cpuUtilization: 70,     // Max % during normal load
+  memoryUtilization: 80,  // Max % during normal load
+  errorRate: 0.01,        // Max 1% error rate
+};
+
+function checkBudget(actual, budget, metric) {
+  if (actual > budget) {
+    console.warn(`Budget exceeded for ${metric}: ${actual} > ${budget}`);
+    return false;
+  }
+  return true;
+}
+```
+
+## Cost Optimization
+
+### Instance Sizing
+
+```javascript
+function optimizeInstanceSize(workload) {
+  const instances = [
+    { type: 't3.small', vcpu: 2, memory: 2, cost: 0.0208 },
+    { type: 't3.medium', vcpu: 2, memory: 4, cost: 0.0416 },
+    { type: 't3.large', vcpu: 2, memory: 8, cost: 0.0832 },
+    { type: 'm5.large', vcpu: 2, memory: 8, cost: 0.096 },
+    { type: 'm5.xlarge', vcpu: 4, memory: 16, cost: 0.192 },
+  ];
+
+  const filtered = instances.filter(i =>
+    i.vcpu >= workload.requiredVCPU &&
+    i.memory >= workload.requiredMemory
+  );
+
+  // Sort by cost efficiency
+  return filtered.sort((a, b) => {
+    const scoreA = (a.vcpu * a.memory) / a.cost;
+    const scoreB = (b.vcpu * b.memory) / b.cost;
+    return scoreB - scoreA;
+  })[0];
+}
+
+const recommendation = optimizeInstanceSize({
+  requiredVCPU: 2,
+  requiredMemory: 4,
+});
+
+console.log('Recommended instance:', recommendation);
+```
+
+## Capacity Alerts
+
+```yaml
+# Prometheus alerting rules
+groups:
+  - name: capacity
+    rules:
+      - alert: HighCPUPrediction
+        expr: |
+          predict_linear(
+            node_cpu_seconds_total{mode="idle"}[1h],
+            3600 * 24 * 7  # 7 days ahead
+          ) < 0.2
+        for: 1h
+        annotations:
+          summary: CPU capacity will be exhausted in 7 days
+
+      - alert: DiskSpaceProjection
+        expr: |
+          predict_linear(
+            node_filesystem_avail_bytes[7d],
+            3600 * 24 * 30
+          ) < 1e9  # Less than 1GB in 30 days
+        annotations:
+          summary: Disk space will run out in 30 days
+
+      - alert: DatabaseConnectionsNearLimit
+        expr: |
+          pg_stat_database_numbackends / pg_settings_max_connections > 0.8
+        for: 10m
+        annotations:
+          summary: Database connections at 80% capacity
+
+      - alert: ScalingRecommendation
+        expr: |
+          rate(http_requests_total[5m]) >
+          (instance_capacity * instance_count * 0.7)
+        annotations:
+          summary: Consider scaling up - traffic approaching capacity
+```
+
+## Quick Reference
+
+| Metric | Buffer | Reasoning |
+|--------|--------|-----------|
+| CPU | 30% | Headroom for spikes |
+| Memory | 20% | GC and OS overhead |
+| Connections | 25% | Connection churn |
+| Storage | 40% | Growth + snapshots |
+
+| Planning Horizon | Update Frequency |
+|------------------|------------------|
+| 3 months | Weekly |
+| 6 months | Bi-weekly |
+| 12 months | Monthly |
+
+| Scaling Trigger | Action |
+|-----------------|--------|
+| 70% CPU | Start planning |
+| 80% CPU | Scale up |
+| 90% CPU | Emergency scaling |
+| 60% CPU for 24h | Scale down |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/monitoring-expert/references/dashboards.md

@@ -0,0 +1,126 @@
+# Dashboards
+
+## RED Method (Request-focused)
+
+```
+Rate     - Requests per second
+Errors   - Failed requests per second
+Duration - Response time distribution
+```
+
+```promql
+# Rate
+sum(rate(http_requests_total[5m]))
+
+# Errors
+sum(rate(http_requests_total{status=~"5.."}[5m]))
+  /
+sum(rate(http_requests_total[5m]))
+
+# Duration (p95)
+histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
+```
+
+## USE Method (Resource-focused)
+
+```
+Utilization - % time resource is busy
+Saturation  - Queue depth, backlog
+Errors      - Error events
+```
+
+```promql
+# CPU Utilization
+100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
+
+# Memory Saturation
+node_memory_SwapTotal_bytes - node_memory_SwapFree_bytes
+
+# Disk Errors
+rate(node_disk_io_time_weighted_seconds_total[5m])
+```
+
+## Dashboard Structure
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SERVICE OVERVIEW                         │
+│  Request Rate │ Error Rate │ p50 Latency │ p99 Latency     │
+├─────────────────────────────────────────────────────────────┤
+│                    REQUEST METRICS                          │
+│  [Graph: Requests/s by endpoint]                           │
+│  [Graph: Error rate over time]                             │
+├─────────────────────────────────────────────────────────────┤
+│                    LATENCY METRICS                          │
+│  [Heatmap: Latency distribution]                           │
+│  [Graph: p50, p95, p99 over time]                          │
+├─────────────────────────────────────────────────────────────┤
+│                    INFRASTRUCTURE                           │
+│  CPU │ Memory │ Disk │ Network                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Panels
+
+### Stat Panel (Single Value)
+
+```promql
+# Current RPS
+sum(rate(http_requests_total[5m]))
+
+# Error percentage
+sum(rate(http_requests_total{status=~"5.."}[5m]))
+  /
+sum(rate(http_requests_total[5m])) * 100
+```
+
+### Time Series
+
+```promql
+# Requests by status
+sum by (status) (rate(http_requests_total[5m]))
+
+# Latency percentiles
+histogram_quantile(0.50, rate(http_request_duration_seconds_bucket[5m]))
+histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
+histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
+```
+
+### Table
+
+```promql
+# Top endpoints by error rate
+topk(10,
+  sum by (path) (rate(http_requests_total{status=~"5.."}[5m]))
+  /
+  sum by (path) (rate(http_requests_total[5m]))
+)
+```
+
+## Business Metrics Dashboard
+
+```promql
+# Orders per minute
+sum(rate(orders_created_total[5m])) * 60
+
+# Revenue (if tracked)
+sum(increase(order_value_dollars_sum[1h]))
+
+# Active users (gauge)
+active_users_total
+```
+
+## Quick Reference
+
+| Method | Focus | Metrics |
+|--------|-------|---------|
+| RED | Services | Rate, Errors, Duration |
+| USE | Resources | Utilization, Saturation, Errors |
+
+| Panel Type | Use Case |
+|------------|----------|
+| Stat | Single KPI |
+| Time Series | Trends over time |
+| Heatmap | Latency distribution |
+| Table | Top N, details |
+| Gauge | Current vs threshold |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/monitoring-expert/references/opentelemetry.md

@@ -0,0 +1,123 @@
+# OpenTelemetry Tracing
+
+## Node.js Setup
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { Resource } from '@opentelemetry/resources';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+
+const sdk = new NodeSDK({
+  resource: new Resource({
+    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service',
+    [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
+  }),
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://jaeger:4318/v1/traces',
+  }),
+  instrumentations: [getNodeAutoInstrumentations()],
+});
+
+sdk.start();
+```
+
+## Manual Spans
+
+```typescript
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+
+const tracer = trace.getTracer('my-service');
+
+async function processOrder(orderId: string) {
+  return tracer.startActiveSpan('processOrder', async (span) => {
+    span.setAttribute('order.id', orderId);
+
+    try {
+      // Child span for database
+      await tracer.startActiveSpan('db.getOrder', async (dbSpan) => {
+        const order = await db.orders.findById(orderId);
+        dbSpan.setAttribute('db.rows_affected', 1);
+        dbSpan.end();
+        return order;
+      });
+
+      // Child span for external API
+      await tracer.startActiveSpan('api.processPayment', async (apiSpan) => {
+        await paymentService.process(order);
+        apiSpan.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
+
+```typescript
+import { propagation, context } from '@opentelemetry/api';
+
+// Extract from incoming request
+app.use((req, res, next) => {
+  const ctx = propagation.extract(context.active(), req.headers);
+  context.with(ctx, next);
+});
+
+// Inject into outgoing request
+async function callExternalService() {
+  const headers = {};
+  propagation.inject(context.active(), headers);
+
+  await fetch('http://other-service/api', { headers });
+}
+```
+
+## Python Setup
+
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+provider = TracerProvider()
+processor = BatchSpanProcessor(OTLPSpanExporter(endpoint="http://jaeger:4318/v1/traces"))
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
+tracer = trace.get_tracer(__name__)
+
+def process_order(order_id: str):
+    with tracer.start_as_current_span("process_order") as span:
+        span.set_attribute("order.id", order_id)
+        # ... process order
+```
+
+## Quick Reference
+
+| Concept | Purpose |
+|---------|---------|
+| Span | Single operation |
+| Trace | Full request flow |
+| Context | Correlation across services |
+| Attributes | Metadata on spans |
+| Events | Timestamped logs in span |
+
+| Attribute | Example |
+|-----------|---------|
+| `http.method` | GET, POST |
+| `http.status_code` | 200, 500 |
+| `db.system` | postgresql |
+| `db.statement` | SELECT ... |