The Complete Production SOP: How to Deploy and Run eBPF BCC Tools Kernel & System Performance Tracing in Autonomous AI Agents

---
name: "ebpf-bcc-kernel-troubleshooting"
description: "Diagnose elusive Linux performance bottlenecks, disk latency spikes, and socket drops using BCC."
metadata:
  author: "IO Visor Project"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "run bcc execsnoop"
  - "measure disk latency biolatency bcc"
  - "trace tcp connections tcptop"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

#!/usr/bin/env bash
set -euo pipefail

if ! command -v biolatency-bpfcc &>/dev/null && ! command -v /usr/sbin/biolatency-bpfcc &>/dev/null; then
  echo "Error: bpfcc-tools not installed or not in PATH" >&2
  exit 1
fi

KERNEL_HEADER_DIR="/lib/modules/$(uname -r)/build"
if [ ! -d "${KERNEL_HEADER_DIR}" ]; then
  echo "Error: Kernel headers missing at ${KERNEL_HEADER_DIR}" >&2
  exit 1
fi

echo "eBPF BCC environment verified for kernel $(uname -r)"

#!/usr/bin/env bash
# Execute 10-second bounded sample for block I/O latency distribution
sudo /usr/sbin/biolatency-bpfcc -m 10 1 > ./diagnostics/biolatency_report.txt

# Trace transient process creations with timestamps for 15 seconds
timeout 15s sudo /usr/sbin/execsnoop-bpfcc -T > ./diagnostics/execsnoop_trace.log || true

# Trace TCP retransmits indicating network congestion
timeout 15s sudo /usr/sbin/tcpretrans-bpfcc -l > ./diagnostics/tcpretrans_trace.log || true

import sys
import re

def parse_biolatency(filepath):
    with open(filepath, 'r') as f:
        content = f.read()
    
    # Check for tail latency spikes in > 64ms or > 128ms buckets
    outliers = re.findall(r'\s*(\d+)\s*->\s*(\d+)\s*:\s*(\d+)', content)
    severe_spikes = [b for b in outliers if int(b[0]) >= 64 and int(b[2]) > 0]
    
    if severe_spikes:
        print(f"CRITICAL: Detected {len(severe_spikes)} latency buckets >= 64ms:")
        for b in severe_spikes:
            print(f"  {b[0]}-{b[1]} ms: {b[2]} operations")
        sys.exit(2)
    print("OK: Disk I/O latency distribution within acceptable boundaries (<64ms).")

if __name__ == '__main__':
    parse_biolatency(sys.argv[1] if len(sys.argv) > 1 else 'diagnostics/biolatency_report.txt')