NAME

xctrace — Record, import, export, symbolicate and triage Instruments .trace files.

SYNOPSIS

DESCRIPTION

xctrace is used to record new Instruments.app .trace files using the specified recording template. It also allows for converting supported converting files of supported input types into .trace files and exporting data from .trace files to parseable formats like xml. It can also inspect an already-recorded trace from the command line: list its contents, print individual details such as call trees and summaries, and triage it for hangs.

Available commands and their options:

help

General help or help specific to command argument

record

Perform a new recording on the specified device and target with the given template. Resulting .trace file can be viewed in Instruments.app or exported using xctrace. Recording can target all processes, attach to an existing process or launch a new one.

--output path

Save the trace to the specified path. A path to an existing trace file can be used if --append-run is specified. In this case the provided template will be ignored and the template in the existing trace will be used. If the passed path is a directory, a uniquely named file will be created in it. If the path contains the extension .trace, a new trace will be created with that name at the specified path or working directory.

--append-run

Allows to target an existing trace file. Specifying it causes new run to be appended. New run is recorded with the template that this existing trace file was initially recorded with.

--run-name

Specifies run name for this recording, which can be later inspected in Instruments.app.

-t, --template path | name

Records using given trace template name or path. If name is specified, template needs to be either bundled with an installed Instruments Package or located in the Application Support directory for Instruments. To retrieve available templates, run xctrace list templates.

-i, --instrument name

Adds Instrument with the specified name to the recording configuration. To retrieve available Instruments, run xctrace list instruments.

--device name | UDID

Record on a device with the given name or UDID. If not specified, then local device is chosen for the recording. If the word simulator is included, devices of simulator types will be preferred. To get list of available devices, run xctrace list devices.

-l, --time-limit time [ms|s|m|h]

Limits the recording to the specified time period. Example: "--time-limit 5s" or "--time-limit 1m"

--window duration [ms|s|m]

Configure trace to operate in windowed mode, where trace buffer acts as a ring buffer, removing old events to make room for new ones. Example: "--window 5s"

--all-processes

Record all processes running on the system.

--attach pid | name

Attach and record running process with the given name or pid.

--launch -- command [arguments]

Launch and record process with the given name or path and provided arguments list. This option should be passed as the last one in the xctrace command invocation.

--package file

Install the given Instruments Package temporarily for the duration of a command

--target-stdin - | file

Redirects standard input stream of a launched process in case if target device is set to the local Mac. Can be pointing to a file or be specified as - , which causes standard input of xctrace to be passed into the standard input of a target process.

--target-stdout - | file

Redirects standard output stream of a launched process. Can be pointing to a file or be specified as - , which causes standard output of a target process to be to be redirected into the standard output of xctrace.

--env VAR=value

Sets environment variable for a launched process. Example: "--env PATH=/tmp"

--no-prompt

Skip any prompts that would be otherwise presented (like privacy warnings)

--notify-tracing-started name

Send Darwin notification with this name when a recording has started.

--recording-options file

Apply recording options for the selected instruments from the given JSON file. The file format matches the output of --show-recording-options and only keys for instruments that are part of the recording are honored.

--show-recording-options

Do not start a recording. Instead, print the configurable recording options for the selected template and instruments as JSON and exit. Instruments that have no configurable recording options are omitted from the output. A target option ( --all-processes, --attach, --launch ) is not required when this flag is used.

import

If the specified file is of a support input format, imports the file into an Instruments .trace file using the specified template. This file can later be viewed using Instruments.app or exported by using xctrace export command.

--input file

Import data from a supported file format at the given path.

--output path

Save the trace to the specified path. Existing trace files cannot be targeted. If the passed path is a directory, a uniquely named file will be created in it. A path to an existing trace file can be used if --append-run is specified. In this case the provided template will be ignored and the template in the existing trace will be used.

--append-run

Allows to target an existing trace file. Specifying it causes new run to be appended. New run is imported into the original template the trace was created with.

-t, --template path | name

