Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(cost-tracker): P10 β€” telemetry export (Prometheus + webhook) (v0.13.0)

Reuven3ea80a9a9cb5
diff --git a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
index d1dc172dbc..fb962191ac 100644
--- a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
+++ b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-cost-tracker",
"description": "Token usage tracking, model cost attribution per agent, budget alerts, and optimization recommendations β€” uses memory_* (namespace-routed) for cost-tracking and cost-patterns; pairs with federation budget circuit breaker (ADR-097)",
- "version": "0.12.0",
+ "version": "0.13.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -27,6 +27,8 @@
"budget",
"model-outcome",
"trend-analysis",
- "ci"
+ "ci",
+ "prometheus",
+ "observability"
]
}
diff --git a/plugins/ruflo-cost-tracker/commands/ruflo-cost.md b/plugins/ruflo-cost-tracker/commands/ruflo-cost.md
index 79c85934a8..ae6fa13fc1 100644
--- a/plugins/ruflo-cost-tracker/commands/ruflo-cost.md
+++ b/plugins/ruflo-cost-tracker/commands/ruflo-cost.md
@@ -55,6 +55,12 @@ Cost tracking commands:
3. The script wraps `npx @claude-flow/cli hooks model-outcome -t ... -m ... -o ...` with explicit-argv spawnSync so quoting is safe
4. Without this, the router doesn't learn from cost-optimize recommendations and the Tier 1 bypass rate doesn't tighten over time
+**`cost export [--prometheus <path>] [--webhook <url>]`** -- Export cost-tracking telemetry to external observability systems.
+1. `--prometheus <path>` writes the node_exporter textfile-collector format (gauges + counters with session labels)
+2. `--webhook <url>` POSTs JSON; auth via `EXPORT_WEBHOOK_HEADER='K: V'`
+3. No flag β†’ stdout JSON
+4. Metrics emitted: `cost_tracker_total_usd`, `cost_tracker_tier_total_usd{tier=...}`, `cost_tracker_session_total_usd{session=...}`, `cost_tracker_session_messages{session=...}`, `cost_tracker_budget_usd`, `cost_tracker_budget_utilization`
+
**`cost conversation`** -- Per-conversation cost view: list every session in `cost-tracking` with started-at, message count, top model, total cost. Different lens from `cost report` (which is per-agent/per-model).
1. Run `node plugins/ruflo-cost-tracker/scripts/conversation.mjs`
2. Optional `CONV_FORMAT=json`, `CONV_LIMIT=N`, `CONV_NAMESPACE=...`
diff --git a/plugins/ruflo-cost-tracker/scripts/export.mjs b/plugins/ruflo-cost-tracker/scripts/export.mjs
new file mode 100755
index 0000000000..1874ec32d8
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/scripts/export.mjs
@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+// cost-export β€” emit cost-tracking telemetry in formats consumable by
+// external observability systems.
+//
+// Outputs:
+// --prometheus <path> write Prometheus textfile-collector exposition
+// --webhook <url> POST JSON payload (default Content-Type: application/json)
+// (no flag) write JSON to stdout
+//
+// Env:
+// EXPORT_NAMESPACE=cost-tracking (default)
+// EXPORT_WEBHOOK_HEADER='Authorization: Bearer xxx' optional, may repeat (comma-separated)
+// EXPORT_QUIET=1 suppress confirmation output (errors still printed)
+
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const NS = process.env.EXPORT_NAMESPACE || 'cost-tracking';
+
+function memoryListKeys() {
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'list',
+ '--namespace', NS, '--format', 'json',
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) return [];
+ const m = /\[[\s\S]*\]/.exec(r.stdout || '');
+ if (!m) return [];
+ try { return JSON.parse(m[0]).map((e) => e.key).filter(Boolean); } catch { return []; }
+}
+function memoryRetrieve(key) {
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'retrieve',
+ '--namespace', NS, '--key', key,
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) return null;
+ const m = /\{[\s\S]*\}/.exec(r.stdout || '');
+ if (!m) return null;
+ try { return JSON.parse(m[0]); } catch { return null; }
+}
+
+function gather() {
+ const keys = memoryListKeys();
+ const sessions = keys.filter((k) => k.startsWith('session-')).map(memoryRetrieve).filter(Boolean);
+ const budget = keys.filter((k) => /^budget-config(-\d+)?$/.test(k)).sort().reverse()
+ .map(memoryRetrieve).filter(Boolean)[0] || null;
+ const totalUsd = sessions.reduce((s, r) => s + (r.total_cost_usd || 0), 0);
+ const byTier = { haiku: 0, sonnet: 0, opus: 0, unknown: 0 };
+ for (const r of sessions) {
+ if (r.byTier) for (const [t, v] of Object.entries(r.byTier)) byTier[t] = (byTier[t] || 0) + v;
+ }
+ return { sessions, budget, totalUsd, byTier, exportedAt: new Date().toISOString() };
+}
+
+function escLabel(v) {
+ return String(v ?? '').replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+}
+
+function toPrometheus(data) {
+ const lines = [];
+ lines.push('# HELP cost_tracker_total_usd Total measured cost across all sessions in USD');
+ lines.push('# TYPE cost_tracker_total_usd gauge');
+ lines.push(`cost_tracker_total_usd ${data.totalUsd.toFixed(6)}`);
+ lines.push('');
+ lines.push('# HELP cost_tracker_tier_total_usd Total cost per tier across all sessions');
+ lines.push('# TYPE cost_tracker_tier_total_usd gauge');
+ for (const [tier, cost] of Object.entries(data.byTier)) {
+ lines.push(`cost_tracker_tier_total_usd{tier="${escLabel(tier)}"} ${(cost || 0).toFixed(6)}`);
+ }
+ lines.push('');
+ lines.push('# HELP cost_tracker_session_total_usd Cost per session in USD');
+ lines.push('# TYPE cost_tracker_session_total_usd gauge');
+ lines.push('# HELP cost_tracker_session_messages Assistant messages per session');
+ lines.push('# TYPE cost_tracker_session_messages counter');
+ for (const s of data.sessions) {
+ const sid = (s.sessionId || '').slice(0, 8);
+ lines.push(`cost_tracker_session_total_usd{session="${escLabel(sid)}"} ${(s.total_cost_usd || 0).toFixed(6)}`);
+ lines.push(`cost_tracker_session_messages{session="${escLabel(sid)}"} ${s.messageCount || 0}`);
+ }
+ if (data.budget?.budget_usd) {
+ lines.push('');
+ lines.push('# HELP cost_tracker_budget_usd Configured budget limit in USD');
+ lines.push('# TYPE cost_tracker_budget_usd gauge');
+ lines.push(`cost_tracker_budget_usd ${data.budget.budget_usd.toFixed(2)}`);
+ lines.push('# HELP cost_tracker_budget_utilization Spent / budget ratio (0.0β€“βˆž)');
+ lines.push('# TYPE cost_tracker_budget_utilization gauge');
+ lines.push(`cost_tracker_budget_utilization ${(data.totalUsd / data.budget.budget_usd).toFixed(6)}`);
+ }
+ return lines.join('\n') + '\n';
+}
+
+async function postWebhook(url, data) {
+ const headers = { 'Content-Type': 'application/json' };
+ if (process.env.EXPORT_WEBHOOK_HEADER) {
+ for (const h of process.env.EXPORT_WEBHOOK_HEADER.split(',')) {
+ const [k, ...rest] = h.split(':');
+ if (k && rest.length) headers[k.trim()] = rest.join(':').trim();
+ }
+ }
+ const resp = await fetch(url, {
+ method: 'POST', headers, body: JSON.stringify(data),
+ });
+ return { status: resp.status, ok: resp.ok };
+}
+
+function parseArgs() {
+ const args = process.argv.slice(2);
+ let prometheus = null, webhook = null;
+ for (let i = 0; i < args.length; i++) {
+ if (args[i] === '--prometheus') prometheus = args[++i];
+ else if (args[i] === '--webhook') webhook = args[++i];
+ }
+ return { prometheus, webhook };
+}
+
+async function main() {
+ const { prometheus, webhook } = parseArgs();
+ const data = gather();
+ if (process.env.EXPORT_QUIET !== '1') {
+ console.error(`Exported ${data.sessions.length} sessions, total $${data.totalUsd.toFixed(2)}`);
+ }
+ if (prometheus) {
+ mkdirSync(dirname(prometheus), { recursive: true });
+ writeFileSync(prometheus, toPrometheus(data));
+ if (process.env.EXPORT_QUIET !== '1') console.error(`Wrote Prometheus textfile: ${prometheus}`);
+ }
+ if (webhook) {
+ const r = await postWebhook(webhook, data);
+ if (!r.ok) {
+ console.error(`Webhook POST failed: HTTP ${r.status}`);
+ process.exit(1);
+ }
+ if (process.env.EXPORT_QUIET !== '1') console.error(`Webhook POST ok (HTTP ${r.status})`);
+ }
+ if (!prometheus && !webhook) {
+ console.log(JSON.stringify(data, null, 2));
+ }
+}
+
+main().catch((e) => { console.error('export failed:', e.message || e); process.exit(1); });
diff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.sh
index 0054824082..4aa3921a1f 100755
--- a/plugins/ruflo-cost-tracker/scripts/smoke.sh
+++ b/plugins/ruflo-cost-tracker/scripts/smoke.sh
@@ -8,10 +8,10 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.12.0 with new keywords"
+step "1. plugin.json declares 0.13.0 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.12.0" ]]; then
- bad "expected 0.12.0, got '$v'"
+if [[ "$v" != "0.13.0" ]]; then
+ bad "expected 0.13.0, got '$v'"
else
miss=""
for k in namespace-routing mcp agentic-flow agent-booster tier1-routing model-routing benchmarking verified telemetry budget; do
@@ -20,9 +20,9 @@ else
[[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
fi
-step "2. all ten skills present with valid frontmatter"
+step "2. all eleven skills present with valid frontmatter"
miss=""
-for s in cost-report cost-optimize cost-booster-route cost-booster-edit cost-compact-context cost-benchmark cost-track cost-budget-check cost-trend cost-conversation; do
+for s in cost-report cost-optimize cost-booster-route cost-booster-edit cost-compact-context cost-benchmark cost-track cost-budget-check cost-trend cost-conversation cost-export; do
f="$ROOT/skills/$s/SKILL.md"
[[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
for k in 'name:' 'description:' 'allowed-tools:'; do
@@ -321,6 +321,19 @@ step "39. ruflo-cost.md documents 'cost trend' subcommand"
grep -q "cost trend" "$ROOT/commands/ruflo-cost.md" \
&& ok || bad "missing"
+step "39a. cost-export skill + export.mjs (Prometheus + webhook)"
+F1="$ROOT/scripts/export.mjs"
+F2="$ROOT/skills/cost-export/SKILL.md"
+miss=""
+[[ -x "$F1" ]] || miss="$miss export-not-executable"
+node --check "$F1" 2>/dev/null || miss="$miss syntax-error"
+grep -q "cost_tracker_total_usd" "$F1" || miss="$miss no-prom-metric"
+grep -q "fetch(" "$F1" || miss="$miss no-webhook-fn"
+[[ -f "$F2" ]] || miss="$miss skill-missing"
+grep -q "export\.mjs" "$F2" || miss="$miss skill-no-script-ref"
+grep -q '^allowed-tools:[[:space:]]*\*' "$F2" && miss="$miss wildcard"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
step "40a. cost-conversation skill + conversation.mjs"
F1="$ROOT/scripts/conversation.mjs"
F2="$ROOT/skills/cost-conversation/SKILL.md"
diff --git a/plugins/ruflo-cost-tracker/skills/cost-export/SKILL.md b/plugins/ruflo-cost-tracker/skills/cost-export/SKILL.md
new file mode 100644
index 0000000000..15654a8a1f
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/skills/cost-export/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: cost-export
+description: Export cost-tracking telemetry in Prometheus textfile or webhook JSON formats β€” for external observability (Grafana, Datadog, custom dashboards)
+argument-hint: "[--prometheus <path>] [--webhook <url>]"
+allowed-tools: Bash
+---
+
+# Cost Export
+
+Pulls every `session-*` and `budget-config-*` record from `cost-tracking` and emits in formats consumable by external observability systems. Without this, cost data lives only inside the AgentDB namespace; with it, the same data lights up dashboards.
+
+## When to use
+
+- After any cost-track run, to refresh metrics for Grafana / Datadog / Prometheus.
+- Cron-friendly via `/loop 5m` to keep external dashboards near-real-time.
+- One-shot to a webhook for ad-hoc reporting (Slack, custom endpoint).
+
+## Steps
+
+1. **Pick a format** β€” textfile collector for Prometheus / Grafana, or webhook POST for everything else:
+
+ ```bash
+ # Prometheus node_exporter textfile collector
+ node plugins/ruflo-cost-tracker/scripts/export.mjs --prometheus /var/lib/node_exporter/textfile_collector/cost_tracker.prom
+
+ # Webhook (POSTs JSON; add auth via env)
+ EXPORT_WEBHOOK_HEADER='Authorization: Bearer $TOKEN' \
+ node plugins/ruflo-cost-tracker/scripts/export.mjs --webhook https://hooks.example.com/cost-tracker
+
+ # Stdout JSON (default if no flag)
+ node plugins/ruflo-cost-tracker/scripts/export.mjs
+ ```
+
+2. **Inspect what's emitted** β€” Prometheus output includes:
+
+ ```
+ cost_tracker_total_usd <gauge>
+ cost_tracker_tier_total_usd{tier="opus|sonnet|haiku"} <gauge>
+ cost_tracker_session_total_usd{session="<8-char>"} <gauge>
+ cost_tracker_session_messages{session="<8-char>"} <counter>
+ cost_tracker_budget_usd <gauge> (if budget configured)
+ cost_tracker_budget_utilization <gauge> (spent / budget)
+ ```
+
+3. **Webhook payload shape** β€” the JSON the webhook receives matches the stdout JSON: `{ exportedAt, sessions: [...], budget, totalUsd, byTier }`. Headers may be added via `EXPORT_WEBHOOK_HEADER='K1: V1, K2: V2'` (comma-separated).
+
+## Env overrides
+
+| Env | Default | Purpose |
+|---|---|---|
+| `EXPORT_NAMESPACE` | `cost-tracking` | Override target namespace |
+| `EXPORT_WEBHOOK_HEADER` | unset | Comma-separated `K: V` pairs for webhook auth |
+| `EXPORT_QUIET=1` | unset | Suppress non-error confirmation output |
+
+## Cross-references
+
+- `cost-track` β€” produces the data this skill exports
+- `cost-budget-check` β€” the same `cost_tracker_budget_*` metrics are alertable in Prometheus
+- node_exporter textfile collector docs (Prometheus convention) β€” drop the `.prom` file in the collector directory and Prometheus picks it up