Agent skill

Systing Trace

by josefbacik in josefbacik/systing

Capture a Linux system trace with systing. An agent skill from josefbacik/systing.

MITAuto-check: notes

Install Systing Trace

skills CLI
$ npx skills add josefbacik/systing --skill systing-trace -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install josefbacik/systing systing-trace --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/josefbacik/systing.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/systing-trace .claude/skills/systing-trace && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
systing-trace
GitHub stars
179
Token cost
~3.2k tokens
SKILL.md length
1,348 words
Files
1
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Capture a Linux system trace with systing. An agent skill from josefbacik/systing.

  • The user wants to profile
  • SKILL.md covers Prerequisites, Common invocations, Recorders (what to capture) and Key options, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Record system activity (scheduling

What it does

Systing Trace is an agent skill from josefbacik/systing. Capture a Linux system trace with systing. Use when the user wants to profile, trace, or record system activity (scheduling, stacks, network, memory, syscalls, Python stacks, TPU ops/metrics) into a DuckDB or Perfetto file. Guides correct invocation of the systing binary as root, choosing recorders, targeting PIDs/cgroups/commands, and output formats.

Its SKILL.md is about 3.2k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It works with DuckDB, Linux and Python. The repository describes itself as: A libbpf based tracer to help figure out what an application is doing. The licence is MIT.

When your agent uses it

  • The user wants to profile
  • Record system activity (scheduling
  • TPU ops/metrics) into a DuckDB

Example prompts

  • “/systing-trace”

Requirements

  • Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit 8419894. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md (its code samples are bash).

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • ui.perfetto.dev

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Systing Trace loads about 3.2k tokens when it runs. Until then it costs about 92 tokens; SKILL.md has 1,348 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~92
When it runs · the whole SKILL.md, loaded when a task matches
~3.2k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

  • NoteRuns commands with sudoSKILL.md:19
    sudo systing --output trace.duckdb -- python3 myscript.py
  • NoteRuns commands with sudoSKILL.md:25
    sudo systing -p <PID> -d 10 --output trace.duckdb
  • NoteRuns commands with sudoSKILL.md:30
    sudo systing -c /sys/fs/cgroup/my.slice -d 30 --output trace.duckdb
  • NoteRuns commands with sudoSKILL.md:35
    sudo systing -d 5 --output trace.duckdb
  • NoteRuns commands with sudoSKILL.md:67
    sudo systing --add-recorder network --add-recorder syscalls -d 10 --output trace.duckdb
  • NoteRuns commands with sudoSKILL.md:72
    sudo systing --only-recorder sched --only-recorder network -d 10 --output trace.duckdb
  • NoteRuns commands with sudoSKILL.md:166
    sudo systing --tpu-profile -d 10 --output trace.duckdb
  • NoteRuns commands with sudoSKILL.md:169
    sudo systing --tpu-metrics --tpu-metrics-interval 500 \
  • NoteRuns commands with sudoSKILL.md:173
    sudo systing --tpu-profile --tpu-service-addr 127.0.0.1:8466 -d 10 --output trace.duckdb

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from josefbacik/systing at commit 8419894, republished under its MIT licence (© josefbacik). 1,348 words, ~3,211 tokens.

Download SKILL.mdSave it as .claude/skills/systing-trace/SKILL.md (or your agent's skills folder).
name
systing-trace
description
Capture a Linux system trace with systing. Use when the user wants to profile, trace, or record system activity (scheduling, stacks, network, memory, syscalls, Python stacks, TPU ops/metrics) into a DuckDB or Perfetto file. Guides correct invocation of the `systing` binary as root, choosing recorders, targeting PIDs/cgroups/commands, and output formats.

Capturing a trace with systing

systing is a BPF-based Linux tracer. It captures scheduling events, IRQs, stack traces, network activity, memory events, syscalls, and more into a DuckDB database (or Perfetto trace) for later analysis.

Prerequisites

  • Must run as root, or hold CAP_BPF + CAP_PERFMON (CAP_SYS_ADMIN also works). Use sudo.
  • Output: prefer --output foo.duckdb for analysis with the systing-analyze MCP server. The default is trace.pb (Perfetto), so always pass --output explicitly when you want DuckDB.

Common invocations

Trace a command from start to finish
bash
sudo systing --output trace.duckdb -- python3 myscript.py

Everything after -- is the command. Only the command, its threads, and children are traced.

Trace an existing PID for N seconds
bash
sudo systing -p <PID> -d 10 --output trace.duckdb
Trace a cgroup
bash
sudo systing -c /sys/fs/cgroup/my.slice -d 30 --output trace.duckdb
System-wide trace (no PID/cgroup filter)
bash
sudo systing -d 5 --output trace.duckdb

-d 0 (the default) means "run until Ctrl-C, or until the -- command exits".

Recorders (what to capture)

List available recorders and their defaults:

bash
systing --list-recorders
RecorderDefaultCaptures
schedonScheduler events (context switches, wakeups, runqueue)
irqonIRQ and softirq events (irq_handler_*, softirq_*)
cpu-stacksonOn-CPU perf stack samples
sleep-stacksonUninterruptible sleep (D-state) stacks
interruptible-stacksonInterruptible sleep (S-state) stacks
syscallsoffAll syscall entry/exit (raw_syscalls:sys_enter/sys_exit)
networkoffBase network recorder: socket/TCP connection state tracking
network-syscallsoffNetwork syscall-level tracing (send/recv bytes, buffer fill, stalls) — no per-packet probes
network-packetsoffPacket-level tracing (sendmsg, recvmsg, qdisc, drops, retransmits, RTT)
memoryoffRSS tracking, mmap/munmap/brk, page faults
memory-allocoffHeap allocator uprobes (malloc/calloc/realloc/free) with stacks
markersoffUserspace marker events (faccessat2 with mode=-975)
tpuoffTPU op-level profile via XLA runtime gRPC (port 8466)
tpu-metricsoffTPU runtime metrics polling (port 8431, lightweight)
task-stacksoffPeriodic stack snapshots of every targeted thread, blocked ones included (--task-stacks-interval-ms, default 100; --task-stacks-frames native|python|all). Output: the task_stack_event table and a Task Stacks: <thread> track in Perfetto. Needs Linux 6.2+; not with --continuous

Enable extras with --add-recorder:

bash
sudo systing --add-recorder network --add-recorder syscalls -d 10 --output trace.duckdb

Or restrict to only specific recorders with --only-recorder (disables every default first):

bash
sudo systing --only-recorder sched --only-recorder network -d 10 --output trace.duckdb
Recorder dependencies and companions
  • --add-recorder network also enables network-packets (the common investigation shape). --only-recorder network is state-only: connection/state tracking with no per-packet kprobes.
  • network-packets and network-syscalls each require the base network recorder and enable it implicitly.
  • memory-alloc requires and implicitly enables memory.
  • Recorders that are on by default can also be turned off directly: --no-sched, --no-irq, --no-cpu-stack-traces, --no-sleep-stack-traces, --no-interruptible-stack-traces, -n/--no-stack-traces (all stacks).

Key options

Targeting and duration
FlagPurpose
-p, --pid <PID>Target a specific process (repeatable)
-c, --cgroup <CGROUP>Target a cgroup path
-d, --duration <SEC>Duration in seconds (default 0 = until Ctrl-C or command exits)
--continuous <SEC>Rolling-window mode: keep only the last <SEC> seconds in the ring buffers. Cannot be combined with a -- <command>
-v, --verboseIncrease verbosity (repeatable)
Output
FlagPurpose
--output <PATH>Output file, format from extension: .duckdb, .pb/.perfetto, .systing/.systing.gz (profile export, see docs/PROFILE_EXPORT_FORMAT.md). Default trace.pb
--output-dir <DIR>Directory for intermediate parquet files (default ./traces)
--parquet-onlySkip final trace generation, keep only the parquet files
--stream <URI>Stream parquet over a socket instead of writing to disk: vsock://CID:PORT, unix:///path.sock, tcp://host:port (tcp is unauthenticated — trusted networks only)
Sampling and counters
FlagPurpose
--sample-freq <HZ>CPU stack-sampling rate per CPU (default 1000). Fixed-period mode: exact with --sw-event, and the rate at max CPU frequency for cpu-cycles
-s, --sw-eventUse a software clock event for sampling (VMs without a PMU)
--perf-counter <NAME>Sample a hardware/software counter, e.g. instructions, cycles, topdown* (repeatable)
--cpu-frequencyRecord CPU frequency tracks
Symbolization
FlagPurpose
--collect-pystacksResolve Python frames in user stacks
--task-stacks-frames native|python|allWith the task-stacks recorder, the frames to collect: kernel + native, Python alone (only threads that have any), or both. python and all turn --collect-pystacks on
--pystacks-debugDebug output for Python stack tracing
--enable-debuginfodBetter symbol resolution (requires DEBUGINFOD_URLS)
--collect-build-idStore user frames as (build-id, file offset) so exited processes stay symbolizable offline
--symbolize-names-onlyELF symbol tables only — no DWARF, no line info, no inline frames. Bounds symbolization memory on hosts with many debug binaries
--symbolize-elide-genericsCollapse generic/template args in symbol names longer than 256 bytes
--no-frame-labelsRender unsymbolized frames as bare hex instead of contextual labels
--no-gopclntabDon't symbolize stripped Go binaries from .gopclntab
--no-gvisor-guest-mapsDon't query gVisor sandboxes' control sockets for guest maps
Memory recorder tuning
FlagPurpose
--memory-fault-sample-rate <N>Sample 1 in N user page faults (default 97; 0/1 = all)
--memory-rss-threshold-bytes <N>Min byte drift between rss_stat events (default max(16 MiB, 64*nr_cpus*page_size); 0 = every event)
--memory-alloc-sample-rate <N>Sample 1 in N allocator calls (default 1). Values > 1 sample alloc/free independently, so alloc/free pairing for leak detection is unreliable — hotspot profiling only
--memory-alloc-lib <LIB>Override allocator library. Absolute path = host namespace verbatim; bare name resolved per-pid via /proc/<pid>/maps
--memory-alloc-symbol-prefix <P>Prefix for malloc/free symbol names (e.g. je_ for prefixed jemalloc)
Show full SKILL.md (593 more words)Show less
Custom events, markers, misc
FlagPurpose
--trace-event <EVENT> / --trace-event-pid <PID>Attach to additional probe points
--trace-event-config <FILE>JSON config defining custom events/tracks/stop triggers (see docs/TRACE_CONFIG_FORMAT.md)
--marker-threshold <N>Stop after N marker instant events — requires --continuous
--marker-duration-threshold <MS>Stop when a marker range exceeds MS ms — requires --continuous
--ringbuf-size-mib <N>Increase BPF ring buffer size if events are lost
--ringbuf-shards <N>Rings per ring-buffer family: 0 (default) = one per CPU up to 64 at a constant family byte budget, except on kernels before 6.8, which keep 8; 8 restores the fixed eight-ring layout exactly
--resolve-addressesResolve network IPs to hostnames via DNS (off by default)
--include-task-contextRecord what each sampled thread's program said it was working on: a program that uses the task-context library (crates/task-context) sets named values (a request id, an iteration number) on its threads, every running-stack sample then carries the id of its thread's context (stack_sample.task_context_id, and task_stack_event.task_context_id with the task-stacks recorder) and the values of each id go once into the task_context table. Finds a process whose executable carries the library or names it as a direct dependency (not one that loads it by dlopen or gets it through another library). Off: nothing of it is loaded. Written for Linux 6.12+, x86-64 and aarch64; reads nothing under the kernel's lockdown confidentiality mode
TPU
FlagPurpose
--tpu-profileOp-level TPU profile (same as --add-recorder tpu); requires a fixed --duration
--tpu-service-addr <HOST:PORT>Override auto-discovery for the profiler service (port 8466)
--tpu-metricsMetrics polling (same as --add-recorder tpu-metrics)
--tpu-metrics-addr <HOST:PORT>Override auto-discovery for the metrics service (port 8431)
--tpu-metrics-interval <MS>Metrics polling interval (default 1000 ms)

TPU profiling

Systing can talk to the XLA/TPU runtime's gRPC services to correlate TPU activity with host-side scheduling and stacks in the same trace.

Two modes (use either or both):

  • --tpu-profile — Full op-level profile. Connects to the XLA profiler service (port 8466), captures an XSpace profile for the trace duration, and records per-op timing, flops, and memory bytes into tpu_op / tpu_device. Heavier; only available while a workload is actively running, and requires a fixed --duration.
  • --tpu-metrics — Lightweight polling. Connects to the RuntimeMetricService (port 8431), samples counters (duty cycle, HBM usage, latency distributions) at --tpu-metrics-interval into tpu_metric. Always available while the runtime is up.

Auto-discovery: By default systing scans /proc/net/tcp (across all network namespaces) for a single listener on the well-known port and connects to it, using setns if the service is in a container's netns. Zero listeners → error ("Is a TPU workload running?"); multiple listeners → disambiguate with --tpu-service-addr / --tpu-metrics-addr.

bash
# Op-level TPU profile + host scheduling for 10s
sudo systing --tpu-profile -d 10 --output trace.duckdb

# Lightweight metrics at 500ms alongside network & sched
sudo systing --tpu-metrics --tpu-metrics-interval 500 \
    --add-recorder network -d 30 --output trace.duckdb

# Explicit address (container / multi-device host)
sudo systing --tpu-profile --tpu-service-addr 127.0.0.1:8466 -d 10 --output trace.duckdb

Output formats

  • .duckdb — Recommended. Queryable with the systing-analyze CLI and MCP tools.
  • .pb / .perfetto — Perfetto trace, viewable at ui.perfetto.dev. This is the default if --output is omitted.
  • .systing / .systing.gz — Line-oriented profile summary (interned stacks + counts + thread metadata), no DuckDB needed. See docs/PROFILE_EXPORT_FORMAT.md.
  • --parquet-only — Skip final output, keep raw parquet files in --output-dir.

After capturing

Once you have a .duckdb file, use the systing-analyze MCP tools (if available) or the systing-analyze CLI to analyze it. See the systing-analyze skill.

Troubleshooting

  • "Operation not permitted" → run with sudo (or grant CAP_BPF+CAP_PERFMON).
  • Lost events / ring buffer full → increase --ringbuf-size-mib (e.g. 64).
  • No stack frames resolved → add --enable-debuginfod with DEBUGINFOD_URLS set, or install debug symbols for the target binaries.
  • Symbolization eating memory (CI hosts, many debug binaries) → --symbolize-names-only, and --symbolize-elide-generics for heavily generic Rust/C++.
  • VM without hardware perf counters → add -s/--sw-event.
  • --marker-threshold rejected → marker thresholds require --continuous <seconds>.
  • "No TPU profiler/metrics service detected" → the XLA runtime isn't listening on 8466/8431. Make sure a TPU workload is running. If it's in a non-host netns systing will find it automatically; with multiple listeners, pass --tpu-service-addr / --tpu-metrics-addr.

© josefbacik, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in skills/systing-trace of josefbacik/systing.

Open the folder on GitHubat commit 8419894

Compare with similar skills

Systing Trace next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Systing Trace compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Systing Trace this skilljosefbacik/systing179—~3.2kAutomated safety check: NotesMIT
Excel and CSV Data Analysisbytedance/deer-flow84k4 repos~2.2kAutomated safety check: PassMIT
Apple Container Test RunnerRustPython/RustPython22k—~467Automated safety check: PassMIT
OrcaSlicer G-code Slicingearthtojake/text-to-cad19k—~989Automated safety check: PassMIT
The Art of Debuggingstas00/the-art-of-debugging1.7k—~6.1kAutomated safety check: NotesCC-BY-SA-4.0
Temporal Developerlatitude-dev/latitude-llm4.7k—~1.5kAutomated safety check: PassMIT

Similar skills

  • Excel and CSV Data Analysis

    bytedance/deer-flow

    Analyzes uploaded Excel and CSV files with SQL through DuckDB, producing schema inspections, statistical summaries and exports to CSV, JSON or Markdown.

    84k GitHub starsUsed in 4 repos~2.2k tokens
    Data & AnalyticsAuto-check passed
  • Apple Container Test Runner

    RustPython/RustPython

    Runs RustPython tests inside a Linux container built with Apple's container CLI, so macOS users can compare Linux results with their local ones.

    22k GitHub stars~467 tokensUpdated today
    Testing & QAAuto-check passed
  • OrcaSlicer G-code Slicing

    earthtojake/text-to-cad

    Slices STL, 3MF or OBJ models into printer-ready G-code with OrcaSlicer, either headless from the command line or by opening the model in the app.

    19k GitHub stars~989 tokensUpdated today
    Media & CreativeAuto-check passed
  • The Art of Debugging

    stas00/the-art-of-debugging

    Condensed debugging method and tool recipes for Unix, Python and PyTorch programs: crashes, hangs, segfaults, wrong output, CUDA OOM, NaN values and slowness.

    1.7k GitHub stars~6.1k tokensUpdated 3 days ago
    DevelopmentAuto-check: notes
  • Temporal Developer

    latitude-dev/latitude-llm

    This skill should be used when the user asks to "create a Temporal workflow", "write a Temporal activity", "debug stuck workflow", "fix non-determinism error", "Temporal Python", "Temporal…

    4.7k GitHub stars~1.5k tokensUpdated yesterday
    Backend & APIsAuto-check passed
  • Environment Setup

    Norman-bury/research-writing-skill

    A skill your agent uses when Python environment setup is needed for data visualization or conda installation is required

    3.4k GitHub stars~840 tokensUpdated 4 mo ago
    Data & AnalyticsAuto-check passed

More from josefbacik/systing

  • Systing Analyze

    josefbacik/systing

    Analyze a systing trace database (.duckdb). An agent skill from josefbacik/systing.

    179 GitHub stars~5.3k tokensUpdated yesterday
    Auto-check passed

Questions about Systing Trace

What does Systing Trace do?

Capture a Linux system trace with systing. An agent skill from josefbacik/systing. Systing Trace is an agent skill from josefbacik/systing. Capture a Linux system trace with systing.

When should I use Systing Trace?

Systing Trace fits situations like: the user wants to profile; record system activity (scheduling; TPU ops/metrics) into a DuckDB.

How do I install Systing Trace in Claude Code?

Run `npx skills add josefbacik/systing --skill systing-trace -a claude-code`. Or copy the skill folder (skills/systing-trace in josefbacik/systing) into .claude/skills/systing-trace in your project. Claude Code loads it when a task matches its description.

How do I install Systing Trace in Codex?

Run `npx skills add josefbacik/systing --skill systing-trace -a codex`. Or copy the skill folder (skills/systing-trace in josefbacik/systing) into .agents/skills/systing-trace in your project. Codex loads it when a task matches its description.

Can I use Systing Trace in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add josefbacik/systing --skill systing-trace -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/systing-trace, .gemini/skills/systing-trace, .github/skills/systing-trace and .opencode/skills/systing-trace in your project.

What does Systing Trace need to run?

SKILL.md names no scripts, command-line tools or credentials: Systing Trace is instructions for the agent only. Our summary lists: Python 3.

Does Systing Trace access the network?

SKILL.md names 1 domain. As links in the text: ui.perfetto.dev. This is read from the text; nothing was executed.

Is Systing Trace safe to install?

Our automated static check of SKILL.md found notes only (runs commands with sudo), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Systing Trace use?

Systing Trace is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Systing Trace use?

About 3.2k tokens (SKILL.md is roughly 13k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Systing Trace?

Skills that share tags, products or a category with Systing Trace: Excel and CSV Data Analysis (bytedance/deer-flow, 84k stars), Apple Container Test Runner (RustPython/RustPython, 22k stars), OrcaSlicer G-code Slicing (earthtojake/text-to-cad, 19k stars) and The Art of Debugging (stas00/the-art-of-debugging, 1.7k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Systing Trace?

josefbacik (a GitHub user) maintains it in josefbacik/systing, which has 179 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on October 8, 2026.

Source: josefbacik/systing on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.