melisai

Linux performance diagnostics for AI agents. Single Go binary. Collects 67 BCC/eBPF tools + procfs metrics. Outputs structured JSON with health score, anomalies, and recommendations. Ships with an MCP server for interactive use from Claude Desktop, Cursor, or any MCP-compatible client.

$ sudo melisai collect --profile quick -o report.json

  melisai v0.1.1 | profile=quick | duration=10s

  Tier 1 (procfs)  ████████████████████████████████████████ 7/7   2.1s
  Tier 2 (BCC)     ████████████████████████████████████████ 4/4  10.3s

  Health Score:  68 / 100  ⚠️
  Anomalies:     cpu_utilization CRITICAL (98.7%)
                 load_average WARNING (3.2x CPUs)
  Recommendations: 2

  Report saved to report.json

Why melisai?

Most performance tools give you raw numbers. melisai gives you a diagnosis.

• Runs Brendan Gregg's USE Method automatically
• Flags anomalies with severity (warning/critical) using field-tested thresholds
• Computes a single health score (0-100) so an AI agent can decide what to do next
• Generates a context-aware AI prompt with 27 known anti-patterns
• Works over MCP (Model Context Protocol) so Claude/Cursor can diagnose a server interactively

Quick Start

# 1. Build (requires Go 1.23+, cross-compile from macOS/Linux)
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o melisai ./cmd/melisai/

# 2. Deploy
scp melisai root@server:/usr/local/bin/

# 3. Install BCC tools on the server (first time only)
ssh root@server "melisai install"

# 4. Run
ssh root@server "melisai collect --profile quick -o /tmp/report.json"

MCP Server

melisai includes a built-in Model Context Protocol server. AI agents connect over stdio and interactively diagnose system performance -- no file juggling required.

melisai mcp   # starts stdio JSON-RPC server

Claude Desktop / Cursor config (claude_desktop_config.json):

{
  "mcpServers": {
    "melisai": {
      "command": "ssh",
      "args": ["root@your-server", "/usr/local/bin/melisai", "mcp"]
    }
  }
}

Tools

Typical workflow

Agent                              melisai
  │                                   │
  ├── get_health ──────────────────►  │  "score: 68, cpu_utilization CRITICAL"
  │                                   │
  ├── explain_anomaly ─────────────►  │  "High CPU: root causes, what to check..."
  │   anomaly_id: cpu_utilization     │
  │                                   │
  ├── collect_metrics ─────────────►  │  Full JSON report with 67 BCC tools,
  │   profile: standard               │  histograms, events, stack traces,
  │   focus: stacks                   │  AI prompt included
  │                                   │
  └── (agent analyzes & recommends)   │

How It Works

melisai collects metrics at three tiers with automatic fallback:

Tier 1: /proc, /sys, ss, ethtool, dmesg  ← always works, no root
        Includes deep network diagnostics: conntrack, softnet,
        IRQ distribution, NIC hardware, TCP extended stats
Tier 2: 67 BCC tools (runqlat, bio...)   ← root + bcc-tools
Tier 3: native eBPF (cilium/ebpf)       ← root + kernel ≥ 5.8 + BTF

Collection runs in two phases to eliminate observer effect:

1. Phase 1 -- Tier 1 collectors capture clean baselines (CPU, memory, disk, network)
2. Phase 2 -- BCC/eBPF tools run without contaminating the baselines

The report includes:

Collection Profiles

# Quick health check
sudo melisai collect --profile quick -o report.json

# Full analysis
sudo melisai collect --profile standard --ai-prompt -o report.json

# Deep dive focused on disk
sudo melisai collect --profile deep --focus disk -o report.json

# Profile a specific process (24 BCC tools filter to this PID)
sudo melisai collect --profile standard --pid 12345 -o app.json

# Profile a container
sudo melisai collect --profile standard --cgroup /sys/fs/cgroup/system.slice/nginx.service -o nginx.json

# Compare before/after
melisai diff baseline.json current.json -o diff.json

Output Example

See doc/example_report.md for a full production example -- a server scoring 32/100 where a message broker fsync storm on HDD cascades into I/O starvation across all containers.

Abbreviated JSON:

{
  "metadata": {
    "tool": "melisai", "schema_version": "1.0.0",
    "hostname": "prod-web-01", "kernel_version": "6.8.0-90-generic",
    "cpus": 20, "memory_gb": 62, "profile": "standard", "duration": "30s"
  },
  "categories": {
    "cpu": [
      {"collector": "cpu_utilization", "tier": 1, "data": {"user_pct": 12.5, "iowait_pct": 0.3, "idle_pct": 85.2}},
      {"collector": "runqlat", "tier": 2, "histograms": [{"name": "runqlat", "unit": "us", "p50": 4, "p99": 64}]}
    ],
    "disk": [ ... ], "memory": [ ... ], "network": [ ... ],
    "process": [ ... ], "stacktrace": [ ... ], "container": [ ... ]
  },
  "summary": {
    "health_score": 85,
    "anomalies": [{"severity": "warning", "metric": "cpu_psi_pressure", "message": "CPU PSI: 12.5%"}],
    "resources": {"cpu": {"utilization_pct": 14.8, "saturation_pct": 0.4, "errors": 0}},
    "recommendations": [{"title": "Enable BBR", "commands": ["sysctl -w net.ipv4.tcp_congestion_control=bbr"]}]
  },
  "ai_context": {"prompt": "You are a Linux performance engineer. Analyze this report..."}
}

