Synopsis

metalperftrace collect [--last duration | --start date --end date] [--prefix prefix] [--json] output_dir

Options

--last duration

Collect trace data from the last duration. The suffix determines the unit: ‘s’ (seconds, default), ‘m’ (minutes), ‘h’ (hours), ‘d’ (days). A bare number without a suffix is treated as seconds. Examples: 30s, 5m, 2h, 1d. Mutually exclusive with --start.

--start date

Start of the collection window (absolute date). Accepted formats: yyyy-MM-dd, yyyy-MM-ddTHH:mm:ss, yyyy-MM-ddTHH:mm:ssZ, @unix_timestamp. Dates in the future are not allowed.

--end date

End of the collection window. Same format as --start. Defaults to the current time when omitted.

--prefix prefix

File name prefix for the collected trace files. Defaults to MetalPerfTrace.

--json

Output collected file paths as a JSON dictionary with a traces key. Enabled by default when stdout is not a terminal.

Synopsis

metalperftrace overview [--json] [--json-include-timeline] [--include-state-transitions] [--predicate expr] [--aggregate] [--start offset] [--end offset] [--domain domain] [--state-label label] trace_file

Description

Print per-process, per-layer performance metrics from a collected trace. By default, prints an aggregation over the entire trace duration with full detail for all metric sections.

Options

--json

Emit output as a JSON object instead of human-readable text. Contains aggregated summary statistics for each layer session.

--json-include-timeline

Include the full per-frame timeline data in JSON output. Implies --json.

--include-state-transitions

Show detailed StateReporter state transition history, including labels, time ranges, and stable state values for each domain.

--predicate expr

An NSPredicate expression used to filter the layers shown. The expression is evaluated against a dictionary with keys: processName (string), pid (integer), layerName (string).

--aggregate

Enable aggregation mode. Groups metrics by state transitions. Without additional options, aggregates over all {domain, label, stableState} keys across all domains.

--start offset

Start offset from trace start (used with --aggregate). Duration format, e.g. 5s, 2m, 1h.

--end offset

End offset from trace start (used with --aggregate). Defaults to trace end when omitted.

--domain domain

Restrict aggregation to a single state domain (used with --aggregate).

--state-label label

With --domain, group by {domain, label} only, ignoring stableState differences. Requires --domain.

Synopsis

metalperftrace listen [--json] [--interval sec] [--output file] [--process name] [--pid pid] [--predicate expr]

Description

Stream live Metal performance statistics as data arrives from the system. Always prints full detail for all metric sections.

Options

--json

Emit each update as a compact JSON object on a single line (NDJSON). When the session ends (via SIGINT, SIGTERM, or SIGHUP), the output file, if any, is rewritten as a single pretty-printed JSON array.

--interval sec, -i sec

Update interval in seconds. Minimum: 1.0. Default: 1.0.

--output file, -o file

Tee all output to file in addition to the terminal. The file must not already exist.

--process name, -p name

Restrict output to the named process. May be repeated.

--pid pid

Restrict output to the given process ID. May be repeated.

--predicate expr

Same as for the overview subcommand.

Synopsis

metalperftrace setup --enable feature | --disable feature [--pid pid]

Description

Enable or disable a Metal performance trace feature in one or more running Metal processes. At least one --pid option is required. Exactly one of --enable or --disable must be specified.

Features

per-frame-metrics

Per-frame signpost collection (per-drawable signposting). Equivalent to setting METAL_PERFORMANCE_PER_FRAME_SIGNPOSTS=1 at launch.

shader-compiler-metrics

Shader compiler statistics signpost collection. Equivalent to setting METAL_PERFORMANCE_SHADER_COMPILER_STATS_SIGNPOSTS=1 at launch.

hud

Metal performance HUD overlay.

Options

--enable feature

Enable the named feature.

--disable feature

Disable the named feature.

--pid pid

Target the process with the given PID. May be repeated.