How to Convert and Export Performance Profiles to CTF and JSON in Linux Using perf data convert

When profiling high-performance applications, kernel schedulers, or hardware PMU counters in Linux, the standard recording workflow produces a binary data file named perf.data. While internal command-line utilities such as perf report, perf annotate, and perf script provide powerful post-processing capabilities, modern software performance engineering frequently relies on external, specialized tracing tools and continuous observability platforms.

Tools such as Babeltrace, Chrome Tracing, Perfetto, Eclipse Trace Compass, and custom telemetry parsers cannot directly consume proprietary Linux kernel binary perf streams. To bridge this interoperability gap, the Linux kernel profiling subsystem provides a dedicated data export utility: perf data convert. This tool allows performance engineers to convert raw perf.data profiles into standardized Common Trace Format (CTF) streams or structured JSON files for automated processing, machine learning analysis, and rich cross-platform visualization.

Understanding Export Formats: CTF versus JSON

The perf data convert command supports two primary export targets:

• Common Trace Format (CTF): A standardized binary trace format designed by the open-source tracing community (specifically used by LTTng and Babeltrace). CTF provides ultra-compact storage, nanosecond-precise event timestamps, and rapid sequential parsing. It is the preferred target for large multi-gigabyte traces that must be merged with kernel function traces or analyzed in Eclipse Trace Compass.
• JSON (JavaScript Object Notation): Formats captured performance samples, call stacks, process IDs, and CPU counter events into human-readable, structured key-value arrays. JSON output is ideal for importing into custom Python/Node.js analysis scripts, web-based visualizers, or enterprise telemetry databases (such as Elasticsearch or ClickHouse).

Recording Profiles with Complete Sample Metadata

Before converting a performance profile, ensure that your recording session captures adequate sample metadata (including instruction pointers, process IDs, hardware timestamps, and call graphs):

# Record CPU cycles and call stacks with nanosecond timestamps
sudo perf record -F 99 -g -R -e cycles -- sleep 10

The -R flag instructs perf to record raw sample data, ensuring that all architectural details needed for conversion are preserved in the generated perf.data file.

Verify that the recording completed successfully and inspect basic header information:

# Verify file format and recorded events
perf data --help

Converting Binary Profiles to CTF Format

To convert a perf.data file into Common Trace Format, use the --to-ctf parameter followed by the target output directory:

# Convert perf.data into CTF format
sudo perf data convert --to-ctf=./ctf_trace/

The command reads the binary samples, synthesizes the CTF metadata file, and writes stream files inside the specified directory:

[ perf data convert: Converted 18452 events to CTF ]

You can inspect the generated trace directory using standard directory listing commands:

# Inspect the generated CTF directory
ls -lh ./ctf_trace/

The folder contains two critical components: a metadata schema definition file and one or more binary data streams (such as channel0_0) corresponding to CPU cores.

To inspect and read the converted CTF trace directly from the command line, use babeltrace or babeltrace2:

# Parse and print CTF trace events with Babeltrace
babeltrace ./ctf_trace/ | head -n 25

The output presents formatted, time-ordered event entries:

[07:12:00.124589201] (+?.?????????) hostname perf:cycles: { cpu_id = 2 }, { pid = 1845, tid = 1845, ip = 0x7fff81204a10 }

Converting Binary Profiles to Structured JSON

To export performance data for web visualization or programmatic processing in automated testing suites, convert the profile to JSON using --to-json:

# Export performance profile to JSON
sudo perf data convert --to-json=profile_trace.json

If processing a custom profile file rather than the default perf.data in the current directory, specify the input file using the -i argument:

# Convert a specific profile to JSON
sudo perf data convert -i /var/log/profiles/db_bench.perf.data --to-json=db_bench.json

Inspect the structure of the resulting JSON file using jq:

# Inspect top-level keys in the converted JSON output
jq 'keys' profile_trace.json

# Preview the first captured event sample
jq '.events[0]' profile_trace.json

The JSON structure contains complete event definitions, including timestamp, CPU core, process identifier (PID), thread identifier (TID), instruction pointer (IP), and resolved symbol names:

{
  "timestamp": 128451023910,
  "cpu": 3,
  "pid": 2045,
  "tid": 2045,
  "comm": "nginx",
  "ip": "0x55a1204b1230",
  "symbol": "ngx_http_process_request",
  "dso": "/usr/sbin/nginx"
}

Automating Trace Conversion in Continuous Profiling Pipelines

In distributed microservice environments, you can script automated collection, conversion, and telemetry ingestion without keeping large binary files on production nodes:

#!/usr/bin/env bash
set -euo pipefail

TRACE_NAME="trace_$(date +%s)"
RAW_FILE="/tmp/${TRACE_NAME}.perf.data"
JSON_FILE="/var/telemetry/${TRACE_NAME}.json"

# Capture 15-second profile
perf record -F 49 -a -g -R -o "${RAW_FILE}" -- sleep 15

# Convert to JSON for ingestion
perf data convert -i "${RAW_FILE}" --to-json="${JSON_FILE}"

# Remove raw binary to reclaim disk space
rm -f "${RAW_FILE}"

echo "Exported structured performance trace to ${JSON_FILE}"

Using perf data convert ensures that raw Linux hardware and software performance traces integrate seamlessly into enterprise observability dashboards and cross-platform forensic suites.