From b50949293e3158971cb4ba47f6ff2685e34fb251 Mon Sep 17 00:00:00 2001 From: itdevwu Date: Fri, 24 Jul 2026 02:58:12 +0800 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20docs:=20route=20skill=20by?= =?UTF-8?q?=20workload=20type?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 11 ++++-- skills/xprobe-measure-latency/SKILL.md | 37 +++++++++++-------- .../xprobe-measure-latency/agents/openai.yaml | 4 +- .../references/setup.md | 35 ++++++++++++++++++ tests/agent-contract/test_contract.py | 9 ++++- 5 files changed, 74 insertions(+), 22 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e67d1e1..f6bab9c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,10 +36,13 @@ ## Agent workflow - Follow `skills/xprobe-measure-latency/SKILL.md` for measurement tasks. -- For an unknown workload, progress from readiness and baseline through a broad, - representative bounded inventory, evidence-based selector narrowing, - validation, and one detailed bounded measurement per stated hypothesis. Scope - breadth and capture duration are independent. Do not guess selectors. +- Classify a workload as CPU-only or GPU/mixed before choosing collectors. + `discover` is only for CUDA context holders; CPU-only work proceeds with its + selected PID and host selectors. For GPU/mixed work, progress from readiness + and baseline through a broad, representative bounded inventory, + evidence-based selector narrowing, validation, and one detailed bounded + measurement per stated hypothesis. Scope breadth and capture duration are + independent. Do not guess selectors. - Read evidence pairs, artifact analysis, stream identity, collection quality, and profiler overhead before interpreting latency. Summed concurrent GPU duration is not wall time. diff --git a/skills/xprobe-measure-latency/SKILL.md b/skills/xprobe-measure-latency/SKILL.md index 6a37512..8ecc398 100644 --- a/skills/xprobe-measure-latency/SKILL.md +++ b/skills/xprobe-measure-latency/SKILL.md @@ -20,25 +20,32 @@ CLI and selector syntax is in [references/cli-contract.md](references/cli-contra yourself; do not ask the user to perform a separate CLI installation. Confirm every JSON response has `schema_version: "2.0"`; do not assume a pre-0.3 or future protocol is compatible with this Skill. -2. Establish an application-level latency baseline. Wait for process readiness, - CUDA context creation, JIT compilation, and warmup before discovery. Keep a - repeatable request or batch trigger ready for the measurement window. +2. Establish an application-level latency baseline, process readiness, and + warmup. Classify the workload before selecting collectors: for CPU-only work, + choose the owning PID and skip CUDA discovery; for GPU or mixed work, wait + for CUDA context creation and JIT warmup before discovery. Keep a repeatable + request or batch trigger ready for the measurement window. 3. Run `xprobe doctor --json --non-interactive --no-color`. Check individual capabilities; `ok: true` only means diagnosis completed. -4. Run `xprobe discover --pid ROOT_PID --limit 200 --json --non-interactive - --no-color`. It returns NVML-confirmed CUDA context holders under that process - tree. Choose a worker from workload, PID/start-time, command line, and GPU - UUID evidence. Measure workers separately when several ranks are relevant. -5. Map the workload before choosing a name. Validate broad kernel, memcpy, or - memset activity endpoints, then collect one bounded, representative coarse - inventory per event family with `--events-out`. Scope breadth and collection - duration are independent: keep the selector broad, but choose a duration that +4. For GPU or mixed work, run `xprobe discover --pid ROOT_PID --limit 200 --json + --non-interactive --no-color`. It returns NVML-confirmed CUDA context holders + under that process tree. Choose a worker from workload, PID/start-time, + command line, and GPU UUID evidence. Measure workers separately when several + ranks are relevant. For CPU-only work, do not run `discover`; continue with + the selected process PID. +5. Map GPU or mixed work before choosing a name. Validate broad kernel, memcpy, + or memset activity endpoints, then collect one bounded, representative coarse + inventory per event family with `--events-out`. For CPU-only work, resolve and + validate the intended host-function boundary directly; do not require CUDA or + CUPTI. Scope breadth and collection duration are independent: keep the + selector broad where an activity inventory exists, but choose a duration that covers the workload cycle being diagnosed. Give `--max-events` headroom. -6. Run `scripts/analyze_trace.py` on each coarse artifact. Use kernel names, - selector hints, duration aggregates, launch variants, stream distribution, - busy union, overlap factor, and adjacent gaps to form one narrow hypothesis. Read +6. For GPU artifacts, run `scripts/analyze_trace.py`. Use kernel names, selector + hints, duration aggregates, launch variants, stream distribution, busy union, + overlap factor, and adjacent gaps to form one narrow hypothesis. Read [references/trace-analysis.md](references/trace-analysis.md) when interpreting - the report. + the report. For CPU-only work, use resolved host selectors and result evidence + to form the hypothesis instead. 7. Run `xprobe validate --pid WORKER_PID --from SELECTOR --to SELECTOR --match POLICY --json --non-interactive --no-color`. Stop when `valid` is false. If `agent_activation` is `injection_required`, disclose that `measure` will diff --git a/skills/xprobe-measure-latency/agents/openai.yaml b/skills/xprobe-measure-latency/agents/openai.yaml index 87dfb4b..1619cb2 100644 --- a/skills/xprobe-measure-latency/agents/openai.yaml +++ b/skills/xprobe-measure-latency/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Xprobe Latency Measurement" - short_description: "Map broad CPU and GPU latency evidence" - default_prompt: "Use $xprobe-measure-latency to map this workload broadly, then measure the suspected latency boundary precisely." + short_description: "Route CPU and GPU latency investigations" + default_prompt: "Use $xprobe-measure-latency to classify this workload as CPU-only or GPU/mixed, then measure the suspected latency boundary." diff --git a/skills/xprobe-measure-latency/references/setup.md b/skills/xprobe-measure-latency/references/setup.md index 3fb109c..bd22288 100644 --- a/skills/xprobe-measure-latency/references/setup.md +++ b/skills/xprobe-measure-latency/references/setup.md @@ -36,6 +36,41 @@ PATH, permission, driver, CUDA, or CUPTI failures explicitly and adjust from the reported detail; do not continue to measurement on an unverified installation. The CLI needs no Node.js. CUDA is optional until a GPU selector is measured. +## Build locally when the release is unsuitable + +The `glibc 2.34` requirement applies to the precompiled release archive. When +that archive cannot run on the host, build the matching source locally with the +host glibc instead. This is a local-use fallback, not permission to weaken the +release package's `GLIBC_2.34` ceiling. + +```bash +git clone --depth 1 --branch v0.3.2 https://github.com/itdevwu/xprobe.git +cd xprobe +mamba env create --file environment.yml +mamba run -n xprobe-dev just build +export PATH="$PWD/target/debug:$PATH" +xprobe --version +xprobe doctor --json --non-interactive --no-color +``` + +For CPU-only work, this build is sufficient; no CUDA toolkit or CUPTI Agent is +required. Do not use `scripts/package-release.sh` for this path because it +enforces the distributable archive compatibility policy. + +For GPU or mixed work, build one local Agent against the target's CUDA 12 or +CUDA 13 toolkit, then point the CLI at it: + +```bash +mamba run -n xprobe-dev env CUDA_PATH=/opt/cuda-12 cmake -S . -B build/cuda12 -G Ninja \ + -DXPROBE_BUILD_BPF=ON -DXPROBE_REQUIRE_CUPTI=ON -DXPROBE_CUDA_MAJOR=12 +mamba run -n xprobe-dev cmake --build build/cuda12 --target xprobe-bpf xprobe-cupti +export XPROBE_CUPTI_AGENT_PATH="$PWD/build/cuda12/cupti/libxprobe-cupti.so" +``` + +Replace `12` and the toolkit path with `13` for CUDA 13. CUDA/CUPTI majors other +than 12 or 13 are not supported: do not force an Agent build or bypass the +version check. + ## Repair the Skill only when needed The user normally installed this Skill before invoking the agent. When its files diff --git a/tests/agent-contract/test_contract.py b/tests/agent-contract/test_contract.py index 850dc69..8b28c13 100755 --- a/tests/agent-contract/test_contract.py +++ b/tests/agent-contract/test_contract.py @@ -74,6 +74,9 @@ def check_skill(workspace: pathlib.Path) -> None: assert quality_field in normalized_skill for investigation_step in ( "application-level latency baseline", + "CPU-only", + "GPU or mixed", + "do not run `discover`", "representative coarse inventory", "Scope breadth and collection duration are independent", "scripts/analyze_trace.py", @@ -112,6 +115,7 @@ def check_skill(workspace: pathlib.Path) -> None: normalized_investigation = re.sub(r"\s+", " ", investigation) normalized_quality = re.sub(r"\s+", " ", quality) normalized_trace_analysis = re.sub(r"\s+", " ", trace_analysis) + normalized_setup = re.sub(r"\s+", " ", setup) for required in ( "Triton", "procfs start time", @@ -143,8 +147,11 @@ def check_skill(workspace: pathlib.Path) -> None: "npx skills@1 add", "xprobe --version", "xprobe doctor", + "host glibc", + "CUDA/CUPTI majors other than 12 or 13 are not supported", + "scripts/package-release.sh", ): - assert required in setup + assert required in normalized_setup engineering_rules = re.sub( r"\s+", " ", (workspace / "AGENTS.md").read_text() From def1ad525481e606b2dfcb8953ed3ce659a2aeb6 Mon Sep 17 00:00:00 2001 From: itdevwu Date: Fri, 24 Jul 2026 02:59:56 +0800 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=A6=20build:=20prepare=20v0.3.3=20?= =?UTF-8?q?release?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CMakeLists.txt | 2 +- Cargo.lock | 12 ++++++------ Cargo.toml | 2 +- README.md | 4 ++-- docs/agent-integration.md | 2 +- docs/cli-contract.md | 2 +- docs/installation.md | 12 ++++++------ install.sh | 4 ++-- skills/xprobe-measure-latency/SKILL.md | 2 +- skills/xprobe-measure-latency/references/setup.md | 12 ++++++------ tests/agent-contract/test_contract.py | 2 +- 11 files changed, 28 insertions(+), 28 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index e1cfaa7..f048aa7 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -1,6 +1,6 @@ cmake_minimum_required(VERSION 3.20) -project(xprobe VERSION 0.3.2 LANGUAGES C) +project(xprobe VERSION 0.3.3 LANGUAGES C) include(CTest) diff --git a/Cargo.lock b/Cargo.lock index 2c0957a..283a306 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -452,7 +452,7 @@ dependencies = [ [[package]] name = "xprobe-cli" -version = "0.3.2" +version = "0.3.3" dependencies = [ "clap", "serde_json", @@ -465,7 +465,7 @@ dependencies = [ [[package]] name = "xprobe-collector" -version = "0.3.2" +version = "0.3.3" dependencies = [ "libbpf-rs", "serde_json", @@ -474,7 +474,7 @@ dependencies = [ [[package]] name = "xprobe-core" -version = "0.3.2" +version = "0.3.3" dependencies = [ "nix", "object", @@ -484,7 +484,7 @@ dependencies = [ [[package]] name = "xprobe-correlator" -version = "0.3.2" +version = "0.3.3" dependencies = [ "regex", "serde_json", @@ -493,7 +493,7 @@ dependencies = [ [[package]] name = "xprobe-exporter" -version = "0.3.2" +version = "0.3.3" dependencies = [ "serde_json", "xprobe-protocol", @@ -501,7 +501,7 @@ dependencies = [ [[package]] name = "xprobe-protocol" -version = "0.3.2" +version = "0.3.3" dependencies = [ "schemars", "serde", diff --git a/Cargo.toml b/Cargo.toml index 22f3223..6fe8c05 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -10,7 +10,7 @@ members = [ resolver = "2" [workspace.package] -version = "0.3.2" +version = "0.3.3" edition = "2024" license = "Apache-2.0" repository = "https://github.com/itdevwu/xprobe" diff --git a/README.md b/README.md index b1e32fe..770dcbf 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ only installation action required from the user: ```bash npx skills@1 add \ - https://github.com/itdevwu/xprobe/tree/v0.3.2/skills/xprobe-measure-latency \ + https://github.com/itdevwu/xprobe/tree/v0.3.3/skills/xprobe-measure-latency \ --global ``` @@ -83,7 +83,7 @@ for safe reactivation. ## Support -| Surface | 0.3.2 support | +| Surface | 0.3.3 support | | --- | --- | | OS/architecture | Linux x86_64, glibc 2.34 or newer | | Host events | ELF function entry/return through PID-scoped uprobes | diff --git a/docs/agent-integration.md b/docs/agent-integration.md index 783af88..9421eb9 100644 --- a/docs/agent-integration.md +++ b/docs/agent-integration.md @@ -17,7 +17,7 @@ repairs the matching xprobe CLI itself: ```bash npx skills@1 add \ - https://github.com/itdevwu/xprobe/tree/v0.3.2/skills/xprobe-measure-latency \ + https://github.com/itdevwu/xprobe/tree/v0.3.3/skills/xprobe-measure-latency \ --global ``` diff --git a/docs/cli-contract.md b/docs/cli-contract.md index 6366b53..bbb0f60 100644 --- a/docs/cli-contract.md +++ b/docs/cli-contract.md @@ -1,6 +1,6 @@ # CLI contract -xprobe 0.3.2 exposes exactly four public commands: `doctor`, `discover`, +xprobe 0.3.3 exposes exactly four public commands: `doctor`, `discover`, `validate`, and `measure`. ## Common behavior diff --git a/docs/installation.md b/docs/installation.md index acd8e0d..3caf960 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -13,7 +13,7 @@ user needs to run: ```bash npx skills@1 add \ - https://github.com/itdevwu/xprobe/tree/v0.3.2/skills/xprobe-measure-latency \ + https://github.com/itdevwu/xprobe/tree/v0.3.3/skills/xprobe-measure-latency \ --global ``` @@ -28,7 +28,7 @@ The versioned bootstrap installs to `~/.local` without root access: ```bash curl --proto '=https' --tlsv1.2 -fsSL \ - https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.2/install.sh | sh + https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.3/install.sh | sh ``` The bootstrap downloads the release archive and its SHA256 file, verifies the @@ -47,7 +47,7 @@ prefix, download the script and pass `--prefix`: ```bash curl --proto '=https' --tlsv1.2 -fsSLO \ - https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.2/install.sh + https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.3/install.sh sh install.sh --prefix /opt/xprobe ``` @@ -59,7 +59,7 @@ script with `sudo`. The installer never elevates privileges itself. For a fully explicit archive workflow: ```bash -version=0.3.2 +version=0.3.3 base=https://github.com/itdevwu/xprobe/releases/download/v$version archive=xprobe-$version-linux-x86_64.tar.gz @@ -92,7 +92,7 @@ missing or damaged, manually install the complete version-matched directory: ```bash npx skills@1 add \ - https://github.com/itdevwu/xprobe/tree/v0.3.2/skills/xprobe-measure-latency \ + https://github.com/itdevwu/xprobe/tree/v0.3.3/skills/xprobe-measure-latency \ --global ``` @@ -101,7 +101,7 @@ installation names the target explicitly: ```bash npx --yes skills@1 add \ - https://github.com/itdevwu/xprobe/tree/v0.3.2/skills/xprobe-measure-latency \ + https://github.com/itdevwu/xprobe/tree/v0.3.3/skills/xprobe-measure-latency \ --agent codex --global --copy --yes ``` diff --git a/install.sh b/install.sh index b3f83fd..c8b183f 100755 --- a/install.sh +++ b/install.sh @@ -2,7 +2,7 @@ set -eu repository=${XPROBE_REPOSITORY:-itdevwu/xprobe} -version=${XPROBE_VERSION:-0.3.2} +version=${XPROBE_VERSION:-0.3.3} if [ -n "${XPROBE_PREFIX:-}" ]; then prefix=$XPROBE_PREFIX elif [ -n "${HOME:-}" ]; then @@ -19,7 +19,7 @@ Install a released xprobe binary and its CUDA Agents. Usage: install.sh [--version VERSION] [--prefix DIR] [--uninstall] Options: - --version VERSION Release to install (default: 0.3.2) + --version VERSION Release to install (default: 0.3.3) --prefix DIR Installation prefix (default: $HOME/.local) --uninstall Remove xprobe from the selected prefix -h, --help Show this help diff --git a/skills/xprobe-measure-latency/SKILL.md b/skills/xprobe-measure-latency/SKILL.md index 8ecc398..62f85df 100644 --- a/skills/xprobe-measure-latency/SKILL.md +++ b/skills/xprobe-measure-latency/SKILL.md @@ -15,7 +15,7 @@ CLI and selector syntax is in [references/cli-contract.md](references/cli-contra ## Workflow -1. Run `xprobe --version`. When the command is absent or not 0.3.2, read +1. Run `xprobe --version`. When the command is absent or not 0.3.3, read [references/setup.md](references/setup.md) and install or repair the CLI yourself; do not ask the user to perform a separate CLI installation. Confirm every JSON response has `schema_version: "2.0"`; do not assume a diff --git a/skills/xprobe-measure-latency/references/setup.md b/skills/xprobe-measure-latency/references/setup.md index bd22288..d2bf61a 100644 --- a/skills/xprobe-measure-latency/references/setup.md +++ b/skills/xprobe-measure-latency/references/setup.md @@ -7,7 +7,7 @@ command unless their environment prevents the agent from writing a usable prefix ## Check and bootstrap xprobe -Check the executable first. Continue only when it reports 0.3.2; otherwise run +Check the executable first. Continue only when it reports 0.3.3; otherwise run the bootstrap below: ```bash @@ -21,7 +21,7 @@ installing under `~/.local`: ```bash curl --proto '=https' --tlsv1.2 -fsSL \ - https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.2/install.sh \ + https://raw.githubusercontent.com/itdevwu/xprobe/v0.3.3/install.sh \ -o /tmp/xprobe-install.sh sh /tmp/xprobe-install.sh export PATH="$HOME/.local/bin:$PATH" @@ -44,7 +44,7 @@ host glibc instead. This is a local-use fallback, not permission to weaken the release package's `GLIBC_2.34` ceiling. ```bash -git clone --depth 1 --branch v0.3.2 https://github.com/itdevwu/xprobe.git +git clone --depth 1 --branch v0.3.3 https://github.com/itdevwu/xprobe.git cd xprobe mamba env create --file environment.yml mamba run -n xprobe-dev just build @@ -74,12 +74,12 @@ version check. ## Repair the Skill only when needed The user normally installed this Skill before invoking the agent. When its files -are missing or the version is not 0.3.2, install the complete version-matched +are missing or the version is not 0.3.3, install the complete version-matched directory through the Agent Skills CLI: ```bash npx skills@1 add \ - https://github.com/itdevwu/xprobe/tree/v0.3.2/skills/xprobe-measure-latency \ + https://github.com/itdevwu/xprobe/tree/v0.3.3/skills/xprobe-measure-latency \ --global ``` @@ -87,7 +87,7 @@ For non-interactive automation, select the host explicitly: ```bash npx --yes skills@1 add \ - https://github.com/itdevwu/xprobe/tree/v0.3.2/skills/xprobe-measure-latency \ + https://github.com/itdevwu/xprobe/tree/v0.3.3/skills/xprobe-measure-latency \ --agent codex --global --copy --yes ``` diff --git a/tests/agent-contract/test_contract.py b/tests/agent-contract/test_contract.py index 8b28c13..04b6691 100755 --- a/tests/agent-contract/test_contract.py +++ b/tests/agent-contract/test_contract.py @@ -143,7 +143,7 @@ def check_skill(workspace: pathlib.Path) -> None: ): assert required in normalized_trace_analysis for required in ( - "v0.3.2/install.sh", + "v0.3.3/install.sh", "npx skills@1 add", "xprobe --version", "xprobe doctor",