Agentium Observability 🔍

📦 Overview: Opt-in tracing, metrics & structured logging for Agentium.

🚀 Patterns

• Quick Attach: instrument(agent, { exporters: ["console", "langfuse"] })
• Bus-Level Hook: instrumentBus(team.eventBus) ➔ broad capture across workflows.
• Shorthands: "console" | "langfuse" | "otel" | "json-file" auto-map to env vars.
• Custom Sinks: new CallbackExporter(trace => ...) for proprietary backends.
• Metric Streaming: metrics.toPrometheus() or .stream() for timeseries ingestion.
• Rich Context: structuredLogs: "json" injects traceId/spanId into logs.

🚨 Anti-patterns

• Missing Flush: Process exit without await obs.tracer.flush() ➔ trace data loss.
• Hardcoded Secrets: Explicit publicKey/secretKey ➔ strictly use LANGFUSE_* env vars.
• Fragmented Setup: Manual new Tracer() + new MetricsCollector() ➔ use instrument().
• Zombie Hooks: Re-instrumenting without obs.detach() ➔ memory leaks/duplicate spans.

💡 Best Practices

• 🔧 Env-Driven Config: Map OTEL_EXPORTER_OTLP_ENDPOINT & LANGFUSE_BASE_URL for zero-code env parity.
• 🔧 Track Economics: Query MetricsSnapshot for total_cost_usd & cached_tokens / reasoning_tokens.
• 🔧 Quality Signals: Monitor correctionRate and avgCritiqueScore for agent evaluation.
• 🔧 Graceful Teardown: Bind process.on('SIGTERM') to obs.tracer.shutdown().
• 🔧 Hybrid Exporters: ["console", "json-file"] (Dev) vs. ["otel", "langfuse"] (Prod).