Xcode 27 documents --show-recording-options to output a template’s recording options as JSON and --recording-options to pass a configuration file to xctrace record (Apple’s Xcode 27 release notes). Use those interfaces to collect Instruments traces on a remote Mac CI node, but treat collection as evidence gathering—not as a performance gate.
Symptom → fastest fix: You need a repeatable performance trace in CI; first lock down the workload, then query the selected template’s options in the same Xcode environment that will run the capture.
This guide is for iOS and macOS developers automating Instruments collection, CI engineers who need trace artifacts linked to a build, and platform maintainers deciding which performance tasks belong in a routine pipeline.
Last updated October 30, 2026; checked against Apple’s Xcode 27 release notes, command-line tool reference, and Instruments documentation.
Establish a baseline before adding a recorder
Start with a specific question the trace should help answer. For example, you might need to inspect CPU activity during a defined application flow, or compare the same operation across two revisions. Choose an operation that can be repeated with controlled input. Record the app state, test data, launch method, and any setup the operation depends on.
Keep three jobs distinct:
- Build: Produce the app from a known code revision and record the build result.
- Run the workload: Launch the intended app or test and execute the same operation with the same input.
- Capture the trace: Record the target using the chosen Instruments template and its supported options.
Choose the template only after you know what you need to inspect. A CPU-focused question and a question about another resource may need different Instruments templates. Avoid choosing a template simply because it is familiar: the recording configuration is template-specific, and the collected data is useful only if it relates to the question you set out to investigate.
For remote Mac performance analysis, baseline quality matters more than simply increasing the number of captures. If you cannot explain how the workload was held constant, label the trace exploratory and do not use it to assert a regression.**Runbook note:** Do not compare traces from different inputs or materially different run conditions as if they were equivalent. First make the workload reproducible; only then decide what a difference in the trace means.
Verify the remote Mac toolchain and target
Before querying recording options, establish which Xcode installation the remote job will use. A machine can have Xcode and command-line tools installed while the active developer directory points somewhere else. Apple documents how to install the command-line tools and configure the active command-line tools setting. Use those references to check the environment rather than assuming that an interactive shell and a CI process select the same toolchain.
In the job environment, record the output of commands such as:
xcode-select -p
xcodebuild -version
xcrun --find xctraceThe first command identifies the active developer directory; the second records the Xcode version reported by the selected toolchain; the third helps confirm which xctrace the job resolves. Apple’s Xcode command-line tool reference describes xctrace as a tool for recording, importing, exporting, and symbolizing Instruments traces.
If you are still deciding how to access and manage the host before wiring up a runner, review MACGPU’s remote Mac service overview alongside your CI requirements. Confirm that the access method and session model fit the workload, especially if the capture depends on a graphical session or a connected device.
How do you confirm the active developer directory when command-line tools are unavailable?
If the CI shell cannot resolve the expected Xcode commands, stop before capturing. Inspect the active developer directory with the tools available in that environment, then check the command-line tools selection in the system settings or correct it using your host-management procedure. Apple’s installation and settings documentation describes the supported setup paths. Once the intended Xcode is selected, re-run the checks inside the actual CI job; a check from a separate login session does not verify the job’s environment.
Next, validate the workload prerequisites. Confirm that the project builds with the intended Xcode, that the target application or device can be reached through the method your test uses, and that the job can launch and stop the workload. A trace command cannot compensate for a missing target, an inaccessible device, or a test that exits before the operation begins.
A remote Mac may also introduce operational boundaries that a local shell hides: session state, permissions, device availability, and access to project inputs can differ between jobs. Record those as run conditions. If a job depends on a graphical session, credentials, or a connected device, include a preflight check for that dependency instead of treating a capture failure as an Instruments problem.
Discover the template’s recording options
How do you query Instruments recording options in Xcode 27?
Query the exact template you intend to use from the same selected Xcode installation that will run the capture. The Xcode 27 release notes document xctrace record --show-recording-options for outputting recording options as JSON. They also document --recording-options for supplying a configuration file to a recording command. These are the relevant interfaces; the options themselves are not a universal schema shared by every template.
Use the command form documented by the Xcode version installed on the runner. For example, structure the discovery step around the selected template:
xcrun xctrace record --template "<template>" --show-recording-optionsCheck the command’s help and the Xcode 27 release notes if the installed version’s syntax differs. Save the returned JSON as a discovery artifact while you review it. Do not assume that a field seen in one template, Xcode build, or recording target is valid for another.
Prepare a configuration file from the options returned by the tool, not from a guessed example copied into the pipeline. Keep the file with the job definition or generate it from version-controlled inputs. If the configuration is generated dynamically, preserve the generated file or its contents with the run metadata so a later review can reconstruct what the recorder received.
The phrase xctrace recording options is useful in a search, but treat the actual output from your selected template as the authority for your run. Apple’s Xcode 27 release notes confirm the JSON discovery and configuration-file interfaces; they do not establish that every template, target, or CI arrangement accepts the same settings.
Run one controlled capture on the remote Mac
Once the baseline, toolchain, template, and configuration are established, connect them in a single job. Keep the target application and workload explicit. Use placeholders in shared examples and substitute values from your own pipeline:
# Replace placeholders with values validated for this runner and template.
xcrun xctrace record \
--template "<template>" \
--recording-options "<recording-options.json>" \
<validated-target-and-workload-arguments>This illustrates where the configuration file belongs; it does not define a universal set of target arguments. Consult the installed tool’s help and Apple’s command-line reference for the supported arguments in your environment. Avoid silently adding flags copied from another template or Xcode version.
Make the job capture more than the recorder’s exit status. Track whether the workload started, whether it completed, whether the recorder returned success, and whether the expected output was created. Preserve the complete command, relevant logs, and the output location. If the workload fails, mark the run as incomplete and retain enough diagnostic output to distinguish an application failure from a recording failure.
The capture step should run under the same conditions as the workload you intend to study. If the test depends on preloaded data, a particular app state, or a device, create or verify that state before recording starts. Stop the workload through the mechanism your test actually uses, and ensure the job reports failures rather than continuing with an apparently successful but empty or partial artifact.
**Failure handling:** A file at the expected path is not sufficient proof of a usable trace. Validate that the capture completed and that the artifact can be opened or exported before marking the job’s collection step as accepted.
Archive the trace and review what it contains
Treat the trace as a build artifact with provenance. Store it with metadata that identifies the code revision, Xcode version, target, template, workload, and recording configuration. Make the artifact accessible to the people who will inspect it, and define how long your CI system retains it according to your project’s evidence and storage policies. Do not claim a performance improvement merely because a trace was generated or archived.
Apple’s command-line tool reference covers importing, exporting, and symbolizing Instruments traces. Use those capabilities where they fit your review process. Then verify the artifact itself: open it in Instruments or use an appropriate export workflow, confirm that the expected target and interval are represented, and check that the relevant data can be inspected. The Apple guide to call tree views and run comparison explains how Instruments views can help analyze CPU profiles and compare runs; it does not establish a project-specific threshold for passing CI.
For a useful comparison, keep the test input and execution conditions under control and compare like with like. If the trace is not readable, has no relevant interval, or cannot be tied to a known workload, preserve it as a diagnostic artifact rather than treating it as a valid performance sample.
| Pipeline stage | Evidence to retain | Acceptance question |
|---|---|---|
| Build | Revision, Xcode version, build result | Did the intended toolchain build the intended target? |
| Workload | Target, input, launch method, completion status | Did the defined operation actually run? |
| Capture | Template, queried options, recorder result | Did the recorder complete with the intended configuration? |
| Review | Trace artifact and analysis outcome | Can a reviewer open it and inspect the data relevant to the question? |
Decide whether collection belongs in routine CI
An automated capture is an observation, not a performance gate. A gate needs a defensible comparison method, a project-owned baseline, and a decision rule that accounts for the conditions under which each run occurred. Set those from your own repeated measurements; do not copy a threshold from an unrelated project or infer one from a single trace.
Use these decision branches:
- If the workload is repeatable, the target is available, the trace can be opened, and the metadata is retained, then consider running collection on the schedule that serves your analysis needs.
- If collection works but run-to-run conditions or result interpretation are not yet controlled, then keep it as an on-demand or diagnostic job and refine the baseline before making it a gate.
- If the target or session is unreliable, the artifact cannot be reviewed, or a failed workload can be mistaken for a successful capture, then do not rely on routine CI collection until those failure paths are fixed.
- If your team has a repeatable comparison process and a separately justified decision rule, then evaluate a gate using that process; trace generation alone is not the gate.
| Readiness area | Ready | Needs work | Blocked |
|---|---|---|---|
| Workload | Same inputs and operation are reproducible | Setup is documented but variable | The operation cannot be identified reliably |
| Toolchain | CI records the selected Xcode and xctrace | Tool selection is inferred from the host | The job cannot resolve the intended tools |
| Capture | Template options are queried and the run completes | Configuration is prepared but unverified | The target or recorder cannot complete |
| Artifact review | Trace opens and the relevant data is inspectable | Artifact exists but review is pending | Trace is missing or unusable |
| Gate decision | Team has a repeatable comparison and owned rule | Baseline or interpretation is still under review | A pass/fail decision would be based on one unverified capture |
Apple’s Instruments automation session provides context for automating trace workflows. Treat any demonstration as guidance for understanding the tool, then verify command behavior against the Xcode version and template used by your runner. As of October 30, 2026, the Xcode 27 release notes confirm the recording-options interfaces described here; recheck the release notes and applicable Instruments documentation if a later Xcode 27.x release changes supported arguments or behavior.
If your current setup relies on a non-Mac host, it cannot provide the macOS toolchain needed for this capture. If you buy and maintain a Mac for occasional or changing CI demand, you also take on hardware ownership, host upkeep, and capacity planning. For a temporary or testable remote-Mac workload, compare those costs and operational duties with a rental before committing: review MACGPU’s remote Mac options. If the workload is continuous and predictable or requires physical interfaces you cannot access remotely, owning a dedicated Mac may fit better. When you need a remote Mac for a limited trial, validate the workload and trace delivery first, then choose the arrangement that matches how often your team will use it.