Implements OpenTelemetry-compatible structured logging with correlation IDs, distributed tracing with parent-child span hierarchies, and metrics collection (counters, gauges, histograms). Correlates swarm agent activity with application-level telemetry and detects anomalies in latency, error rates, and resource usage.

Installation

claude --plugin-dir plugins/ruflo-observability

Agents

Agent	Model	Role
`observability-engineer`	sonnet	Structured logging, distributed tracing, metrics collection, agent-application telemetry correlation

Skills

Skills are auto-invoked via the Skill tool when their description matches the task (progressive disclosure). For an explicit CLI surface use the /observe slash command below.

Skill	Argument hint	Description
`observe-trace`	`<task-id>`	Trace agent execution by collecting spans and building a trace tree
`observe-metrics`	`[--period 1h]`	Aggregate and display system metrics with anomaly detection

Commands (5 subcommands)

observe trace <task-id>              # Trace agent execution with span tree
observe metrics [--period 1h]        # View aggregated metrics (p50, p95, p99)
observe logs [--level error]         # Filter structured logs by level
observe dashboard                    # Combined health dashboard
observe correlate <agent-id>         # Correlate all telemetry for an agent

Key Metrics

Metric	Type	Description
`agent_task_duration_seconds`	Histogram	Time to complete agent tasks
`agent_token_usage`	Counter	Tokens consumed per agent/model
`agent_active_count`	Gauge	Currently active agents
`agent_error_rate`	Counter	Errors per agent
`swarm_span_duration_ms`	Histogram	Span durations for tracing
`memory_operations_total`	Counter	AgentDB read/write counts

Trace Hierarchy

[root] swarm-task
  [child] agent-spawn (agent=architect)
  [child] agent-spawn (agent=coder)
    [child] file-read (path=src/auth.ts)
    [child] file-write (path=src/auth.ts)
  [child] agent-spawn (agent=tester)
    [child] test-run (suite=auth)

Log Format

JSON structured logs with timestamp, level, message, correlationId, agentId, taskId, spanId, traceId, duration_ms, and metadata.

Compatibility

CLI: pinned to @claude-flow/cli v3.6 major+minor.
Verification: bash plugins/ruflo-observability/scripts/smoke.sh is the contract.

Namespace coordination

This plugin owns the observability AgentDB namespace (base-name exception per ruflo-agentdb ADR-0001 §"Namespace convention", same precedent as federation and migrations). Reserved namespaces (pattern, claude-memories, default) MUST NOT be shadowed.

observability is accessed via memory_* tools (namespace-routed). Stores spans, metric snapshots, and log entries.

Routing note: Earlier versions of these skills used agentdb_hierarchical-recall with namespace argument — that tool family routes by tier and ignores namespace strings. ADR-0001 fixed the skills to use memory_* for namespaced reads and documented the dual pattern-store path for metric snapshots.

Verification

bash plugins/ruflo-observability/scripts/smoke.sh
# Expected: "10 passed, 0 failed"

Architecture Decisions

ADR-0001 — ruflo-observability plugin contract (namespace-routing fix, smoke as contract)

ruflo-agentdb — namespace convention owner; defines the routing rules ADR-0001 fixes a violation of
ruflo-cost-tracker -- Token usage metrics feed into cost attribution
ruflo-iot-cognitum -- Reuses Z-score anomaly detection for telemetry patterns
ruflo-market-data -- Data feed health and ingestion latency monitoring

License

MIT

As a mod

Function-hook mod (ADR-445 pattern, hooks/register.ts). It adds, with no network, no process spawning and no model call:

Guard (tighten-only, default on): refuses a memory write of telemetry (spans, logs, labels) that holds a secret, a US SSN or a spaced payment-card number (13-digit epoch timestamps are fine). The deny reason names the rule, never the value.
/observe-mod: local status and scan <text> (secret check, same rules as the guard).
Status file .claude-flow/observe-mod/status.json ({version:1, updatedMs, guard, checked, blocked, ...}), written at session start and when counters change.

Per-prompt context is deliberately not added: this plugin has nothing worth attaching to every prompt.

Option	Default	Effect
`guard`	`on`	refuse the calls above

Test: claude plugin validate plugins/ruflo-observability, claude plugin test plugins/ruflo-observability, bash plugins/ruflo-observability/scripts/smoke.sh.

README.md

ruflo-observability

Overview