How magic-trace Captures Kernel Traces with kcore Support

magic-trace automatically appends the --kcore flag to perf record when Intel Processor-Trace is enabled, the trace scope includes the kernel, and the system runs kernel version 5.5 or later with a compatible perf binary.

magic-trace is Jane Street's open-source execution tracing tool that leverages the Linux perf subsystem to capture high-resolution performance data. When you capture kernel traces with kcore support, the tool inspects your kernel capabilities and automatically injects the --kcore argument into the underlying perf command, embedding kernel-core symbol mappings that make decoding self-modifying kernel code more reliable.

Automatic kcore Detection Flow

magic-trace determines whether to enable kcore support through a three-stage pipeline involving system capability detection, user-configurable overrides, and dynamic command construction.

Kernel Capability Detection in src/perf_capabilities.ml

The detection process begins in src/perf_capabilities.ml, where the function Perf_capabilities.detect_exn inspects the running kernel version and the installed perf binary to compute a bit-mask of supported features. The kcore bit is defined in this module and is set only when the kernel version is ≥ 5.5, the version that introduced reliable kcore support for symbol lookup.

If the kernel or perf tool lacks this capability, the bit remains unset, and magic-trace later emits a warning recommending an upgrade to perf ≥ 5.5.

User Override via src/env_vars.ml

Even when the system supports kcore, you can force magic-trace to omit the feature by setting the environment variable MAGIC_TRACE_PERF_NO_KCORE. This variable is read in src/env_vars.ml and overrides automatic detection, allowing users to generate traces compatible with older analysis tools or reproducible build environments.

To explicitly disable kcore support:

export MAGIC_TRACE_PERF_NO_KCORE=1
magic-trace record -collection-mode intel-pt -trace-scope kernel

Command Construction in src/perf_tool_backend.ml

The final decision logic resides in src/perf_tool_backend.ml within the kcore_opts helper (lines 447–459). This function evaluates three criteria before appending ["--kcore"] to the argument list:

• The collection mode is Intel Processor-Trace.
• The trace scope includes the kernel (either kernel or a mixed userspace‑kernel scope).
• The kcore capability bit is present in the detected feature mask.

When all conditions are met, the flag is injected into the perf record command. If the capability is missing, the function omits the flag and prints a warning about the old perf version.

Requirements for kcore Support

To successfully capture kernel traces with kcore support, your environment must satisfy the following requirements as enforced by the source code:

• Kernel version ≥ 5.5 – Validated by Perf_capabilities.supports_kcore in src/perf_capabilities.ml.
• perf binary ≥ 5.5 – The perf userspace tools must report the kcore capability to Perf_capabilities.detect_exn.
• Collection mode – Must specify Intel Processor-Trace (-collection-mode intel-pt).
• Trace scope – Must include kernel events (-trace-scope kernel or an equivalent mixed scope).
• No user override – The MAGIC_TRACE_PERF_NO_KCORE environment variable must be unset.

If any requirement is missing, magic-trace falls back to standard kernel tracing without kcore embeddings.

Practical Examples

Recording with Automatic kcore Detection

To capture a kernel trace with automatic kcore support, ensure your environment variables do not block the feature and invoke the record command:

# Ensure kcore is not disabled

unset MAGIC_TRACE_PERF_NO_KCORE

magic-trace record \
    -collection-mode intel-pt \
    -trace-scope kernel \
    -output kernel_trace

This command triggers the code path in src/perf_tool_backend.ml that adds --kcore to the underlying perf record invocation, causing perf to write kernel-core mappings into kernel_trace.

Disabling kcore for Compatibility

When working with older perf versions or requiring deterministic builds without kcore dependencies, force the feature off:

export MAGIC_TRACE_PERF_NO_KCORE=1
magic-trace record \
    -collection-mode intel-pt \
    -trace-scope kernel \
    -output kernel_trace_no_kcore

Without kcore support available, magic-trace prints the following warning:

Warning: old perf version detected! perf userspace tools v5.5 contain an important feature, kcore, that make decoding kernel traces more reliable...

Summary

• Automatic detection: Perf_capabilities.detect_exn in src/perf_capabilities.ml validates kernel ≥ 5.5 and compatible perf binaries before setting the kcore capability bit.
• User control: The MAGIC_TRACE_PERF_NO_KCORE environment variable (read in src/env_vars.ml) allows you to disable kcore even when the system supports it.
• Conditional injection: The kcore_opts function in src/perf_tool_backend.ml (lines 447–459) appends --kcore only for Intel Processor-Trace with kernel scope when the capability is present.
• Improved reliability: The --kcore flag embeds kernel-core symbol mappings into the trace, enabling accurate decoding of self-modifying kernel code.

Frequently Asked Questions

What kernel version is required for kcore support in magic-trace?

magic-trace requires kernel version 5.5 or later to enable kcore support. The Perf_capabilities.detect_exn function in src/perf_capabilities.ml explicitly checks the kernel version and only sets the kcore capability bit for versions ≥ 5.5, as earlier kernels lack reliable kcore support for symbol resolution.

How can I disable kcore support when recording traces?

Set the environment variable MAGIC_TRACE_PERF_NO_KCORE=1 before running magic-trace record. This variable is processed in src/env_vars.ml and overrides the automatic capability detection, forcing the tool to omit the --kcore flag regardless of system support.

Why does magic-trace warn about old perf versions when recording kernel traces?

If your perf binary is older than version 5.5 or lacks kcore support, magic-trace prints a warning because the absence of the --kcore flag makes decoding kernel traces less reliable, particularly for self-modifying kernel code. Upgrading to perf ≥ 5.5 allows the kcore_opts logic in src/perf_tool_backend.ml to inject the flag and improve symbol resolution.

Does kcore work with userspace-only tracing?

No. The kcore_opts logic in src/perf_tool_backend.ml only adds --kcore when the trace scope includes the kernel. Pure userspace traces do not require kernel-core symbol mappings, so the flag is omitted for those collection modes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}