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 event records in the agent's byte order. 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.

Agent portability

The agent runs where your code runs; the analysis host is usually an x86-64 workstation. Those two can disagree about word size and byte order, so the format is self-describing rather than fixed: the agent writes its native byte order and analyze detects and swaps. The device is the constrained side of the system and the host is not, so the host does the work.

Detection needs no extra field. Every header opens with a byte-string magic, which reads the same either way, followed by a small u32 version — so a version that does not fit in 16 bits is a byte-swapped one and nothing else. TRACE_HF_BIGENDIAN records it explicitly as well, which costs nothing and makes a hexdump legible. callsight serve relays event bytes untouched and writes its file headers in the device's order, so a streamed segment is never half one thing and half the other.

Big-endian ARM has no cross toolchain in Debian, so it is not a CI leg. Both axes are covered independently — 32-bit ARM by the ARMv7 build, big-endian by PowerPC and s390x — and the runtime contains no architecture-specific endian assumption.

The cycle-counter clock is used on x86-64 and aarch64 only. 32-bit ARM has the same generic timer, but reaching it needs CP15 instructions that raise SIGILL where the timer is absent — and a runtime check cannot avoid that, because the check is the instruction. Those agents use clock_gettime, which is in the vDSO on ARMv7 anyway.

Two build details matter on 32-bit agents, and both build fragments handle them for you.

The runtime is compiled with _FILE_OFFSET_BITS=64, without which ftruncate fails past 2 GB and statvfs can return EOVERFLOW. And the byte budget uses a 64-bit atomic: ARMv7 and up inline it, while ARMv5/v6, MIPS32 and PowerPC32 need -latomic, which the Make and CMake integrations probe for rather than guess.

Every on-disk and on-wire struct carries a compile-time size assertion, so an ABI whose padding rules differ from ours fails the build instead of quietly producing files the analyzer misreads.

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