XCODE 27
как подключить параметры записи xctrace к удалённому Mac CI? Руководство 2026

Подключить запись xctrace к удалённому Mac CI можно: сначала проверьте доступные параметры выбранного шаблона в вашей версии Xcode 27, затем зафиксируйте рабочую нагрузку и сохраняйте полученный trace вместе с данными запуска. Сбор файла автоматизирует получение записи, но сам по себе не доказывает ни улучшение производительности, ни регрессию.

Эта инструкция для разработчиков iOS и macOS, которым нужно записывать Instruments trace для повторяемой операции приложения. Она также пригодится инженерам CI, которым нужно сохранять и отслеживать записи на удалённом Mac. Если вы отвечаете за платформу разработки, используйте руководство, чтобы определить, что автоматизировать, а что оставить на проверку специалисту.

Обновлено 30 октября 2026 года. Функциональность сверена с заметками Apple о выпуске Xcode 27, справочником по инструментам командной строки Xcode и материалами Apple по Instruments. Значения, доступные для конкретного шаблона, следует проверять непосредственно в установленной среде: их нельзя считать универсальными для всех проектов и запусков.

Подготовьте воспроизводимую нагрузку до подключения Instruments

Сначала определите не инструмент, а сценарий, который хотите наблюдать: например, запуск приложения и выполнение стабильной последовательности действий, тестовый кейс или обработка одинакового набора данных. Заранее запишите, какой вопрос должна прояснить запись: где расходуется процессорное время, на каком участке возникает ожидание или какое действие нужно сопоставить между запусками. Выбор шаблона Instruments должен следовать из этой задачи, а не заменять её.

Разделите процесс на самостоятельные этапы:

• Сборка — подготовка исполняемого приложения из нужного коммита и конфигурации.
• Выполнение нагрузки — запуск приложения и выполнение выбранной операции с определёнными входными данными.
• Запись trace — сбор данных Instruments во время выполнения нагрузки.

Такое разделение важно для интерпретации. Изменение параметров сборки, входных данных или способа запуска может изменить наблюдаемый результат; поэтому не относите изменение записи автоматически к регрессии приложения. Сохраните идентификатор коммита, конфигурацию сборки и отметку о том, какой именно сценарий выполнялся.

Если цель — сравнивать записи, определите заранее, что должно оставаться неизменным: код, набор данных, последовательность действий и целевая среда. Отдельно фиксируйте изменения, которые неизбежны, например обновление Xcode или изменение конфигурации запуска. Когда эти сведения теряются, trace остаётся файлом, но теряет часть ценности для последующего сравнения.

Практический ориентир по подготовке — составьте короткую карточку запуска, которую CI сможет прикрепить к артефакту. Включите в неё идентификатор коммита, версию и путь активного Xcode, название шаблона, описание нагрузки, сведения о цели записи и итоговый статус задачи. Это рекомендация по организации процесса, а не специальный формат Apple: карточка должна позволить другому инженеру восстановить условия записи, а не угадывать их по имени файла.

Не смешивайте назначение трёх этапов и при разборе отказов. Если приложение не собрано, проблема предшествует Instruments. Если приложение собрано, но не запускается, проверьте доступ к целевому процессу и порядок старта. Если нагрузка завершилась, а trace не появился, уже отдельно исследуйте команду записи, путь вывода и права. Такое деление делает журналы CI полезнее: вместо общей отметки «профилирование не удалось» команда видит, на каком звене оборвался сценарий.

Не меняйте одновременно нагрузку, шаблон и способ запуска, если задача — понять причину изменения записи. Иначе результат будет сложно приписать конкретному изменению.

Проверьте активный Xcode и доступность цели на удалённом Mac

До запроса параметров выясните, какой Xcode фактически использует задача CI. Путь к активному каталогу разработчика можно проверить командой:

xcode-select -p

Затем проверьте версию Xcode и доступность xctrace через выбранный набор инструментов:

xcodebuild -version
xcrun --find xctrace
xcrun xctrace version

Эти команды — диагностические примеры для оболочки, а не доказательство того, что проект уже готов к записи. Справочник Apple описывает xctrace как средство для записи, импорта, экспорта и символикации trace Instruments; конкретные команды и применимые параметры нужно сверять с локальной справкой установленного инструмента. См. справочник Apple по инструментам командной строки Xcode.

Если xcrun --find xctrace не находит инструмент, сначала выясните, установлен ли нужный Xcode и совпадает ли активный каталог с тем, который ожидает CI. Одной установки Command Line Tools может быть недостаточно, если для вашей задачи требуется инструмент, поставляемый с Xcode. Apple отдельно описывает установку Command Line Tools и выбор активного набора инструментов командной строки. После выбора каталога повторите проверку в том же контексте пользователя и задания, в котором будет выполняться запись.

