# How magic-trace Captures Kernel Traces with kcore Support

> Learn how magic-trace captures kernel traces with kcore support by automatically enabling the --kcore flag for perf record in specific Intel Processor-Trace configurations. Optimize your kernel tracing.

- Repository: [Jane Street/magic-trace](https://github.com/janestreet/magic-trace)
- Tags: how-to-guide
- Published: 2026-05-24

---

**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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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:

```bash
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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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:

```bash

# 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`](https://github.com/janestreet/magic-trace/blob/main/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:

```bash
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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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`](https://github.com/janestreet/magic-trace/blob/main/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.