warp merge

Merge multiple benchmark data files into a single combined dataset for aggregate analysis.

Synopsis

warp merge [FLAGS] FILE1 FILE2 [FILE3 ...]

warp merge run1.csv.zst run2.csv.zst run3.csv.zst --benchdata combined

Parameters

FILES

The paths to two or more benchmark data files to merge. Warp saves benchmark data in CSV format with optional zstd compression. All input files must use compatible formats and operation types.

At least two files are required. You can merge any number of files in a single merge operation.

Flags

Output control

--benchdata

Default: auto-generated filename

Specify the output filename for the merged benchmark data. The default behavior generates a unique filename with timestamp. Use this flag to control the output filename and location.

Warp adds the extension to the name you give: .csv.zst when the input files are CSV, or .json.zst when they are JSON.

Example:

warp merge run1.csv.zst run2.csv.zst --benchdata combined

Display control

--no-color

Default: false

Disable color output in the terminal. The default behavior displays colored output for better readability. Use this flag when redirecting output to files or when terminal colors cause display issues.

Example:

warp merge run1.csv.zst run2.csv.zst --no-color

--debug

Default: false

Enable detailed debug output for troubleshooting. The default behavior shows only standard merge progress messages. Use this flag to see internal processing and diagnostic information.

Example:

warp merge run1.csv.zst run2.csv.zst --debug

TLS options

--insecure

Default: false

Disable TLS certificate verification for remote operations. The default behavior validates TLS certificates for secure connections. Use this flag only when necessary for testing environments.

Example:

warp merge run1.csv.zst run2.csv.zst --insecure

Shell integration

--autocompletion

Default: false

Install shell autocompletion for Warp commands. The default behavior does not modify shell configuration. Use this flag once to enable tab completion in your shell environment.

Example:

warp merge --autocompletion

Merge behavior

The merge command combines benchmark operations from multiple files into a single dataset. This process preserves all operation details including timestamps, latencies, and host information.

The merge process loads all input files sequentially. Each operation from each file is added to the combined dataset. Thread identifiers are adjusted to ensure unique thread numbering across all merged operations. This prevents thread ID conflicts when merging results from different benchmark runs.

The merged operations are sorted by start time to maintain chronological order. This ordering ensures that analysis tools process operations in the sequence they actually occurred.

The output file contains all operations from all input files. Host information is preserved for distributed benchmarks. Error information and timing data remain intact for each operation.

Merge validation

After merging, the command validates that each operation type has overlapping time ranges. This validation ensures the merged data represents coherent benchmark runs. Operations that do not overlap in time may indicate configuration issues or interrupted benchmarks.

The command displays validation results for each operation type. Warning messages appear if operation types have no overlapping time ranges.

Use cases

Merge results from distributed clients when client machines save local benchmark data. This consolidates distributed benchmark results into a single file for analysis. The result is the same as one benchmark run at a higher concurrency.

Only data that overlaps in absolute time counts in the analysis. Merging runs from different times, such as daily runs or repeated iterations, does not produce a combined analysis. To compare runs from different times, use warp cmp.

Merged output

The merged file contains the combined operation records from all input files.

The output preserves all operation metadata including operation type, object size, and timing information. Host identifiers remain intact showing which machine or client generated each operation. Error information is maintained for any failed operations in the original files.

The merged file uses the same format as the input files: compressed CSV (.csv.zst) or compressed JSON (.json.zst). This format is compatible with all Warp analysis commands. You can analyze merged files using warp analyze or compare them using warp cmp.

Examples

Merge multiple runs

Combine three benchmark runs that ran at the same time into a single dataset:

warp merge run1.csv.zst run2.csv.zst run3.csv.zst --benchdata aggregated

The merged file contains all operations from all three runs.

Merge distributed results

Combine results from multiple client machines:

warp merge client1-results.csv.zst client2-results.csv.zst client3-results.csv.zst \
  --benchdata distributed-combined

This consolidates distributed benchmark data into a single file for analysis.

Merge with pattern matching

Combine all benchmark files in a directory that come from clients of the same run:

warp merge benchmark-*.csv.zst --benchdata all-benchmarks

The shell expands the pattern to match all files with the specified prefix.

Auto-generated filename

Merge files without specifying output filename:

warp merge run1.csv.zst run2.csv.zst

Warp generates a unique filename with timestamp automatically.

Merge and analyze

Merge multiple files then immediately analyze the combined results:

warp merge run1.csv.zst run2.csv.zst run3.csv.zst --benchdata merged
warp analyze merged.csv.zst

This workflow combines data from runs that took place at the same time and generates aggregate statistics.

Merge and compare

Merge the client files from a distributed baseline run and compare them against a test run:

warp merge baseline-client1.csv.zst baseline-client2.csv.zst baseline-client3.csv.zst \
  --benchdata baseline-combined
warp cmp baseline-combined.csv.zst test-run.csv.zst

This approach compares a test run against the combined results of a distributed baseline run.