Далее подтвердите, что проект действительно собирается, а целевой процесс или устройство доступны именно этому заданию. Успешная проверка в интерактивной SSH-сессии ещё не гарантирует такой же результат в агенте CI: у задачи могут отличаться пользователь, переменные окружения, права доступа и доступ к устройству. Проверьте запуск и завершение приложения без записи, прежде чем добавлять Instruments. Это помогает отделить проблему приложения или доступа от проблемы конфигурации xctrace.

Если вам нужно подготовить сам узел и воспроизводимый набор инструментов, сначала определите активную среду по руководству по подготовке удалённого Mac. Для этой статьи ключевое условие простое: команды проверки должны запускаться в том же окружении, которое затем выполнит задачу CI.

Не считайте SSH-доступ эквивалентом готовности агента. Подключение подтверждает, что вы можете открыть удалённую оболочку, но не всегда подтверждает, что автоматизированная задача использует тот же каталог разработчика, получает доступ к целевому приложению и способна записать артефакт в нужное хранилище. Повторите диагностические проверки непосредственно в сценарии CI или в максимально близком к нему тестовом задании. Если проверку выполняет отдельный пользователь, сверяйте настройки именно этого пользователя.

Запросите параметры записи для выбранного шаблона

В Xcode 27 Apple описывает для xctrace record параметр --show-recording-options, который выводит JSON с параметрами записи, доступными для выбранного шаблона. Для передачи подготовленного файла настроек предусмотрен --recording-options. Эти возможности указаны в заметках Apple о выпуске Xcode 27; воспринимайте их именно как функции командной строки, а не обещание одинакового набора настроек для любой цели и конфигурации.

Рабочий порядок такой:

• Выберите подходящий шаблон Instruments для вопроса, который должен прояснить запуск.
• Запросите доступные настройки именно для этого шаблона и сохраните полученный JSON как диагностический артефакт.
• Проверьте структуру и допустимые значения в установленной среде.
• Только после этого подготовьте конфигурационный файл и передайте его команде записи через --recording-options.

Условный пример запроса:

xcrun xctrace record \
  --template "<ИМЯ_ШАБЛОНА>" \
  --show-recording-options

Этот пример показывает способ запросить параметры, а не готовую конфигурацию для любого приложения. Не копируйте выдуманные поля JSON из чужого проекта: требуемые опции зависят от выбранного шаблона и текущего инструментария. Перед использованием конкретной команды сверяйте её с локальной справкой xcrun xctrace record --help и документацией своей версии Xcode.

Как запросить параметры записи Instruments в Xcode 27? Запустите запрос для нужного шаблона в том же окружении, где будет выполняться CI, и изучите фактически выведенный JSON. После этого передавайте файл с подтверждёнными настройками через --recording-options; не предполагайте, что параметры одного шаблона подойдут другому.

Информацию о настройках храните как часть репозитория или конфигурации задачи только тогда, когда команда контролирует её актуальность. Если Xcode обновился, повторите запрос: старый файл может перестать соответствовать реальным параметрам инструмента. Не следует скрывать этот этап в общей переменной CI без записи о том, какой шаблон и версия инструментария использовались.

Перед фиксацией конфигурации проверьте, где она создаётся и как передаётся в задачу. Временный файл должен быть доступен процессу xctrace в момент записи; путь к нему не должен зависеть от интерактивной оболочки разработчика. Если файл формируется на лету, сохраняйте его в журнале или артефактах при условии, что в нём нет чувствительных значений. Если файл хранится в репозитории, связывайте его с шаблоном и проверяйте после изменений версии Xcode.

Передайте фиксированную нагрузку задаче записи

После подготовки условий свяжите шаблон, проверенный конфигурационный файл, целевое приложение и путь вывода. Синтаксис команды и поддерживаемые способы выбора цели проверяйте по справке установленного xctrace: командная строка не даёт оснований утверждать, что любой вариант запуска доступен для всех устройств, приложений и CI-сред.

Пример каркаса команды, где все значения намеренно оставлены заполнителями:

xcrun xctrace record \
  --template "<ИМЯ_ШАБЛОНА>" \
  --recording-options "<ПУТЬ_К_JSON>" \
  --output "<ПУТЬ_К_TRACE>"

Подставляйте параметры цели и запуска только в соответствии с локальной справкой и способом выполнения вашего сценария. Apple демонстрирует автоматизацию xctrace в сессии о работе с Instruments из командной строки, но показанный подход не следует трактовать как подтверждение поддержки всех шаблонов или вариантов подключения. Успешный пример на одном проекте не снимает необходимости проверить ваш целевой процесс, устройство и права доступа.

Параллельно управляйте жизненным циклом приложения отдельными шагами задачи:

