# server-performance-analysis **Repository Path**: suxikang/server-performance-analysis ## Basic Information - **Project Name**: server-performance-analysis - **Description**: No description available - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-07 - **Last Updated**: 2026-04-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # server-performance-analysis An AI agent toolkit for bare-metal, virtual-machine, Linux, and Kubernetes performance triage. This repository is designed to be reusable across multiple agent environments, including Codex, Claude Code, and OpenCode. Core idea: - the workflow lives in `SKILL.md` - the operational knowledge lives in `references/` - the executable collection helpers live in `scripts/` Platform differences are mostly about how you inject the workflow into the agent, not how the analysis itself works. It helps investigate: - high CPU usage - elevated steal time in VMs - high node load - CPU throttling - memory pressure and `OOMKilled` - I/O wait and disk saturation - network queueing, retransmits, and latency regressions - cases where `perf`, `bcc`, or `bpftrace` may be needed for a deeper dive ## Analysis Model This toolkit follows a macro-to-micro workflow: - macro observation confirm that something is abnormal - attribution determine which host, VM, Node, Pod, process, thread, or device owns the symptom - micro analysis locate the hot path with sampling or tracing - evidence packaging summarize what is proven, what remains uncertain, and what to do next The default tool order is: - statistics first - sampling second - tracing last The bundled scripts primarily help with the first stage and part of the second. Heavy profiling remains an explicit opt-in step. ## What's Included ### Core Assets - `SKILL.md` Main reusable workflow document for agents - `references/linux-performance-commands.md` Host, VM, and node command guidance - `references/virtualization-performance-triage.md` VM-specific triage for steal time, noisy neighbors, and virtual device bottlenecks - `references/kubernetes-performance-triage.md` Pod, container, and node triage guidance for Kubernetes - `references/advanced-profiling.md` Optional deep-dive notes for `perf`, `bcc`, `bpftrace`, and flame graphs - `references/perf-methodology.md` Macro-to-micro analysis model, tool-class decision order, and common failure patterns - `scripts/capture_host_snapshot.sh` Low-risk Linux host snapshot - `scripts/capture_k8s_snapshot.sh` Kubernetes snapshot for namespace, Pod, node, events, and cgroup evidence - `scripts/capture_snapshot.sh` Backward-compatible alias to the host snapshot script ### Optional Platform Adapter - `agents/openai.yaml` Optional Codex / OpenAI product metadata. Other platforms can ignore this file. ## Install And Use ### Generic Usage Clone the repository anywhere you like: ```bash git clone git@gitee.com:suxikang/server-performance-analysis.git ``` You can use it in a platform-neutral way by: - running the scripts in `scripts/` - giving `SKILL.md` to your agent as the main workflow prompt - adding relevant files from `references/` when deeper context is needed ### Codex-Specific Install If you want Codex to discover it as a local skill, clone or copy it into the Codex skills directory: ```bash git clone git@gitee.com:suxikang/server-performance-analysis.git ~/.codex/skills/server-performance-analysis ``` Restart Codex after installing so the new skill can be discovered. ## Usage Example scripts: ```bash ~/.codex/skills/server-performance-analysis/scripts/capture_host_snapshot.sh ``` ```bash ~/.codex/skills/server-performance-analysis/scripts/capture_k8s_snapshot.sh --namespace default --pod my-pod ``` ## Usage Guide ### 1. Choose the right entry path Use the skill in one of three common ways: - Linux or bare-metal host issue Use this when the machine itself is slow, load is high, I/O wait is high, or network latency is rising. - Virtual machine issue Use this when the guest looks unstable, latency is bursty, or you suspect steal time, noisy neighbors, or shared virtual infrastructure. - Kubernetes issue Use this when the symptom starts from a Pod, container, service, or Node inside a cluster. ### 2. Start with a natural-language prompt or shared workflow If you already have metrics, command output, or a clear symptom, give your agent: - the contents of `SKILL.md` - the symptom description - any relevant logs, command output, or snapshot files Generic examples: - `Analyze why this Linux host has high load and elevated iowait using the workflow in SKILL.md.` - `Analyze why this VM has unstable latency and possible steal time using the workflow in SKILL.md.` - `Investigate why this Kubernetes Pod has high CPU and occasional OOMKilled restarts using the workflow in SKILL.md.` ### 3. Collect a snapshot when evidence is incomplete For a host or VM: ```bash ~/.codex/skills/server-performance-analysis/scripts/capture_host_snapshot.sh ``` Or specify an output directory: ```bash ~/.codex/skills/server-performance-analysis/scripts/capture_host_snapshot.sh ./my-host-snapshot ``` For Kubernetes: ```bash ~/.codex/skills/server-performance-analysis/scripts/capture_k8s_snapshot.sh --namespace default --pod my-pod ``` Or target a label selector: ```bash ~/.codex/skills/server-performance-analysis/scripts/capture_k8s_snapshot.sh --namespace default --selector 'app=my-service' ``` ### 4. Review the generated files in this order After the script finishes, look at: 1. `missing-tools.txt` Check which optional tools were unavailable and what analysis is degraded. 2. `README.txt` Review limitations, fallback guidance, and the suggested reading order. 3. Core evidence files For hosts and VMs, start with `uptime.txt`, `top.txt`, `vmstat.txt`, `free.txt`, and `iostat.txt` if present. For Kubernetes, start with `events.txt`, `top_pods.txt`, `top_nodes.txt`, `pod_describe.txt`, and the cgroup-related files. ### 5. Feed the results back into Codex Once you have the snapshot, ask your agent to interpret it using `SKILL.md` plus the relevant references. Generic examples: - `Review these host snapshot files and tell me the most likely bottleneck using SKILL.md.` - `Review this Kubernetes snapshot and tell me whether the problem is Pod-level, Node-level, or platform-level using SKILL.md.` ### 6. Understand the fallback behavior - Missing optional tools do not stop the scripts. - Missing tools are summarized in `missing-tools.txt`. - `kubectl` is required for the Kubernetes script, but `kubectl top` is optional. - The skill does not auto-install missing packages. - On Kunpeng / aarch64, the base snapshots should still work, but advanced `perf` analysis may have more environmental constraints than on x86. ## Platform Usage ### Codex Recommended when you want native local skill discovery. - Install into `~/.codex/skills/server-performance-analysis` - Invoke it directly with: - `Use $server-performance-analysis to analyze why this Linux node has high load and elevated iowait.` - `Use $server-performance-analysis to investigate why this Kubernetes Pod has high latency, high CPU, and occasional OOMKilled restarts.` - Codex can also consume the snapshot directories generated by `scripts/` ### Claude Code Recommended when you want to use this repository as a promptable workflow plus script bundle. - Keep the repository in any working directory - Provide `SKILL.md` as the main workflow context - Attach or paste relevant files from `references/` only when needed - Run `scripts/capture_host_snapshot.sh` or `scripts/capture_k8s_snapshot.sh`, then ask Claude Code to interpret the results Example Claude Code prompts: - `Use the workflow in SKILL.md to analyze this host snapshot and tell me whether the bottleneck is CPU, memory, disk, network, or hypervisor-related.` - `Use SKILL.md and references/kubernetes-performance-triage.md to review this Kubernetes snapshot.` ### OpenCode Recommended when you want to use this repository as a reusable prompt pack and operational toolkit. - Keep the repository in any accessible project directory - Inject `SKILL.md` as the primary workflow document - Add specific files from `references/` when the investigation needs more depth - Use `scripts/` to collect evidence before asking for analysis Example OpenCode prompts: - `Use SKILL.md from this repository as the analysis workflow and review these VM snapshot files.` - `Use SKILL.md plus references/kunpeng-notes.md to assess whether this ARM64 performance issue needs deeper profiling.` ## Kubernetes Snapshot Inputs `capture_k8s_snapshot.sh` supports: - `--namespace ` required - `--pod ` or `--selector ` required - `--node ` optional - `--output-dir ` optional The script only depends on `kubectl` by default. `kubectl top` and `jq` are optional. ## Host And VM Snapshot Notes `capture_host_snapshot.sh` now also collects virtualization clues when available, including: - `systemd-detect-virt` - `hostnamectl` - `lscpu` - `lsblk` This helps distinguish guest-side hotspots from hypervisor or shared infrastructure issues. Both snapshot scripts now generate: - `README.txt` A summary of limitations, review order, and fallback guidance - `missing-tools.txt` A summary of missing optional tools and the diagnostic capabilities affected The current behavior is soft degradation only. Missing optional tools are reported, but the skill does not auto-install or auto-download anything. ## Notes - This repository is intentionally usable as a generic agent toolkit, not only as a Codex-native skill. - The skill is designed to start with low-risk commands and escalate only when evidence supports it. - `perf`, `bcc`, and `bpftrace` are optional deep-dive tools, not baseline requirements. - `kubectl` is a hard dependency for the Kubernetes snapshot script; `kubectl top` is not. - VM incidents may still require hypervisor or cloud-provider evidence even when in-guest metrics are collected. - On Kunpeng / aarch64, the basic snapshot flow is expected to work, but `perf` quality depends on kernel support, permissions, symbols, and unwind conditions. - The Kubernetes script does not SSH into nodes or run privileged host tooling automatically. ## License MIT. See `LICENSE`.