@flowtrace/clawdbot-plugin

Flowtrace observability plugin for Clawdbot - automatic tracing of agent activities, tool calls, and memory operations.

Features

• 📊 Automatic Tracing: Traces every agent run, tool call, and response
• 🧠 Memory Tracking: Automatically tracks memory store/recall/forget operations
• 🔗 Parent-Child Relationships: Tool calls are linked to their parent agent runs
• ⏱️ Duration Tracking: Measures time spent on each operation
• 🏷️ Rich Metadata: Captures session keys, workspace info, and more
• 📈 Dashboard Integration: View traces in Flowtrace UI

Installation

npm install @flowtrace/clawdbot-plugin

Setup

1. Start Flowtrace

Make sure Flowtrace is running. By default, it runs on http://localhost:9600.

# Using the Flowtrace desktop app
open /Applications/Flowtrace.app

# Or using the CLI
flowtrace serve

2. Configure the Plugin

Add to your clawdbot.json:

{
  "plugins": {
    "@flowtrace/clawdbot-plugin": {
      "enabled": true,
      "url": "http://localhost:9600",
      "tenant_id": 1,
      "project_id": 1
    }
  }
}

Or use environment variables:

export FLOWTRACE_URL="http://localhost:9600"
export FLOWTRACE_TENANT_ID="1"
export FLOWTRACE_PROJECT_ID="1"

3. Restart Clawdbot

clawdbot restart

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable or disable tracing | | url | string | http://localhost:9600 | Flowtrace server URL | | tenant_id | number | 1 | Tenant identifier | | project_id | number | 1 | Project identifier |

Commands

/flowtrace

Shows the current Flowtrace integration status:

📊 Flowtrace Status

• Enabled: Yes
• Server: http://localhost:9600
• Tenant: 1
• Project: 1

What Gets Traced

Agent Runs

Every time the agent processes a message:

• Session key and agent ID
• Workspace directory
• Message provider (Telegram, WhatsApp, etc.)
• Prompt length
• Duration and success status

Tool Calls

Every tool invocation:

• Tool name
• Input parameters
• Output/result
• Duration
• Error status (if any)

Memory Operations

When using memory plugins (e.g., memory-lancedb):

| Operation | Tracked Data | |-----------|--------------| | memory_store | Text, category, importance, memory ID | | memory_recall | Query, result count, relevance scores | | memory_forget | Memory ID, deleted text |

Viewing Traces

1. Open Flowtrace desktop app or navigate to http://localhost:9600
2. Go to Traces section
3. Filter by project, session, or time range
4. Click on a trace to see the timeline and details

Memory Dashboard

In Flowtrace, you can also view:

• Memory operation frequency
• Most recalled memories
• Store/recall ratio
• Memory search latency

Troubleshooting

Traces not appearing

1. Check that Flowtrace is running: curl http://localhost:9600/api/v1/health
2. Verify the plugin is enabled: Send /flowtrace command
3. Check logs for connection errors

Connection refused

Make sure the Flowtrace URL is correct and the server is accessible:

curl -X POST http://localhost:9600/api/v1/traces \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":1,"project_id":1,"agent_id":1,"session_id":1,"span_type":0}'

API Reference

The plugin sends traces to these Flowtrace endpoints:

| Endpoint | Purpose | |----------|---------| | POST /api/v1/traces | Generic traces (agent runs, errors) | | POST /api/v1/traces/tool | Tool call traces | | POST /api/v1/traces/memory | Memory operation traces |

License

MIT