• Запустите приложение выбранным и проверенным способом.
• Передайте ему одинаковый вход и выполните согласованную последовательность действий.
• Проверьте, что операция действительно завершилась, а процесс не завершился раньше времени.
• Обработайте ненулевой код завершения записи как ошибку, а не как успешный сбор.
• Проверьте, что ожидаемый файл создан и имеет ненулевой размер, затем зафиксируйте его путь в журналах CI.

Последняя проверка подтверждает лишь наличие выходного файла, но не его анализируемость и не корректность измерений. Поэтому сохраняйте код возврата команды, сообщения об ошибках и сведения о приложении рядом с артефактом. Если задача завершилась с ошибкой, не маскируйте её следующим успешным шагом и не публикуйте пустой или устаревший trace под именем текущего запуска.

Сделайте путь вывода уникальным для запуска либо перед публикацией удаляйте предыдущий файл. Иначе задача может ошибочно принять старый trace за результат текущей записи. В журнале укажите итоговый путь после завершения команды, а не только каталог, в который планировалось записать результат. Когда CI использует отдельные рабочие каталоги, убедитесь, что передача артефакта получает файл из фактического каталога текущего задания.

Как подтвердить активный каталог, если команда Xcode не работает? Выполните xcode-select -p, проверьте путь, затем сравните его с Xcode, который должен использовать агент. Если каталог неверен, настройте активный набор инструментов в контексте CI по документации Apple и повторно проверьте наличие xctrace; проверка в терминале разработчика не заменяет проверку внутри задачи.

Не считайте созданный файл доказательством успешного измерения. Проверяйте, что запись относится к ожидаемому запуску, приложению и нагрузке.

Сохраните trace как прослеживаемый артефакт и проверьте его

Передайте выходной файл в хранилище артефактов CI с названием или метаданными, которые позволяют связать его с коммитом и сценарием. Наряду с файлом сохраните версию Xcode, активный каталог разработчика, выбранный шаблон, использованный конфигурационный JSON, сведения о цели и результат запуска. Если конфигурационный файл может содержать параметры, которые команда не хочет раскрывать, задайте правила хранения и доступа отдельно.

Дальше проверьте не только факт публикации артефакта, но и возможность использовать его в анализе. Откройте trace в Instruments либо проверьте предусмотренный процесс экспорта и чтения данных. Справочник Apple перечисляет xctrace для записи, импорта, экспорта и символикации файлов Instruments, но конкретный путь повторной проверки зависит от того, как устроен ваш анализ. Для изучения и сопоставления профилей полезны материалы Apple о представлениях Call Tree и сравнении запусков.

При проверке проследите, что символы и целевой процесс позволяют интерпретировать содержимое, что файл относится к нужной задаче и что внутренние правила команды допускают его повторное открытие. Если запись открывается, но в ней отсутствует ожидаемый участок работы, вернитесь к порядку запуска приложения и нагрузки. Не исправляйте такую проблему простым изменением порога CI: сначала выясните, действительно ли измерялся нужный сценарий.

Как сохранить trace, созданный удалённым Mac CI? После записи проверьте код завершения и наличие выходного файла, затем опубликуйте его как артефакт текущего запуска вместе с метаданными. Укажите коммит, версию Xcode, шаблон и описание нагрузки. Не перезаписывайте предыдущую запись таким же постоянным именем: иначе связь между историей запусков и файлами станет ненадёжной.

Задайте понятные правила хранения артефактов. Записи нужны для повторного анализа, но политика хранения должна соответствовать требованиям проекта к доступу, объёму хранилища и срокам сохранения. Проверьте, кто может загрузить trace и связанные с ним журналы, а также можно ли восстановить их после завершения задачи. Для долгосрочного сравнения недостаточно оставить ссылку в журнале, если сам файл через некоторое время будет удалён политикой очистки.

Когда запись предназначена только для диагностики, её можно публиковать отдельно от обязательных выходов сборки, сохранив связь с запуском. Если она должна участвовать в проверке выпуска, убедитесь, что публикация артефакта сама по себе не меняет статус проверки: сохранение файла — это операция доставки данных, а не анализ его содержимого. Такой контракт не позволит инженеру принять успешную загрузку артефакта за подтверждение нормального состояния приложения.

Проведите пробный запуск и выберите режим CI

Сначала выполните запись в изолированной задаче, а не сразу в обязательном этапе выпуска. Проверьте весь путь: доступность Xcode и цели, сборку приложения, запуск нагрузки, результат xctrace, публикацию файла и возможность анализа. Только после этого решайте, запускать сбор регулярно, вызывать его по запросу или пока оставить вне основного CI.

Можно ли использовать автоматически записанную производительность как CI-барьер? Не на основании одного факта получения trace. Для решения о регрессии нужны сопоставимые запуски, контролируемые условия выполнения и отдельный анализ; порог и допустимые колебания должны вытекать из реальной базовой линии вашего проекта. Автоматическая запись создаёт материал для проверки, а не готовое заключение.