Imported using given trace template name or path. Only data that is needed by Instruments contained in the template will be imported. If name is specified, template needs to be either bundled with an installed Instruments Package or located in the Application Support directory for Instruments. To retrieve available templates, run xctrace list templates.

--run-name name

Specifies run name for this import, which can be later inspected in Instruments.app.

-i, --instrument name

Adds Instrument with the specified name to the import configuration. To retrieve available Instruments, run xctrace list instruments.

--package file

Install the given Instruments Package temporarily for the duration of a command.

export

Exports a trace file into an XML format. Output contains metadata about the trace, raw data stored in tables and view-level aggregated data. Table of contents query describes the structure of available data for a given trace.

If the file passed to --input is not a .trace bundle but a supported import format (for example .atrc or .logarchive), it is imported in memory before the export runs. The same default-template selection used by xctrace import applies; the --template, --instrument, and --package options may be supplied to override it.

file

Path to the trace file to export data from. Passing the trace file as a positional argument is the preferred form. A supported import-format file (for example .atrc or .logarchive) may be supplied instead of a .trace bundle; it will be implicitly imported before export. The --input file option is accepted as a legacy equivalent.

--output path

Save output of the export operation to the given path. If not specified, then textual output is being written to the xctrace standard output.

--toc

Export the table of contents of a trace file. This will contain overview of content and exportable entities from the given trace file.

--xpath expression

Perform given XPath query on the table of contents to select entities to export from the given trace file. Selected entities will be present in the export command output. The expression has to select entities, that is, the elements listed by --toc; attributes and text values cannot be exported on their own, so use them as predicates to choose an entity instead, as in ‘/trace-toc/run[@number="1"]/data/table[@schema="time-profile"]’. The command fails if the expression matches no exportable entity.

--har

Export data as the HTTP Archive file if the trace run contains the HTTP Traffic Instrument. Cannot be combined with --xpath or --toc; run a separate export command for those.

-t, --template path | name

Template used for the implicit import of a non-.trace input. Ignored when the input is already a .trace bundle. If a name is specified, template needs to be either bundled with an installed Instruments Package or located in the Application Support directory for Instruments. To retrieve available templates, run xctrace list templates.

-i, --instrument name

Adds Instrument with the specified name to the implicit-import configuration. Ignored when the input is already a .trace bundle. To retrieve available Instruments, run xctrace list instruments.

--package file

Install the given Instruments Package temporarily for the duration of a command. Useful for making additional importers available to the implicit-import phase.

--time-start time[ns|us|ms|s]

Restrict exported data to begin at the specified trace-relative offset. The value is a trace-relative timestamp — the amount of time elapsed since the start of the trace run. A unit suffix is required: use ns for nanoseconds, us for microseconds, ms for milliseconds, or s for seconds. Example: "--time-start 500ms". If omitted and --time-end or --duration is specified, the start offset defaults to 0 (the beginning of the trace). If --time-end and --duration are both omitted, the export extends to the end of the trace.

--time-end time[ns|us|ms|s]

Restrict exported data to end at the specified trace-relative offset. Accepts the same unit suffixes as --time-start. Mutually exclusive with --duration. If --time-start is omitted, the start offset is implied to be 0. Example: "--time-end 1500ms".

--duration time[ns|us|ms|s]

Restrict exported data to a window of the specified length. The window begins at --time-start if provided, or at the beginning of the trace if --time-start is omitted. Accepts the same unit suffixes as --time-start. Mutually exclusive with --time-end. Example: "--duration 1s".

remodel

Remodel trace using currently installed packages and their modelers.

--input file

Remodel data from .trace file at the given path.

--output path

Save remodeled .trace file to the given path. .

--package file

Install the given Instruments Package temporarily for the duration of a command.

symbolicate

Symbolicate trace file using supplied debug symbols (dSYM).

--input file

Symbolicate addresses in .trace file at the given path.

--output path

Save symbolicated .trace file to the given path. If not specified, the symbolicated .trace will be saved to its original location (input path).

--dsym path

