Radaros Observability Digest

Target: @radaros/observability Summary: Tracing, metrics, and structured logging for RadarOS agents.

🚀 Quick Start

Instrument agents or event buses instantly with multiple backends. Always flush on exit to guarantee telemetry dispatch.

import { Agent, openai } from "@radaros/core"
import { instrument } from "@radaros/observability"
 
const agent = new Agent({ name: "assistant", model: openai("gpt-4o") })
const obs = instrument(agent, { exporters: ["console", "langfuse"] })
 
await agent.run("Hello!")
await obs.tracer.flush() // Required before process exit

🔧 Configuration

Pass an ObservabilityConfig object to configure tracing, metrics, and logs.

• exporters: Array of ExporterShorthand ("console", "langfuse", "otel", "json-file") or custom TraceExporter instances.
• metrics: Boolean to enable MetricsCollector mapping (runs, avgDurationMs, totalTokens, estimatedKvCacheGb).
• structuredLogs: Set to true, "json", "console", or supply a custom LogDrain function (entry: LogEntry) => void for Pino/Winston integrations.

💡 Patterns & Best Practices

• Multi-Backend Routing: Combine shorthands in the exporters array to simultaneously stream telemetry across multiple tools (e.g., ["langfuse", "otel"]).
• Custom Integration Override: Use concrete instances like new LangfuseExporter({ baseUrl: "..." }) instead of shorthands when default environment variables are insufficient.
• Global Bus Attachment: Use instrumentBus(eventBus) to trace entire team workflows or swarms sharing a single bus, rather than manually attaching to individual sub-agents.
• Deep Metric Extraction: Access granular AI metrics via obs.metrics.getMetrics(). This explicitly tracks reasoningTokens, toolUsageFrequency, and cost estimations.
• Custom Log Drains: Inject a custom callback into structuredLogs to merge native agent traceId and spanId directly into your existing infrastructure logs.

🚨 Anti-patterns & Gotchas

• Memory Leaks on Dynamic Agents: Calling instrument(agent) dynamically inside request handlers without invoking obs.detach() leaves orphaned listeners on the EventBus.
• Missing Process Flush: Failing to await obs.tracer.flush() or await obs.tracer.shutdown() before process exit drops in-flight spans for asynchronous exporters like Langfuse or OTLP.
• Over-Instrumentation: Instrumenting both a parent team EventBus and its individual child agents simultaneously with identical exporters. This triggers duplicated traces and bloated telemetry pipelines.

🔍 References

• NPM Package: @radaros/observability
• Underlying Traced Events: agent.run, tool.call, tool.result, handoff.transfer, team.delegate, memory.extract, cache.hit, capacity.warning.