BCC Tools (67)

~84% coverage of Brendan Gregg's BPF observability diagram.

24 of these tools support --pid filtering for per-process analysis.

Anomaly Detection

29 threshold rules based on Gregg's recommended values:

Manual Usage (without AI)

melisai works perfectly as a standalone CLI tool — no AI agent required.

Getting Help

# General help — all commands and capabilities
melisai --help

# Detailed help for collect (profiles, flags, examples)
melisai collect --help

# Help for other commands
melisai diff --help
melisai install --help
melisai mcp --help
melisai capabilities --help

Typical Manual Workflow

# 1. Quick health check — see if something is obviously wrong
sudo melisai collect --profile quick -o quick.json

# 2. Read the summary
cat quick.json | python3 -m json.tool | head -30
# or use jq:
jq '.summary' quick.json

# 3. Check health score and anomalies
jq '.summary.health_score' quick.json                     # 0-100
jq '.summary.anomalies[]' quick.json                      # what's wrong
jq '.summary.recommendations[].title' quick.json          # what to fix

# 4. Deep dive into network
sudo melisai collect --profile standard --focus network -o net.json
jq '.categories.network[0].data.conntrack' net.json       # conntrack usage
jq '.categories.network[0].data.softnet_stats' net.json   # per-CPU drops
jq '.categories.network[0].data.listen_overflows' net.json # accept queue

# 5. Profile a specific process
sudo melisai collect --profile standard --pid $(pgrep nginx) -o nginx.json

# 6. Compare before/after a change
sudo melisai collect --profile quick -o before.json
# ... apply your fix ...
sudo melisai collect --profile quick -o after.json
melisai diff before.json after.json                        # human-readable
melisai diff before.json after.json -o diff.json           # JSON diff

# 7. Check what tools are available
melisai capabilities

Interpreting the Report

The JSON report has four main sections:

Network Deep Diagnostics — Manual Inspection

# Conntrack table usage
jq '.categories.network[0].data.conntrack' report.json

# Softnet drops (per-CPU) — any "dropped" > 0 is bad
jq '.categories.network[0].data.softnet.stats[] | select(.dropped > 0)' report.json

# Listen overflows (accept queue full) — rate-based
jq '.categories.network[0].data.tcp_ext | {listen_overflows, listen_drops, listen_overflow_rate}' report.json

# NIC ring buffer (is it maxed out?)
jq '.categories.network[0].data.interfaces[] | {name, driver, ring_rx_current, ring_rx_max, rx_discards}' report.json

# IRQ imbalance (check if one CPU handles all network interrupts)
jq '.categories.network[0].data.softnet.irq_distribution' report.json

# TCP memory pressure
jq '.categories.network[0].data.tcp_ext | {prune_called, tcp_abort_on_memory}' report.json

# All sysctls at a glance
jq '.categories.network[0].data.sysctls' report.json

# Socket memory and orphan sockets
jq '.categories.network[0].data.socket_mem' report.json

Useful jq One-Liners

# All critical anomalies
jq '.summary.anomalies[] | select(.severity == "critical")' report.json

# All recommendations with commands
jq '.summary.recommendations[] | {title, commands}' report.json

# USE metrics for all resources
jq '.summary.resources' report.json

# Top CPU-consuming processes
jq '.categories.process[0].data.top_by_cpu[:5]' report.json

# BCC histogram percentiles
jq '.categories.cpu[].histograms[]? | {name, p50, p99, max}' report.json

Architecture

cmd/melisai/           CLI (cobra) + MCP subcommand
internal/
  ├── collector/       7 Tier 1 collectors + BCC adapter
  ├── executor/        BCC runner, security, 67 parsers, registry
  ├── ebpf/            Native eBPF loader (cilium/ebpf, CO-RE)
  ├── mcp/             MCP server (4 tools, stdio JSON-RPC)
  ├── model/           Types, USE metrics, anomalies, health score
  ├── observer/        PID tracker, overhead measurement
  ├── orchestrator/    Two-phase execution, signal handling, profiles
  ├── output/          JSON, FlameGraph SVG, AI prompt generator
  ├── diff/            Report comparison engine
  └── installer/       Distro detection, package installation

Security: all BCC binaries are verified (root-owned, not world-writable, in allowed paths). No shell execution. Environment sanitized. Output capped at 50MB per tool.

Requirements

Tested distros

Development

# Run all 258 tests
go test ./... -v

# With race detector
go test ./... -race

# Lint
make lint

# Cross-compile
make build    # or: GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o melisai ./cmd/melisai/

# Validation tests (Linux + root + stress-ng)
make test-validation

Troubleshooting

License

Apache License 2.0