Use symbol data from dSYM at given path. Path can be a dSYM or a directory to search recursively for dSYMs. If not specified, the tool will make its best effort to locate dSYMs (it may take a while).

triage

Analyze an already-recorded trace and report the hangs it holds for a single process. Each hang is reported with what the process' main thread was doing while it was hung. The trace has to include Hangs and Time Profiler instruments.

file

Triage the .trace or .atrc file at the given path. An input that is not a .trace bundle is imported first. The --input file option is accepted as a legacy equivalent.

--process pid | name

Triage the process with the given pid or name. Does not need to be specified if there was a single process targeted in the trace.

--run number | label

Triage the run with the given number or label. Does not need to be specified if the trace only has one run.

--style hangs

Select performance focus for triage. Required.

--limit count | none

Report at most count hangs, longest first. Defaults to 10. Pass none to report every hang.

-f, --format text | markdown

Print the report in the given format. Defaults to text.

show

Show a detail (a call tree, summary, or list) from the trace. Use xctrace toc to find the track paths and detail names to pass.

Call trees and summaries are emitted with a node ID column. --focus, --source, and --resolve use this ID to select a node for an operation; pass them alongside the same track, detail, run, time range, and other filtering options.

file

Show data from the .trace or .atrc file at the given path. An input that is not a .trace bundle is imported first. The --input file option is accepted as a legacy equivalent.

--track path

The track to read, given as a '/'-separated path of displayed track titles, for example ‘Time Profiler’ or ‘Calculator/Main Thread’.

--calltree name

 

--summary name

 

--list name

Show the call tree, summary, or list detail with the given name. Exactly one must be specified.

--run number | label

Show data from the run with the given number or label. Does not need to be specified if the trace only has one run.

--time-start time[ns|us|ms|s]

 

--time-end time[ns|us|ms|s]

 

--duration time[ns|us|ms|s]

Restrict the shown data to a trace-relative time range. A unit suffix is required. --time-end and --duration cannot be specified together. If --time-start is omitted, the range starts at the beginning of the trace.

-f, --format text | markdown

Print the detail in the given format. Defaults to text. --summary and --source output is text only.

--sort column

Order rows by the column with the given title, largest first. With --source, ranks source lines instead, with unsampled lines last.

--ascending, --descending

Sort smallest or largest first. Requires --sort. Defaults to --descending.

--arrange-columns expression

Select and order columns by title, separated by '|'. ‘...’ stands in for the remaining default columns, so ‘Weight|...’ moves Weight to the front. Columns hidden by default may be named. Not supported with --summary or --source.

--filter column=value

Keep only rows whose column matches value. column is a column title or mnemonic. Repeatable.

--match-all, --match-any

Rows must match every --filter (the default), or any one of them.

--minimum-value column=value

 

--maximum-value column=value

Keep only rows whose column value is at least, or at most, value, given in the column's units (e.g. 10ms, 5MB, 40). Repeatable. Only valid with --summary or --list.

--hide-node-ids

Do not print the leading ID column.

--focus id

Follow the focus action of the summary row with the given ID and show the detail behind it. A summary's focus destinations are listed beneath its rows. Requires --summary.

--title label

Pick which focus destination to follow when the row has more than one. Requires --focus.

--hide-heaviest-stack

Do not print the heaviest stack trace above the call tree. Requires --calltree.

--include-source-info

Print the source file and line number of each call tree symbol. Requires --calltree.

--source node-id

Print the annotated source of the call tree node with the given ID, with per-line weights. Requires --calltree.

--source-mode source | disassembly | interleave

Annotate source lines, disassembled instructions, or source with its instructions interleaved. Defaults to source. Requires --source.

--full-source

Print the whole source file rather than only the selected symbol. Requires --source.

--function expression

Apply a call tree function before printing. expression is a function name with an optional ':'-separated argument, such as ‘invert-calltree’ or ‘prune:<descriptor-json>’. Repeatable. Requires --calltree.

--list-functions

List the call tree functions available on the call tree, and the arguments each accepts, then exit. Requires --calltree.

