elsabro 2.3.0 → 3.7.0

package/references/observability.md

@@ -0,0 +1,793 @@
+---
+name: observability
+description: Sistema de observabilidad con OpenTelemetry para ELSABRO
+version: 1.0.0
+---
+
+# ELSABRO Observability System
+
+## Vision General
+
+El sistema de observabilidad proporciona visibilidad completa de la ejecución de agentes, permitiendo debugging, optimización y monitoreo en tiempo real.
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                    OBSERVABILITY STACK                                    │
+├──────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   ┌────────────────────────────────────────────────────────────────┐    │
+│   │                      COLLECTION LAYER                           │    │
+│   │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │    │
+│   │  │  TRACES  │  │ METRICS  │  │   LOGS   │  │  EVENTS  │       │    │
+│   │  │ (Spans)  │  │(Counters)│  │(Struct.) │  │(Actions) │       │    │
+│   │  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘       │    │
+│   │       │             │             │             │              │    │
+│   └───────┼─────────────┼─────────────┼─────────────┼──────────────┘    │
+│           │             │             │             │                    │
+│           └─────────────┴─────────────┴─────────────┘                    │
+│                                   │                                      │
+│                                   ▼                                      │
+│   ┌────────────────────────────────────────────────────────────────┐    │
+│   │                    PROCESSING LAYER                             │    │
+│   │  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐   │    │
+│   │  │  Aggregation   │  │   Filtering    │  │   Enrichment   │   │    │
+│   │  │  (by agent)    │  │  (by severity) │  │  (context)     │   │    │
+│   │  └────────────────┘  └────────────────┘  └────────────────┘   │    │
+│   └────────────────────────────────────────────────────────────────┘    │
+│                                   │                                      │
+│                                   ▼                                      │
+│   ┌────────────────────────────────────────────────────────────────┐    │
+│   │                    EXPORT LAYER                                 │    │
+│   │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │    │
+│   │  │  Console │  │   File   │  │  Jaeger  │  │ Langtrace│       │    │
+│   │  │ (local)  │  │  (JSON)  │  │ (remote) │  │ (SaaS)   │       │    │
+│   │  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │    │
+│   └────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Componentes de Telemetría
+
+### 1. Traces (Distributed Tracing)
+
+Rastreo de ejecución a través de múltiples agentes y operaciones.
+
+```
+Trace: flow_execution_abc123
+│
+├── Span: flow.start
+│   ├── duration: 50ms
+│   └── attributes: { flowId, inputs }
+│
+├── Span: node.analyze (parallel)
+│   ├── Span: agent.Explore
+│   │   ├── duration: 12s
+│   │   └── attributes: { model: haiku, tokens: 2500 }
+│   ├── Span: agent.Plan
+│   │   ├── duration: 15s
+│   │   └── attributes: { model: haiku, tokens: 3200 }
+│   └── Span: agent.code-explorer
+│       ├── duration: 18s
+│       └── attributes: { model: haiku, tokens: 4100 }
+│
+├── Span: node.implement (parallel)
+│   ├── Span: agent.elsabro-executor
+│   │   ├── duration: 45s
+│   │   └── attributes: { model: opus, tokens: 15000 }
+│   └── Span: agent.elsabro-qa
+│       ├── duration: 30s
+│       └── attributes: { model: opus, tokens: 8000 }
+│
+└── Span: flow.complete
+    ├── duration: 2m 15s
+    └── attributes: { success: true, filesModified: 5 }
+```
+
+### 2. Metrics (Counters & Gauges)
+
+Métricas agregadas para monitoreo y alerting.
+
+```javascript
+// Counters
+elsabro.agents.invocations_total      // Total de invocaciones por agente
+elsabro.agents.errors_total           // Total de errores por agente
+elsabro.flows.executions_total        // Total de flows ejecutados
+elsabro.checkpoints.saved_total       // Total de checkpoints guardados
+
+// Gauges
+elsabro.agents.active                 // Agentes actualmente ejecutando
+elsabro.flows.active                  // Flows actualmente en progreso
+elsabro.memory.size_bytes             // Tamaño de memoria utilizada
+
+// Histograms
+elsabro.agents.duration_seconds       // Distribución de duración
+elsabro.agents.tokens_used            // Distribución de tokens usados
+elsabro.flows.duration_seconds        // Duración total de flows
+```
+
+### 3. Logs (Structured Logging)
+
+Logs estructurados con contexto para debugging.
+
+```json
+{
+  "timestamp": "2024-01-20T15:30:45.123Z",
+  "level": "INFO",
+  "message": "Agent execution completed",
+  "traceId": "abc123",
+  "spanId": "def456",
+  "agent": "elsabro-executor",
+  "model": "opus",
+  "duration_ms": 45000,
+  "tokens": {
+    "input": 5000,
+    "output": 10000,
+    "total": 15000
+  },
+  "result": "success",
+  "filesModified": ["src/auth/login.ts", "src/auth/login.test.ts"],
+  "context": {
+    "flowId": "development_flow",
+    "nodeId": "implement",
+    "sessionId": "ses_xyz"
+  }
+}
+```
+
+### 4. Events (Action Tracking)
+
+Eventos discretos para auditoría y analytics.
+
+```json
+{
+  "type": "agent.started",
+  "timestamp": "2024-01-20T15:30:00.000Z",
+  "data": {
+    "agentId": "elsabro-executor",
+    "nodeId": "implement",
+    "inputs": { "task": "Implement auth" }
+  }
+}
+
+{
+  "type": "checkpoint.saved",
+  "timestamp": "2024-01-20T15:30:45.000Z",
+  "data": {
+    "checkpointId": "chk_abc123",
+    "trigger": "PHASE_COMPLETE",
+    "phase": "implementation"
+  }
+}
+
+{
+  "type": "interrupt.triggered",
+  "timestamp": "2024-01-20T15:31:00.000Z",
+  "data": {
+    "interruptId": "int_xyz",
+    "type": "approval",
+    "reason": "Production deployment"
+  }
+}
+```
+
+---
+
+## API de Observability
+
+### TelemetryManager
+
+```javascript
+/**
+ * TelemetryManager
+ * Gestiona toda la telemetría de ELSABRO
+ */
+class TelemetryManager {
+  constructor(options = {}) {
+    this.config = {
+      serviceName: options.serviceName || 'elsabro',
+      environment: options.environment || 'development',
+      exporters: options.exporters || ['console'],
+      samplingRate: options.samplingRate || 1.0,
+      metricsInterval: options.metricsInterval || 60000
+    };
+
+    this.tracer = this.initTracer();
+    this.meter = this.initMeter();
+    this.logger = this.initLogger();
+
+    // Métricas predefinidas
+    this.metrics = this.initMetrics();
+  }
+
+  // ==================== Tracing ====================
+
+  /**
+   * Inicializa el tracer
+   */
+  initTracer() {
+    // OpenTelemetry compatible tracer
+    return {
+      activeSpans: new Map(),
+      completedSpans: [],
+
+      startSpan(name, options = {}) {
+        const spanId = `span_${Date.now()}_${Math.random().toString(36).substring(7)}`;
+        const span = {
+          spanId,
+          name,
+          traceId: options.traceId || `trace_${Date.now()}`,
+          parentSpanId: options.parentSpanId || null,
+          startTime: Date.now(),
+          endTime: null,
+          duration: null,
+          status: 'RUNNING',
+          attributes: options.attributes || {},
+          events: []
+        };
+
+        this.activeSpans.set(spanId, span);
+        return span;
+      },
+
+      endSpan(spanId, status = 'OK') {
+        const span = this.activeSpans.get(spanId);
+        if (span) {
+          span.endTime = Date.now();
+          span.duration = span.endTime - span.startTime;
+          span.status = status;
+          this.activeSpans.delete(spanId);
+          this.completedSpans.push(span);
+        }
+        return span;
+      },
+
+      addEvent(spanId, name, attributes = {}) {
+        const span = this.activeSpans.get(spanId);
+        if (span) {
+          span.events.push({
+            name,
+            timestamp: Date.now(),
+            attributes
+          });
+        }
+      },
+
+      setAttribute(spanId, key, value) {
+        const span = this.activeSpans.get(spanId);
+        if (span) {
+          span.attributes[key] = value;
+        }
+      }
+    };
+  }
+
+  /**
+   * Crea un span para ejecución de agente
+   */
+  startAgentSpan(agentId, options = {}) {
+    const span = this.tracer.startSpan(`agent.${agentId}`, {
+      traceId: options.traceId,
+      parentSpanId: options.parentSpanId,
+      attributes: {
+        'agent.id': agentId,
+        'agent.model': options.model || 'unknown',
+        'agent.node_id': options.nodeId,
+        'flow.id': options.flowId
+      }
+    });
+
+    // Incrementar contador
+    this.metrics.agentInvocations.add(1, { agent: agentId });
+
+    return span;
+  }
+
+  /**
+   * Finaliza un span de agente
+   */
+  endAgentSpan(span, result) {
+    // Agregar atributos del resultado
+    this.tracer.setAttribute(span.spanId, 'agent.tokens.input', result.tokensInput || 0);
+    this.tracer.setAttribute(span.spanId, 'agent.tokens.output', result.tokensOutput || 0);
+    this.tracer.setAttribute(span.spanId, 'agent.success', result.success);
+
+    if (result.error) {
+      this.tracer.setAttribute(span.spanId, 'agent.error', result.error);
+      this.metrics.agentErrors.add(1, { agent: span.attributes['agent.id'] });
+    }
+
+    // Registrar duración
+    const status = result.success ? 'OK' : 'ERROR';
+    const completedSpan = this.tracer.endSpan(span.spanId, status);
+
+    // Actualizar histogramas
+    this.metrics.agentDuration.record(completedSpan.duration / 1000, {
+      agent: span.attributes['agent.id']
+    });
+
+    this.metrics.agentTokens.record(
+      (result.tokensInput || 0) + (result.tokensOutput || 0),
+      { agent: span.attributes['agent.id'] }
+    );
+
+    return completedSpan;
+  }
+
+  /**
+   * Crea un span para ejecución de flow
+   */
+  startFlowSpan(flowId, options = {}) {
+    const span = this.tracer.startSpan(`flow.${flowId}`, {
+      attributes: {
+        'flow.id': flowId,
+        'flow.version': options.version,
+        'session.id': options.sessionId
+      }
+    });
+
+    this.metrics.flowsActive.add(1);
+    this.metrics.flowExecutions.add(1, { flow: flowId });
+
+    return span;
+  }
+
+  /**
+   * Finaliza un span de flow
+   */
+  endFlowSpan(span, result) {
+    this.tracer.setAttribute(span.spanId, 'flow.success', result.success);
+    this.tracer.setAttribute(span.spanId, 'flow.nodes_executed', result.nodesExecuted || 0);
+    this.tracer.setAttribute(span.spanId, 'flow.files_modified', result.filesModified?.length || 0);
+
+    const status = result.success ? 'OK' : 'ERROR';
+    const completedSpan = this.tracer.endSpan(span.spanId, status);
+
+    this.metrics.flowsActive.add(-1);
+    this.metrics.flowDuration.record(completedSpan.duration / 1000, {
+      flow: span.attributes['flow.id']
+    });
+
+    return completedSpan;
+  }
+
+  // ==================== Metrics ====================
+
+  /**
+   * Inicializa el meter para métricas
+   */
+  initMeter() {
+    return {
+      counters: new Map(),
+      gauges: new Map(),
+      histograms: new Map(),
+
+      createCounter(name, options = {}) {
+        const counter = {
+          name,
+          description: options.description,
+          value: 0,
+          labels: new Map(),
+
+          add(value, labels = {}) {
+            const key = JSON.stringify(labels);
+            const current = this.labels.get(key) || 0;
+            this.labels.set(key, current + value);
+            this.value += value;
+          }
+        };
+        this.counters.set(name, counter);
+        return counter;
+      },
+
+      createGauge(name, options = {}) {
+        const gauge = {
+          name,
+          description: options.description,
+          value: 0,
+
+          set(value) {
+            this.value = value;
+          },
+
+          add(delta) {
+            this.value += delta;
+          }
+        };
+        this.gauges.set(name, gauge);
+        return gauge;
+      },
+
+      createHistogram(name, options = {}) {
+        const histogram = {
+          name,
+          description: options.description,
+          buckets: options.buckets || [0.1, 0.5, 1, 2, 5, 10, 30, 60],
+          values: [],
+          labels: new Map(),
+
+          record(value, labels = {}) {
+            const key = JSON.stringify(labels);
+            if (!this.labels.has(key)) {
+              this.labels.set(key, []);
+            }
+            this.labels.get(key).push(value);
+            this.values.push(value);
+          },
+
+          getStats(labels = {}) {
+            const key = JSON.stringify(labels);
+            const values = this.labels.get(key) || this.values;
+
+            if (values.length === 0) return null;
+
+            const sorted = [...values].sort((a, b) => a - b);
+            return {
+              count: values.length,
+              sum: values.reduce((a, b) => a + b, 0),
+              min: sorted[0],
+              max: sorted[sorted.length - 1],
+              avg: values.reduce((a, b) => a + b, 0) / values.length,
+              p50: sorted[Math.floor(values.length * 0.5)],
+              p90: sorted[Math.floor(values.length * 0.9)],
+              p99: sorted[Math.floor(values.length * 0.99)]
+            };
+          }
+        };
+        this.histograms.set(name, histogram);
+        return histogram;
+      }
+    };
+  }
+
+  /**
+   * Inicializa métricas predefinidas
+   */
+  initMetrics() {
+    return {
+      // Counters
+      agentInvocations: this.meter.createCounter('elsabro.agents.invocations_total', {
+        description: 'Total agent invocations'
+      }),
+      agentErrors: this.meter.createCounter('elsabro.agents.errors_total', {
+        description: 'Total agent errors'
+      }),
+      flowExecutions: this.meter.createCounter('elsabro.flows.executions_total', {
+        description: 'Total flow executions'
+      }),
+      checkpointsSaved: this.meter.createCounter('elsabro.checkpoints.saved_total', {
+        description: 'Total checkpoints saved'
+      }),
+      interruptsTriggered: this.meter.createCounter('elsabro.interrupts.triggered_total', {
+        description: 'Total interrupts triggered'
+      }),
+
+      // Gauges
+      agentsActive: this.meter.createGauge('elsabro.agents.active', {
+        description: 'Currently active agents'
+      }),
+      flowsActive: this.meter.createGauge('elsabro.flows.active', {
+        description: 'Currently active flows'
+      }),
+
+      // Histograms
+      agentDuration: this.meter.createHistogram('elsabro.agents.duration_seconds', {
+        description: 'Agent execution duration',
+        buckets: [1, 5, 10, 30, 60, 120, 300]
+      }),
+      agentTokens: this.meter.createHistogram('elsabro.agents.tokens_used', {
+        description: 'Tokens used per agent',
+        buckets: [100, 500, 1000, 5000, 10000, 50000]
+      }),
+      flowDuration: this.meter.createHistogram('elsabro.flows.duration_seconds', {
+        description: 'Flow execution duration',
+        buckets: [10, 30, 60, 120, 300, 600, 1800]
+      })
+    };
+  }
+
+  // ==================== Logging ====================
+
+  /**
+   * Inicializa el logger estructurado
+   */
+  initLogger() {
+    return {
+      logs: [],
+      level: 'INFO',
+      levels: { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3 },
+
+      log(level, message, context = {}) {
+        if (this.levels[level] < this.levels[this.level]) return;
+
+        const entry = {
+          timestamp: new Date().toISOString(),
+          level,
+          message,
+          ...context,
+          service: 'elsabro'
+        };
+
+        this.logs.push(entry);
+
+        // Console output
+        const color = {
+          DEBUG: '\x1b[36m',
+          INFO: '\x1b[32m',
+          WARN: '\x1b[33m',
+          ERROR: '\x1b[31m'
+        }[level] || '';
+
+        console.log(`${color}[${level}]\x1b[0m ${message}`, context);
+
+        return entry;
+      },
+
+      debug(message, context) { return this.log('DEBUG', message, context); },
+      info(message, context) { return this.log('INFO', message, context); },
+      warn(message, context) { return this.log('WARN', message, context); },
+      error(message, context) { return this.log('ERROR', message, context); }
+    };
+  }
+
+  // ==================== Events ====================
+
+  /**
+   * Emite un evento
+   */
+  emit(eventType, data = {}) {
+    const event = {
+      type: eventType,
+      timestamp: new Date().toISOString(),
+      data,
+      service: this.config.serviceName,
+      environment: this.config.environment
+    };
+
+    // Log the event
+    this.logger.info(`Event: ${eventType}`, data);
+
+    return event;
+  }
+
+  // ==================== Dashboard ====================
+
+  /**
+   * Genera resumen de telemetría
+   */
+  getSummary() {
+    const agentStats = this.metrics.agentDuration.getStats();
+    const flowStats = this.metrics.flowDuration.getStats();
+
+    return {
+      timestamp: new Date().toISOString(),
+      agents: {
+        totalInvocations: this.metrics.agentInvocations.value,
+        totalErrors: this.metrics.agentErrors.value,
+        currentlyActive: this.metrics.agentsActive.value,
+        errorRate: this.metrics.agentInvocations.value > 0
+          ? (this.metrics.agentErrors.value / this.metrics.agentInvocations.value * 100).toFixed(2) + '%'
+          : '0%',
+        duration: agentStats ? {
+          avg: `${agentStats.avg.toFixed(2)}s`,
+          p50: `${agentStats.p50.toFixed(2)}s`,
+          p90: `${agentStats.p90.toFixed(2)}s`,
+          p99: `${agentStats.p99.toFixed(2)}s`
+        } : null
+      },
+      flows: {
+        totalExecutions: this.metrics.flowExecutions.value,
+        currentlyActive: this.metrics.flowsActive.value,
+        duration: flowStats ? {
+          avg: `${flowStats.avg.toFixed(2)}s`,
+          p50: `${flowStats.p50.toFixed(2)}s`,
+          p90: `${flowStats.p90.toFixed(2)}s`
+        } : null
+      },
+      checkpoints: {
+        total: this.metrics.checkpointsSaved.value
+      },
+      interrupts: {
+        total: this.metrics.interruptsTriggered.value
+      },
+      traces: {
+        active: this.tracer.activeSpans.size,
+        completed: this.tracer.completedSpans.length
+      }
+    };
+  }
+
+  /**
+   * Genera dashboard ASCII
+   */
+  renderDashboard() {
+    const summary = this.getSummary();
+
+    return `
+╔══════════════════════════════════════════════════════════════════════════╗
+║                      ELSABRO OBSERVABILITY DASHBOARD                      ║
+╠══════════════════════════════════════════════════════════════════════════╣
+║  ${new Date().toISOString().padEnd(72)}║
+╠══════════════════════════════════════════════════════════════════════════╣
+║  AGENTS                                                                   ║
+║  ├─ Total Invocations: ${String(summary.agents.totalInvocations).padEnd(10)} Active: ${String(summary.agents.currentlyActive).padEnd(5)}       ║
+║  ├─ Total Errors:      ${String(summary.agents.totalErrors).padEnd(10)} Error Rate: ${summary.agents.errorRate.padEnd(8)}   ║
+║  └─ Duration (p50/p90): ${summary.agents.duration ? `${summary.agents.duration.p50} / ${summary.agents.duration.p90}` : 'N/A'}                    ║
+║                                                                           ║
+║  FLOWS                                                                    ║
+║  ├─ Total Executions:  ${String(summary.flows.totalExecutions).padEnd(10)} Active: ${String(summary.flows.currentlyActive).padEnd(5)}       ║
+║  └─ Duration (avg):    ${summary.flows.duration ? summary.flows.duration.avg : 'N/A'}                                     ║
+║                                                                           ║
+║  SYSTEM                                                                   ║
+║  ├─ Checkpoints Saved: ${String(summary.checkpoints.total).padEnd(10)}                              ║
+║  ├─ Interrupts:        ${String(summary.interrupts.total).padEnd(10)}                              ║
+║  └─ Active Traces:     ${String(summary.traces.active).padEnd(10)}                              ║
+╚══════════════════════════════════════════════════════════════════════════╝
+    `;
+  }
+
+  // ==================== Export ====================
+
+  /**
+   * Exporta telemetría a diferentes formatos
+   */
+  export(format = 'json') {
+    const data = {
+      summary: this.getSummary(),
+      traces: this.tracer.completedSpans,
+      logs: this.logger.logs,
+      metrics: {
+        counters: Object.fromEntries(
+          [...this.meter.counters].map(([k, v]) => [k, { value: v.value, labels: Object.fromEntries(v.labels) }])
+        ),
+        gauges: Object.fromEntries(
+          [...this.meter.gauges].map(([k, v]) => [k, v.value])
+        ),
+        histograms: Object.fromEntries(
+          [...this.meter.histograms].map(([k, v]) => [k, v.getStats()])
+        )
+      }
+    };
+
+    if (format === 'json') {
+      return JSON.stringify(data, null, 2);
+    }
+
+    return data;
+  }
+}
+
+// Singleton instance
+let telemetryInstance = null;
+
+function getTelemetry(options) {
+  if (!telemetryInstance) {
+    telemetryInstance = new TelemetryManager(options);
+  }
+  return telemetryInstance;
+}
+
+module.exports = { TelemetryManager, getTelemetry };
+```
+
+---
+
+## Integración con Agentes
+
+### Instrumentación Automática
+
+```javascript
+// Wrapper para instrumentar agentes
+async function instrumentedAgentExecution(agent, inputs, context) {
+  const telemetry = getTelemetry();
+
+  // Crear span
+  const span = telemetry.startAgentSpan(agent.id, {
+    traceId: context.traceId,
+    parentSpanId: context.parentSpanId,
+    model: agent.model,
+    nodeId: context.nodeId,
+    flowId: context.flowId
+  });
+
+  telemetry.logger.info(`Agent started: ${agent.id}`, {
+    model: agent.model,
+    nodeId: context.nodeId
+  });
+
+  try {
+    // Ejecutar agente
+    const result = await executeAgent(agent, inputs);
+
+    // Finalizar span con éxito
+    telemetry.endAgentSpan(span, {
+      success: true,
+      tokensInput: result.usage?.input_tokens,
+      tokensOutput: result.usage?.output_tokens
+    });
+
+    telemetry.logger.info(`Agent completed: ${agent.id}`, {
+      duration_ms: span.duration,
+      tokens: result.usage?.total_tokens
+    });
+
+    return result;
+
+  } catch (error) {
+    // Finalizar span con error
+    telemetry.endAgentSpan(span, {
+      success: false,
+      error: error.message
+    });
+
+    telemetry.logger.error(`Agent failed: ${agent.id}`, {
+      error: error.message,
+      duration_ms: Date.now() - span.startTime
+    });
+
+    throw error;
+  }
+}
+```
+
+---
+
+## Comandos de Usuario
+
+### /elsabro:telemetry
+
+```bash
+/elsabro:telemetry dashboard    # Mostrar dashboard en tiempo real
+/elsabro:telemetry summary      # Resumen de métricas
+/elsabro:telemetry traces       # Ver traces recientes
+/elsabro:telemetry export       # Exportar telemetría a archivo
+/elsabro:telemetry reset        # Resetear métricas
+```
+
+---
+
+## Configuración
+
+### .planning/observability-config.json
+
+```json
+{
+  "observability": {
+    "enabled": true,
+    "serviceName": "elsabro",
+    "environment": "development",
+    "tracing": {
+      "enabled": true,
+      "samplingRate": 1.0,
+      "exporters": ["console", "file"]
+    },
+    "metrics": {
+      "enabled": true,
+      "interval": 60000,
+      "exporters": ["console"]
+    },
+    "logging": {
+      "level": "INFO",
+      "structured": true,
+      "exporters": ["console", "file"]
+    },
+    "exporters": {
+      "file": {
+        "path": ".planning/telemetry/",
+        "format": "json",
+        "rotation": "daily"
+      },
+      "jaeger": {
+        "enabled": false,
+        "endpoint": "http://localhost:14268/api/traces"
+      },
+      "langtrace": {
+        "enabled": false,
+        "apiKey": ""
+      }
+    }
+  }
+}
+```