Примите решение по контрольному списку

Отметьте каждый пункт перед тем, как включать запись в обычную задачу CI:

• [ ] Нагрузка повторяется, входные данные и целевой сценарий зафиксированы.
• [ ] Внутри самой задачи CI подтверждены активный Xcode, доступность xctrace и доступ к целевому процессу или устройству.
• [ ] Параметры записи получены для выбранного шаблона в той же среде, где будет выполняться задача.
• [ ] Команда проверяет код завершения, наличие именно нового trace и его соответствие текущему запуску.
• [ ] Артефакт сохраняется вместе с коммитом, версией Xcode, шаблоном и описанием нагрузки.
• [ ] Команда может открыть или экспортировать trace и знает, кто отвечает за его интерпретацию.

**Если отмечены все пункты,** включайте сбор как диагностическую задачу и сначала сохраняйте результат для анализа. Это ещё не основание блокировать выпуск: для барьера отдельно задайте базовую линию, метод сравнения и порог на собственных повторных тестах.

Если не отмечен хотя бы один из первых пяти пунктов, оставьте задачу в изолированном пробном режиме и устраните пробел до регулярного запуска. Если не определён только ответственный за интерпретацию, допустим запуск по запросу или по расписанию, но не автоматический отказ в слиянии на основании самого факта записи.

Используйте также следующие условия выбора:

• Если нагрузка повторяется, параметры записи получены для нужного шаблона, а trace проходит проверку и сохраняется вместе с контекстом запуска, то включайте задачу как диагностический этап и архивируйте результат для последующего анализа.
• Если сбор записи стабилен, но команда ещё не определила, как интерпретировать результат, то запускайте её по запросу или по расписанию. Не блокируйте слияние или выпуск только из-за наличия автоматически собранных данных.
• Если цель недоступна, приложение запускается нестабильно или задача не различает текущий и устаревший файл, то вернитесь к изолированной проверке. Не добавляйте запись в обязательный CI, пока не устраните неоднозначность.
• Если вы хотите использовать результаты как барьер, то сначала повторите измерения на фиксированной нагрузке и условиях, определите базовую линию и проверьте способ анализа на собственных данных. До этого применяйте запись для диагностики, а не для автоматического отказа в выпуске.
• Если для нужной задачи доступен стабильный локальный Mac и удалённый доступ не даёт преимуществ, то оставьте сбор на локальном узле. Если же нужен доступный CI-узел с macOS, а покупка и обслуживание отдельного компьютера не оправданы для временного процесса, то оцените удалённый Mac и проверьте на нём те же шаги до переноса регулярной нагрузки.

Список условий отделяет готовность к сбору от готовности к блокирующему решению. Даже повторяемый сбор не означает, что команда уже понимает, какие изменения значимы. И наоборот, полезный для анализа trace не обязательно нужно собирать в каждом запуске сборки: для некоторых проектов достаточно запуска по расписанию или при изменении критичного участка кода.

Если команда переходит от ручного анализа к сравнению результатов, фиксируйте условия выполнения и отдельно проверяйте интерпретацию выбранного представления. Apple описывает работу с Call Tree и сравнение запусков в документации по анализу CPU-профилей. Используйте эти материалы как руководство по анализу, но не подменяйте ими проектную базовую линию: применимость сравнения зависит от сценария и данных, которые действительно собирает ваша задача.

Для локальной машины преимущество — прямой контроль над оборудованием и отсутствие отдельного удалённого пути передачи данных; ограничения — необходимость выделить и поддерживать физический узел, а также обеспечить его доступность для CI. Удалённая схема удобна, когда вы хотите проверить работу на Mac без покупки машины и выполнять задачу в удалённом окружении; её дополнительные требования — настроить доступ, сбор артефактов и проверку условий запуска. Если задача требует постоянной нагрузки, особого физического интерфейса или полного контроля над оборудованием, собственный Mac может быть правильнее. Если же вам нужно временно проверить удалённый процесс записи, сначала сравните ограничения вашей текущей схемы: Linux-узел не заменит требуемые инструменты macOS, а личный компьютер может быть недоступен CI в нужный момент.

Если текущая инфраструктура не предоставляет стабильный Mac, удалённый узел MACGPU можно рассматривать как временную среду для проверки процесса, но перед переносом регулярного задания проверьте способ подключения, права, целевой сценарий и доставку trace на практике. Сначала определите, действительно ли вашей команде нужен отдельный удалённый узел; если да, сопоставьте условия задачи с вариантами аренды Mac. Такой выбор оправдан для временной проверки и задач, которым нужен macOS-инструментарий без покупки оборудования, но не заменяет анализ пригодности узла для постоянной нагрузки.