--resolve node-id

Print the symbol descriptor JSON for the call tree node with the given ID, for use as a --function argument. Repeatable. Requires --calltree.

toc

Print a trace's static tracks (e.g. one per instrument) as a tree, with the details available on each listed inline. Dynamic tracks (processes, threads, and similar per-instance tracks) are not listed individually. Instead, each distinct dynamic-track shape (e.g. “Process”, “Process/Thread”) is listed once in a separate “Details for dynamic tracks” section. Use xctrace list tracks to enumerate the tracks of one shape. A detail's focus destinations are listed beneath it; see xctrace show --focus.

file

Show the table of contents for the .trace or .atrc file at the given path. The --input file option is accepted as a legacy equivalent.

--run number | label

Show the run with the given number or label. Does not need to be specified if the trace only has one run.

-f, --format text | markdown

Print the table of contents in the given format. Defaults to text.

list devices

Lists all of non-host devices that can be used as a target for a new recording.

list templates

Lists all of templates that are known to xctrace. These include Instruments.app bundled templates, templates from installed Instruments Packages and custom templates installed into Application Support directory for Instruments.app.

-v, --verbose

Print each template's description, indented below its name.

list instruments

Lists all of the Instruments available to select as part of the record or import workflow.

-v, --verbose

Print each instrument's description, indented below its name.

list runs

Lists the number and label of each run contained in a .trace document.

file

List the runs in the .trace file at the given path. The --input file option is accepted as a legacy equivalent.

list tracks

Lists the tracks of one dynamic-track shape, as printed by xctrace toc. Each listed path can be passed to xctrace show --track.

file

List the tracks in the .trace or .atrc file at the given path. The --input file option is accepted as a legacy equivalent.

--type path

The '/'-separated dynamic-track shape to enumerate, for example ‘Process/Thread’. Required.

--run number | label

List the tracks of the run with the given number or label. Does not need to be specified if the trace only has one run.

-q, --quiet

Make terminal output less verbose

SEE ALSO

Instruments.app may be used to perform trace recordings in a graphical environment and may also be used to open trace documents created by xctrace.

EXAMPLES

Import a logarchive file to the trace file with a unique name using a MyCustomTemplate template:

Import a ktrace file into a new document created from the template with name MyCustomTemplate and adding the instrument from /tmp/PackageToLoad.instrdst and save the resulting document as output.trace:

Import a ktrace file with a custom run name:

Export a table of contents (toc) of the input.trace file to standard output:

Export recorded data from a table with my-table-schema schema in the first run of the input.trace file to standard output:

Export UUID, binary path, load address and architecture for each binary image contained in the first run of the input.trace and save as output.xml:

Export UUID, binary path, load address and architecture for each binary image used by the process named my-process-name in the first run of the input.trace file to standard output:

Export the table of contents directly from a. atrc file without first running xctrace import:

Start recording all processes on the local Mac device using the Time Profiler template and automatically stop the recording after 5s:

Start a new recording by attaching to the process with name Trailblazer on the connected device Chad's iPhone using the template Time Profiler:

Start Metal System Trace template recording on a simulator device named iPhone SE Simulator, capturing all existing processes:

Start Time Profiler template recording on a local Mac device, launching and profiling binary at /tmp/tool path with arg1 arg2 arguments, output of the binary gets redirected to the standard output:

Symbolicate the input.trace file using debug information from a SomeLibrary.dSYM file:

Symbolicate the input.trace file by trying automatically locate debug information:

Report the hangs of the process the recording.trace file was recorded against:

Report the hangs of the process named Calculator in an atrc file, without first running xctrace import:

Report the five longest hangs of the process with pid 79311 in the second run of the recording.trace file:

List the tracks and details in recording.trace:

List the thread tracks in recording.trace:

Print the Profile call tree of the Time Profiler track for one second starting at 2s:

Print the Run Loop Busy Intervals list of a process' main thread, longest first:

Follow the Updates focus destination of a summary row:

Print the annotated disassembly of a call tree node: