blockmine 1.23.4 → 1.25.0

package/.claude/skills/observability-engineering/SKILL.md

@@ -1,101 +0,0 @@
-# Observability Engineering
-
-Deep dive into distributed tracing, APM tools, OpenTelemetry, logs aggregation, and observability best practices.
-
-## Purpose
-
-Enable teams to gain deep visibility into distributed systems with comprehensive observability practices beyond basic monitoring.
-
-## When to Use This Skill
-
-Automatically activates when working on:
-- Distributed tracing (Jaeger, Tempo, Zipkin)
-- OpenTelemetry instrumentation
-- APM tools (DataDog, New Relic, Dynatrace)
-- Logs aggregation (ELK, Loki)
-- Correlation strategies (trace IDs, unified observability)
-- Service mesh observability
-- Observability cost optimization
-
-## Quick Start Checklist
-
-- [ ] Instrument application with OpenTelemetry
-- [ ] Set up distributed tracing backend
-- [ ] Configure logs aggregation
-- [ ] Implement correlation (trace IDs across logs/metrics/traces)
-- [ ] Set up APM dashboards
-- [ ] Configure sampling strategies
-- [ ] Monitor observability costs
-- [ ] Create SLO-based alerts
-
-## Core Concepts
-
-### Three Pillars of Observability
-
-```
-Logs:    What happened (events)
-Metrics: How much (counters, gauges)
-Traces:  Where time was spent (distributed request flow)
-```
-
-### OpenTelemetry
-
-```typescript
-import { trace, context } from '@opentelemetry/api';
-
-const tracer = trace.getTracer('my-service');
-
-async function handleRequest(req, res) {
-  const span = tracer.startSpan('handleRequest');
-
-  try {
-    const user = await fetchUser(req.userId);
-    span.setAttribute('user.id', user.id);
-
-    const result = await processData(user);
-    res.json(result);
-  } finally {
-    span.end();
-  }
-}
-```
-
-## Resource Files
-
-### Tracing & APM
-- **[distributed-tracing.md](resources/distributed-tracing.md)** - Jaeger, Tempo, trace propagation, span design
-- **[opentelemetry.md](resources/opentelemetry.md)** - OTEL SDK, auto-instrumentation, collectors, exporters
-- **[apm-tools.md](resources/apm-tools.md)** - DataDog, New Relic, Dynatrace comparison
-
-### Logs & Correlation
-- **[logs-aggregation.md](resources/logs-aggregation.md)** - ELK Stack, Loki, structured logging
-- **[correlation-strategies.md](resources/correlation-strategies.md)** - Trace IDs, unified observability
-
-### Cost & Best Practices
-- **[observability-cost-optimization.md](resources/observability-cost-optimization.md)** - Sampling, retention, cost strategies
-
-## Best Practices
-
-✅ Use OpenTelemetry (vendor-neutral)
-✅ Implement structured logging
-✅ Correlate logs/metrics/traces (trace IDs)
-✅ Sample intelligently (head-based, tail-based)
-✅ Monitor observability costs
-✅ Create dashboards from traces
-✅ Use service mesh for automatic instrumentation
-
-## Integration Points
-
-- **sre**: Monitoring and alerting
-- **devsecops**: Security monitoring
-- **platform-engineering**: Service mesh observability
-- **backend-dev-guidelines**: Application instrumentation
-
----
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-🎯 SKILL ACTIVATED: observability-engineering
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-
-**Total Resources:** 6 focused guides on observability engineering
-**Focus:** Distributed tracing, OpenTelemetry, APM, cost optimization

package/.claude/skills/observability-engineering/resources/apm-tools.md

@@ -1,97 +0,0 @@
-# APM Tools
-
-Comparison and guide to Application Performance Monitoring tools: DataDog, New Relic, Dynatrace.
-
-## DataDog
-
-```typescript
-// DataDog APM
-import tracer from 'dd-trace';
-tracer.init({
-  service: 'my-app',
-  env: 'production',
-  version: '1.0.0',
-});
-
-// Auto-instruments Express, Prisma, Redis, etc.
-```
-
-**Pros:**
-- ✅ Easy setup (auto-instrumentation)
-- ✅ Unified logs/metrics/traces
-- ✅ Great dashboards
-- ✅ APM + infrastructure monitoring
-
-**Cons:**
-- ❌ Expensive at scale
-- ❌ Vendor lock-in
-
-## New Relic
-
-```javascript
-// newrelic.js
-exports.config = {
-  app_name: ['My App'],
-  license_key: process.env.NEW_RELIC_LICENSE_KEY,
-  distributed_tracing: {
-    enabled: true,
-  },
-};
-
-// Load before app
-require('newrelic');
-const app = require('./app');
-```
-
-**Pros:**
-- ✅ Powerful query language (NRQL)
-- ✅ Good for complex architectures
-- ✅ Real-time alerting
-
-**Cons:**
-- ❌ Steeper learning curve
-- ❌ Can be expensive
-
-## Dynatrace
-
-```
-Dynatrace OneAgent (auto-deploys)
-- No code changes required
-- Full-stack monitoring
-```
-
-**Pros:**
-- ✅ AI-powered root cause analysis
-- ✅ Zero-code instrumentation
-- ✅ Enterprise features
-
-**Cons:**
-- ❌ Most expensive
-- ❌ Overkill for small teams
-
-## Cost Comparison
-
-```
-Small team (5 services, 1M spans/month):
-- DataDog: ~$500/month
-- New Relic: ~$400/month
-- Dynatrace: ~$800/month
-
-Large team (50 services, 100M spans/month):
-- DataDog: ~$5,000/month
-- New Relic: ~$4,000/month
-- Dynatrace: ~$10,000/month
-```
-
-## Open Source Alternative
-
-```
-Jaeger + Prometheus + Grafana = $0
-(but requires self-hosting and maintenance)
-```
-
----
-
-**Related Resources:**
-- observability-cost-optimization.md - Cost management
-- opentelemetry.md - Vendor-neutral instrumentation

package/.claude/skills/observability-engineering/resources/correlation-strategies.md

@@ -1,87 +0,0 @@
-# Correlation Strategies
-
-Guide to correlating logs, metrics, and traces for unified observability.
-
-## Trace ID Propagation
-
-```typescript
-import { trace, context } from '@opentelemetry/api';
-import { logger } from './logger';
-
-app.use((req, res, next) => {
-  const span = trace.getActiveSpan();
-  const traceId = span?.spanContext().traceId;
-
-  // Attach trace ID to logger context
-  req.logger = logger.child({ traceId });
-
-  next();
-});
-
-app.get('/users/:id', async (req, res) => {
-  req.logger.info('Fetching user', { userId: req.params.id });
-  // Log includes traceId automatically
-
-  const user = await getUser(req.params.id);
-  res.json(user);
-});
-```
-
-## Unified Observability
-
-```
-Request arrives:
-1. Generate trace ID
-2. Create span (trace)
-3. Emit metrics (counter, histogram)
-4. Log with trace ID
-
-All three pillars linked by trace ID:
-- Logs: {"traceId": "abc123", "message": "User fetched"}
-- Metrics: user_requests_total{trace_id="abc123"}
-- Traces: Trace abc123 shows spans
-```
-
-## Correlation in Practice
-
-```typescript
-// 1. Start span (tracing)
-const span = tracer.startSpan('handleRequest');
-const traceId = span.spanContext().traceId;
-
-// 2. Log with trace ID (logs)
-logger.info('Processing request', { traceId, userId: req.userId });
-
-// 3. Increment metric (metrics)
-requestCounter.add(1, { traceId, endpoint: '/users' });
-
-// 4. All linked by traceId
-span.end();
-```
-
-## Querying Across Pillars
-
-```
-# Find all logs for a trace
-traceId:"abc123"
-
-# Find traces with errors
-status:error AND service:"user-service"
-
-# Find metrics for specific trace
-trace_id="abc123" AND metric="http_request_duration"
-```
-
-## Best Practices
-
-✅ Always propagate trace IDs
-✅ Include trace IDs in all logs
-✅ Use trace IDs in metric labels (when cardinality allows)
-✅ Link dashboards (click log → view trace)
-✅ Standardize field names (traceId, spanId)
-
----
-
-**Related Resources:**
-- distributed-tracing.md - Trace propagation
-- logs-aggregation.md - Structured logging with trace IDs

package/.claude/skills/observability-engineering/resources/distributed-tracing.md

@@ -1,98 +0,0 @@
-# Distributed Tracing
-
-Guide to implementing distributed tracing with Jaeger, Tempo, and other tools.
-
-## What is Distributed Tracing?
-
-Tracks requests as they flow through microservices:
-
-```
-User Request
-  ↓
-API Gateway (span 1) ──→ 50ms
-  ↓
-User Service (span 2) ──→ 20ms
-  ↓
-Database (span 3) ──────→ 80ms
-Total: 150ms
-
-Trace shows:
-- Total request time: 150ms
-- Database was bottleneck: 80ms (53%)
-```
-
-## Jaeger Setup
-
-```yaml
-# docker-compose.yml
-version: '3'
-services:
-  jaeger:
-    image: jaegertracing/all-in-one:latest
-    ports:
-      - "16686:16686"  # UI
-      - "14268:14268"  # HTTP collector
-      - "6831:6831/udp"  # Agent
-```
-
-## Instrumentation
-
-```typescript
-import { trace, context, SpanStatusCode } from '@opentelemetry/api';
-
-const tracer = trace.getTracer('user-service');
-
-async function getUser(userId: string) {
-  const span = tracer.startSpan('getUser');
-  span.setAttribute('user.id', userId);
-
-  try {
-    const user = await db.users.findUnique({ where: { id: userId } });
-    span.setStatus({ code: SpanStatusCode.OK });
-    return user;
-  } catch (error) {
-    span.setStatus({
-      code: SpanStatusCode.ERROR,
-      message: error.message
-    });
-    span.recordException(error);
-    throw error;
-  } finally {
-    span.end();
-  }
-}
-```
-
-## Trace Propagation
-
-```typescript
-// Service A creates trace
-const span = tracer.startSpan('callServiceB');
-const headers = {};
-
-// Inject trace context into headers
-propagation.inject(context.active(), headers);
-
-// Call Service B with trace context
-await fetch('http://service-b/api', { headers });
-
-span.end();
-
-// Service B continues the trace
-const extractedContext = propagation.extract(context.active(), req.headers);
-const span = tracer.startSpan('handleRequest', {}, extractedContext);
-```
-
-## Best Practices
-
-✅ Trace critical paths
-✅ Add meaningful attributes
-✅ Sample high-volume endpoints
-✅ Keep span names consistent
-✅ Record errors in spans
-
----
-
-**Related Resources:**
-- opentelemetry.md - OTEL implementation
-- correlation-strategies.md - Trace ID usage

package/.claude/skills/observability-engineering/resources/logs-aggregation.md

@@ -1,118 +0,0 @@
-# Logs Aggregation
-
-Guide to ELK Stack, Loki, and structured logging for centralized log management.
-
-## ELK Stack (Elasticsearch, Logstash, Kibana)
-
-```yaml
-# docker-compose.yml
-version: '3'
-services:
-  elasticsearch:
-    image: elasticsearch:8.11.0
-    environment:
-      - discovery.type=single-node
-    ports:
-      - "9200:9200"
-
-  logstash:
-    image: logstash:8.11.0
-    volumes:
-      - ./logstash.conf:/usr/share/logstash/pipeline/logstash.conf
-
-  kibana:
-    image: kibana:8.11.0
-    ports:
-      - "5601:5601"
-```
-
-## Structured Logging
-
-```typescript
-import winston from 'winston';
-
-const logger = winston.createLogger({
-  format: winston.format.json(),
-  transports: [
-    new winston.transports.Console(),
-  ],
-});
-
-logger.info('User logged in', {
-  userId: 'user-123',
-  ipAddress: req.ip,
-  traceId: span.spanContext().traceId,  // Correlation
-  timestamp: new Date().toISOString(),
-});
-
-// Output:
-// {"level":"info","message":"User logged in","userId":"user-123","traceId":"abc123",...}
-```
-
-## Grafana Loki
-
-```yaml
-# loki-config.yaml
-auth_enabled: false
-
-server:
-  http_listen_port: 3100
-
-ingester:
-  lifecycler:
-    ring:
-      kvstore:
-        store: inmemory
-      replication_factor: 1
-
-schema_config:
-  configs:
-    - from: 2020-10-24
-      store: boltdb-shipper
-      object_store: s3
-      schema: v11
-```
-
-```typescript
-// Ship logs to Loki
-import Pino from 'pino';
-
-const logger = Pino({
-  transport: {
-    target: 'pino-loki',
-    options: {
-      batching: true,
-      interval: 5,
-      host: 'http://loki:3100',
-      labels: {
-        service: 'my-app',
-        env: 'production',
-      },
-    },
-  },
-});
-```
-
-## Log Levels
-
-```typescript
-logger.error('Payment failed', { orderId: '123', error: err.message });
-logger.warn('High memory usage', { memoryMB: 850 });
-logger.info('User registered', { userId: 'user-456' });
-logger.debug('Cache miss', { key: 'user:123' });
-```
-
-## Best Practices
-
-✅ Use structured logging (JSON)
-✅ Include trace IDs for correlation
-✅ Log at appropriate levels
-✅ Avoid logging sensitive data (PII, passwords)
-✅ Set retention policies (30-90 days)
-✅ Index important fields
-
----
-
-**Related Resources:**
-- correlation-strategies.md - Linking logs with traces
-- observability-cost-optimization.md - Log retention costs

