Reference

CLI

init

callsight init <dir> [--build make|cmake] [--stream]

An existing trace.config is never overwritten.

run

callsight run [options] -- <command> [args...]

Sets the environment, runs the command, then analyzes what it recorded. The four-step loop is identical every time and easy to get subtly wrong — most often by reporting on a traces/ directory that still holds the previous run.

callsight run --timeout 10 --top 20 -- ./bin/app.instr --workload heavy
callsight run --mode summary --out report.json --format json -- ./bin/app.instr

--timeout sends SIGTERM first so a clean exit can flush each thread's buffered tail; only a program that ignores it gets killed.

scan

callsight scan <dir> [--config trace.config]

Prints how many sources would be instrumented versus excluded, lists the excluded ones, and — for an include-func config — the subtree size and any substring-collision warnings.

select

callsight select <dir> --function NAME [--depth N] [--threads GLOB] [--list]

flags

callsight flags --config CONFIG [--scan DIR] [--format make|raw]
                [--compiler auto|gcc|clang] [--compiler-cmd CC] [--print] -- srcs...

A selective config under a detected Clang exits with an explanation rather than emitting GCC-only flags. A failed detection is treated as GCC, so detection can never break a build that would otherwise work.

analyze

callsight analyze [tracedir] [--exe BIN] [--top N]
                  [--format text|json|folded|chrome|callers]
                  [--addr2line CMD] [--subtract-overhead]

Summary traces (TRACE_MODE=summary) are detected automatically and merged. They hold per-function totals rather than call paths, so folded, chrome and callers are refused with an explanation instead of producing an empty result.

diff

callsight diff BASE.json NEW.json [--key self_ms] [--threshold N] [--fail-over PCT]

Compares two --format json reports function by function. Exact call counts make this a real comparison rather than two samples that happened to land differently, so it works as a build gate:

callsight diff base.json new.json --fail-over 10   # exit 1 on a >10% regression

doctor

callsight doctor [project] [--config trace.config] [--dir traces]

Checks the compiler and whether it is GCC, addr2line, that -finstrument-functions is accepted, that the config selects something, and that the trace directory is writable with room to spare. Exits non-zero if anything is actually broken; observations that are not problems are marked note.

serve · ui · provision

callsight serve [--host 0.0.0.0] [--port 9001] [--out traces]
                [--max-mb 4096] [--seg-mb 256]
callsight ui    [--host 127.0.0.1] [--port 8321]
callsight provision [--force]

serve bounds and rotates its output per connection: a device streaming for an hour should not fill the analysis host either.

provision reports where ctags comes from and installs the bundled static copy into $CALLSIGHT_HOME/bin (default ~/.callsight/bin), verifying its checksum. --force installs it even when a system ctags is present.

Build integrations

Both do the same two things: generate the flags from your config and source list, and compile the runtime without instrumentation so hooks cannot recurse. Neither forces -no-pie any more — link the way you ship.

GNU Make

CALLSIGHT_DIR ?= callsight
include $(CALLSIGHT_DIR)/Makefile.callsight

Expects SRCS, BUILDDIR, BINDIR, TARGET, CC, CFLAGS_SYMBOLS and LDFLAGS. Defines:

• CFLAGS_INSTRUMENT — your CFLAGS_SYMBOLS plus hooks plus the exclude lists
• TRACE_OBJ — the runtime object, built without instrumentation

When make instrument is requested and no flags could be generated, the build stops with an explanation instead of silently producing an uninstrumented binary. A normal make still succeeds even if callsight isn't installed.

CMake

list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/callsight")
include(CallSight)
callsight_instrument(<target>)

Environment variables

File formats

Trace files

trace.<pid>.<tid>.<seq>.bin (file mode) or trace.stream.<id>.<seq>.bin (streamed). An 80-byte version 2 header followed by fixed 32-byte little-endian event records. The architecture page documents the record; a file with a bad magic, unknown version or mismatched event size is skipped with a warning, and a truncated final record is tolerated.

Version 1 files still analyze. They carry a bare 16-byte header, nanosecond timestamps, no load bias and no markers.

Summary files

trace.summary.<pid>.<tid>.bin: an MLSUMRY header followed by one 688-byte record per function — address, calls, inclusive and self time, min, max, and a 160-bucket duration histogram (four sub-buckets per octave). Merged across threads by analyze.

Folded stacks

main;handle_request;parse_headers 148230
main;handle_request 92117

One line per distinct call path: semicolon-separated frames, then self time in nanoseconds. Read directly by flamegraph.pl and speedscope.

JSON report

Summary counters (events, threads, functions, span_ms, unmatched_exits, unclosed_enters), a rows array sorted by self time, a per_thread array, plus tool and version. See the analysis page for a full example.

Known limitations

• Selective instrumentation is GCC-only. Clang has -finstrument-functions but not the exclude lists (LLVM #15627); under Clang only an unfiltered config builds.
• Linux only. The runtime uses SYS_gettid, pthread_getname_np and POSIX shared memory.
• Inlined functions emit no hooks — there is no call boundary to hook.
• Overhead is roughly 12 ns per event with the cycle-counter clock and 16 ns with clock_gettime, measured by tests/bench/run_bench.py. An instrumented build with tracing off costs well under a nanosecond per hook. This is still a profiling build, not a production one.
• A crashed or killed process loses each thread's buffered tail. Clean exits flush everything; callsight run --timeout sends SIGTERM first for that reason.
• Capture is bounded by default at 512 MB (capture limits). Reaching a bound is reported in the trace, not left for you to infer.
• Summary mode has no call paths. It records per-function totals, so flame graphs, the timeline export and hot call sites need event mode.
• The compiler's exclude matching is substring-based, so unusually overlapping directory or symbol names can over-match. callsight guards the auto-generated function excludes against this and warns, but hand-written exclude-func entries are yours to keep specific.
• Position-independent executables are supported. The runtime records the load bias in every trace header, so -no-pie is no longer required — which matters, because forcing it would have you profiling a binary built differently from the one you ship. Version 1 traces predate this and still need it.
• Static call-graph resolution does not follow function pointers, macro-generated calls, or C++ dynamic dispatch.

Project links