Function Call Tracing
Instrument C/C++ with -finstrument-functions for execution tracing and Perfetto visualisation
How do I install this agent skill?
npx skills add https://github.com/gadievron/raptor --skill function-call-tracingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a secure environment for tracing and profiling C/C++ applications. It uses a mandatory sandboxing mechanism for building and running untrusted code, and the native instrumentation and conversion tools include safety checks for memory management and input parsing.
- Socketwarn
1 alert: gptSecurity
- Snykpass
Risk: LOW · No issues
- Runlayerfail
3/3 files flagged
What does this agent skill do?
Function Call Tracing
Purpose
Trace all function calls in C/C++ programs with per-thread logs and Perfetto visualization.
Containment
The traced project is untrusted — its build scripts and the produced binary execute arbitrary code. Every command that runs the target's build system or the instrumented binary goes through libexec/raptor-run-sandboxed --output-dir <dir> <cmd> [args...] (--output-dir = the directory the command writes into: the project tree for builds, the working directory for runs). The sandbox strips loader variables (LD_LIBRARY_PATH, LD_PRELOAD) by design; the instrumented link bakes an rpath instead, so the sandboxed run resolves libtrace.so with no loader variable. If a sandboxed step fails, fix the sandboxed path — never run the target bare. Building the instrumentation library itself (RAPTOR's own skill sources) needs no sandbox.
Components
1. Instrumentation Library (trace_instrument.c)
Captures function entry/exit, writes per-thread logs.
Build:
gcc -c -fPIC trace_instrument.c -o trace_instrument.o
gcc -shared trace_instrument.o -o libtrace.so -ldl -lpthread
2. Perfetto Converter (trace_to_perfetto.cpp)
Converts logs to Chrome JSON for Perfetto UI.
Build:
g++ -O3 -std=c++17 trace_to_perfetto.cpp -o trace_to_perfetto
Usage
Step 1: Add to Build
LIBTRACE_DIR is the absolute directory holding libtrace.so; the -Wl,-rpath makes the binary find it at run time inside the sandbox (which strips LD_LIBRARY_PATH).
CFLAGS += -finstrument-functions -g
LDFLAGS += -L$(LIBTRACE_DIR) -Wl,-rpath,$(LIBTRACE_DIR) -ltrace -ldl -lpthread
Step 2: Build Target (sandboxed — the build scripts are untrusted)
libexec/raptor-run-sandboxed --output-dir <project-dir> make ENABLE_TRACE=1
Step 3: Run (sandboxed; the rpath resolves libtrace.so — no loader variable)
libexec/raptor-run-sandboxed --output-dir <working-dir> <project-dir>/program
# Creates trace_<tid>.log files
Step 4: Convert to Perfetto (sandboxed — the log bytes came from the untrusted target, and the converter is native code)
libexec/raptor-run-sandboxed --output-dir <working-dir> ./trace_to_perfetto trace_*.log -o trace.json
# Open trace.json in ui.perfetto.dev
Log Format
[seq] [timestamp] [dots] [ENTRY|EXIT!] function_name
[0] [1.000000000] [ENTRY] main
[1] [1.000050000] . [ENTRY] helper
[2] [1.000100000] . [EXIT!] helper
[3] [1.000150000] [EXIT!] main
- Dots indicate call depth
- Timestamp in seconds.nanoseconds
- One log file per thread
When User Requests Tracing
Steps
- Copy
trace_instrument.candtrace_to_perfetto.cppto project - Build instrumentation library
- Add
-finstrument-functionsto CFLAGS - Add
-L$(LIBTRACE_DIR) -Wl,-rpath,$(LIBTRACE_DIR) -ltrace -ldl -lpthreadto LDFLAGS - Build project via
libexec/raptor-run-sandboxed --output-dir <project-dir> ... - Run the instrumented binary via
libexec/raptor-run-sandboxed --output-dir <working-dir> ...(the rpath resolveslibtrace.so) - Convert logs via
libexec/raptor-run-sandboxed --output-dir <working-dir> ./trace_to_perfetto trace_*.log -o trace.json(untrusted log bytes into a native parser) - Provide link to ui.perfetto.dev
Build System Detection
Makefile: Add flags conditionally
ENABLE_TRACE ?= 0
ifeq ($(ENABLE_TRACE),1)
CFLAGS += -finstrument-functions -g
LDFLAGS += -L$(LIBTRACE_DIR) -Wl,-rpath,$(LIBTRACE_DIR) -ltrace -ldl -lpthread
endif
CMake: Add option
option(ENABLE_TRACE "Enable tracing" OFF)
if(ENABLE_TRACE)
add_compile_options(-finstrument-functions -g)
link_directories(${LIBTRACE_DIR})
add_link_options(-Wl,-rpath,${LIBTRACE_DIR})
link_libraries(trace dl pthread)
endif()
Output
- trace_<tid>.log: Per-thread text logs
- trace.json: Perfetto Chrome JSON format
- View at https://ui.perfetto.dev
Perfetto JSON Format
Function ENTRY → "B" (begin) event Function EXIT! → "E" (end) event All threads aligned by timestamp in single file.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/gadievron/raptor/function-call-tracing">View Function Call Tracing on skillZs</a>