package/.claude/skills/observability-engineering/resources/observability-cost-optimization.md

@@ -1,141 +0,0 @@
-# Observability Cost Optimization
-
-Guide to managing observability costs through sampling, retention policies, and efficient practices.
-
-## Sampling Strategies
-
-### Head-Based Sampling
-```typescript
-// Sample 10% of traces
-const sampler = new TraceIdRatioBasedSampler(0.1);
-
-const sdk = new NodeSDK({
-  sampler,
-  // ...
-});
-
-// Pros: Simple, predictable cost
-// Cons: May miss rare errors
-```
-
-### Tail-Based Sampling
-```typescript
-// Sample based on outcome (keep all errors, 1% of success)
-const tailSampler = {
-  shouldSample: (span) => {
-    if (span.status.code === SpanStatusCode.ERROR) {
-      return true;  // Keep all errors
-    }
-    if (span.attributes['http.status_code'] >= 500) {
-      return true;  // Keep server errors
-    }
-    return Math.random() < 0.01;  // 1% of successful requests
-  },
-};
-
-// Pros: Keeps important traces, lower cost
-// Cons: More complex
-```
-
-## Retention Policies
-
-```
-Hot storage (recent, fast):
-- Traces: 7 days
-- Logs: 14 days
-- Metrics: 30 days
-
-Warm storage (archived, slower):
-- Traces: 30 days
-- Logs: 90 days
-- Metrics: 1 year
-
-Cold storage (compliance):
-- Logs: 7 years (compressed)
-```
-
-## Cost Breakdown
-
-```
-Typical observability costs (10 services, 1M RPM):
-
-DataDog:
-- APM: $2,000/month (100M spans)
-- Logs: $1,500/month (500 GB)
-- Metrics: $500/month
-- Total: $4,000/month
-
-Self-Hosted (Jaeger + Loki + Prometheus):
-- Infrastructure: $800/month
-- Maintenance: $3,000/month (0.3 engineer)
-- Total: $3,800/month
-
-Savings with optimization:
-- 90% sampling: $400 APM (vs $2,000)
-- 30-day retention: $500 logs (vs $1,500)
-- Total: $1,400/month (65% reduction)
-```
-
-## Optimization Strategies
-
-### 1. Sample Aggressively
-```
-High-volume endpoints: 1% sample rate
-Low-volume endpoints: 100% sample rate
-Errors: Always keep
-```
-
-### 2. Reduce Log Volume
-```typescript
-// Don't log every request
-if (req.path !== '/health' && req.path !== '/metrics') {
-  logger.info('Request', { method: req.method, path: req.path });
-}
-
-// Sample logs
-if (Math.random() < 0.1) {  // 10% of logs
-  logger.debug('Debug info', { ...details });
-}
-```
-
-### 3. Optimize Metric Cardinality
-```typescript
-// ❌ Bad: Unbounded cardinality
-requestCounter.add(1, { userId: req.userId });  // Millions of users
-
-// ✅ Good: Bounded cardinality
-requestCounter.add(1, { endpoint: req.route });  // ~100 endpoints
-```
-
-### 4. Use Cheaper Storage
-```
-S3 Glacier for old logs: $0.004/GB (vs $0.023/GB Standard)
-83% cheaper for infrequently accessed data
-```
-
-## Monitoring Observability Costs
-
-```typescript
-// Track observability data volume
-observabilityCostGauge.set(dailySpanCount * 0.0001);  // $0.0001 per span
-
-// Alert on cost spikes
-if (dailyObservabilityCost > threshold) {
-  alert('Observability costs exceeded budget');
-}
-```
-
-## Best Practices
-
-✅ Sample high-volume endpoints
-✅ Always keep errors
-✅ Set aggressive retention policies
-✅ Reduce metric cardinality
-✅ Use cheaper storage tiers
-✅ Monitor observability costs
-
----
-
-**Related Resources:**
-- distributed-tracing.md - Sampling implementation
-- logs-aggregation.md - Log retention