XCODE 27 XCTRACE
intégrer les options d’enregistrement à un CI Mac distant ? Guide 2026

La collecte xctrace peut être intégrée à un CI Mac distant si vous interrogez d’abord les options du modèle Instruments utilisé, puis gardez la charge de travail et l’archive de trace identifiables. Cette automatisation recueille des données à analyser ; elle ne constitue pas, à elle seule, une porte de performance fiable.

Cet article s’adresse aux développeurs iOS et macOS qui veulent automatiser une capture Instruments, aux ingénieurs CI qui doivent conserver ces traces, et aux responsables de plateforme qui déterminent quelles tâches peuvent tourner sans surveillance. Si vous cherchez plutôt à diagnostiquer une régression précise, vous aurez aussi besoin d’un protocole de comparaison propre au projet.

Dernière mise à jour : 30 octobre 2026. Les fonctions Xcode citées ont été vérifiées dans les notes de version Xcode 27, la référence des outils de ligne de commande Xcode et la documentation Instruments liée ci-dessous. Les options détaillées doivent toujours être confirmées dans l’environnement qui exécutera la tâche.

Préparer une référence avant de capturer

Une trace n’est interprétable que si vous savez ce que l’application faisait au moment de l’enregistrement. Avant de modifier le pipeline, choisissez une opération que vous pouvez relancer de la même manière : ouverture d’un document de test, rendu d’une scène, lecture d’un média, navigation dans un parcours utilisateur ou exécution d’un test automatisé. Les travaux audio, vidéo et de conception graphique peuvent bénéficier d’une capture ciblée, à condition que les fichiers d’entrée et les réglages restent identifiables.

Définissez ensuite la question que la trace doit aider à examiner. Cherchez-vous à comprendre l’activité du processeur pendant un rendu, à repérer une attente dans le parcours ou à comparer l’exécution d’une même opération après une modification ? Le modèle Instruments doit correspondre à cette question. Une trace produite avec un autre modèle, une autre entrée ou une autre étape de démarrage n’est pas une comparaison équivalente.

Dans le pipeline, séparez explicitement trois opérations :

• Construire l’application à partir du commit prévu.
• Exécuter l’application avec une entrée et un scénario reproductibles.
• Enregistrer la trace Instruments pendant la fenêtre de travail pertinente.

Cette séparation aide à attribuer un échec au bon endroit. Un build réussi ne confirme pas que la cible a été lancée ; une cible lancée ne prouve pas que le scénario s’est terminé ; un fichier trace créé ne prouve pas que la capture couvre l’opération souhaitée.

Consignez, avec chaque exécution, l’identifiant du commit, le schéma de build, la cible ou le processus, les données d’entrée et le scénario lancé. Pour une tâche qui compare des résultats, gardez également les conditions d’exécution aussi cohérentes que possible. Une charge interrompue, une application déjà ouverte ou un autre état de données peut modifier ce que la trace représente. Il vaut mieux marquer l’échantillon comme non comparable que de présenter son résultat comme un signal de performance.

Vérifier le Xcode réellement utilisé par le nœud

Sur le Mac distant, vérifiez le Xcode que le processus CI utilise réellement, plutôt que de déduire son choix à partir des outils installés. Le chemin du répertoire développeur actif et celui de l’exécutable trouvé par la tâche doivent être cohérents avec l’environnement prévu. Les commandes suivantes servent de contrôles de départ :

xcode-select -p
xcodebuild -version
xcrun --find xctrace

La documentation Apple sur le choix des outils de ligne de commande explique le rôle du répertoire développeur actif. La page consacrée à l’installation des outils de ligne de commande décrit cette installation, mais disposer de ces outils ne signifie pas automatiquement que la tâche CI utilise le Xcode voulu. Si le chemin actif n’est pas celui attendu, sélectionnez explicitement l’installation appropriée selon votre configuration, puis relancez les vérifications dans le contexte du travail CI.

Vérifiez aussi que le projet se construit dans cette même tâche et que la cible à observer est accessible. Selon le scénario, cela signifie confirmer que l’application peut être lancée, que le simulateur ou l’appareil choisi est disponible et que le processus observé correspond au bon binaire. Le guide de référence des outils en ligne de commande Xcode décrit xctrace comme un outil destiné à enregistrer, importer, exporter et symboliser des traces Instruments. Il ne garantit pas que chaque combinaison de modèle, de cible et de contexte CI fonctionnera sans vérification.

Pour éviter une erreur de sélection silencieuse, consignez les sorties de contrôle avec les journaux du travail. Comparez-les à la configuration déclarée du nœud, pas seulement à votre poste de développement. Dans un environnement où plusieurs installations Xcode coexistent, une tâche qui fonctionne localement peut appeler un outil différent sur le serveur.

Interroger les options du modèle avant de configurer l’enregistrement

Avec Xcode 27, xctrace peut afficher le JSON des options d’enregistrement prises en charge par le modèle choisi avec --show-recording-options, puis accepter un fichier de configuration au moyen de --recording-options. Ces possibilités sont décrites dans les notes de version Xcode 27. Elles ne signifient pas qu’un fichier unique convient à tous les modèles ou à toutes les cibles.

Commencez par choisir le modèle en fonction de la question définie lors de la préparation. Interrogez ensuite les options de ce modèle dans le même environnement Xcode que celui du CI. Le principe de commande est le suivant :

xcrun xctrace record \
  --template "<MODELE_INSTRUMENTS>" \
  --show-recording-options

Remplacez le texte entre chevrons par le modèle retenu. Examinez la sortie générée par votre installation et créez le fichier de configuration à partir de ces options. N’ajoutez pas des champs issus d’un exemple conçu pour un autre modèle : leur présence dans un ancien script ne démontre pas qu’ils soient pris en charge dans votre chaîne d’outils.

Une fois le fichier préparé, passez son chemin à --recording-options lors de l’enregistrement. Gardez le fichier de configuration dans le dépôt ou parmi les paramètres versionnés du pipeline si vous souhaitez relire, expliquer et reproduire les choix appliqués. Si vous le générez pendant le travail, publiez aussi la configuration effectivement utilisée comme artefact ; une référence à un fichier temporaire supprimé après l’exécution ne permet pas de retrouver les paramètres.

La commande de découverte ne valide pas à elle seule le scénario complet. Vous devez encore contrôler la cible, la disponibilité du simulateur ou de l’appareil si votre parcours en dépend, les permissions et le cycle de vie de l’application. Les commandes et possibilités décrites par Apple établissent la fonction de l’outil ; le protocole d’exécution reste à valider pour votre projet.

Lancer une capture reproductible sur le Mac distant

Le pipeline doit relier le modèle, le fichier d’options confirmé, la cible, la charge de travail et le chemin de sortie. Utilisez des variables clairement nommées afin de distinguer les paramètres du projet des valeurs propres à une exécution :

TEMPLATE="<MODELE_INSTRUMENTS>"
OPTIONS_FILE="<CHEMIN_CONFIGURATION_JSON>"
APP_PATH="<CHEMIN_APPLICATION>"
TRACE_PATH="<CHEMIN_SORTIE_TRACE>"
WORKLOAD_ID="<IDENTIFIANT_CHARGE>"

# Construire l’application avec la configuration prévue.
# Préparer la cible et les données d’entrée.
# Lancer l’enregistrement avec les options confirmées.
# Exécuter la charge, arrêter proprement la capture et vérifier le résultat.

Ce fragment montre l’organisation du travail, pas une commande universelle prête à copier : les paramètres requis varient selon le modèle et le type de cible. Construisez la commande complète à partir des options révélées par l’outil et de la référence Xcode. L’exemple n’implique pas qu’un même mode de lancement convienne à une application, un simulateur et un appareil physique.

Veillez à ce que le lancement de la charge soit identifiable par le script. Si l’application ne démarre pas, si l’action de test échoue ou si l’arrêt de l’enregistrement retourne un état d’erreur, le travail doit le signaler clairement. Ne laissez pas un fichier antérieur portant le même nom être pris pour la trace de l’exécution actuelle : choisissez un chemin propre à l’exécution ou supprimez et vérifiez les anciens fichiers avant la capture. Ainsi, le contrôle d’existence final ne valide pas accidentellement un artefact périmé.

Le pipeline doit également garder le statut d’échec du processus qui a réellement exécuté le scénario. Un script qui continue après un échec, puis termine avec le statut d’une simple commande de copie peut afficher un travail vert alors que la capture n’a jamais eu lieu. Séparez donc le contrôle du résultat d’exécution de la publication de l’artefact, et faites échouer le travail si l’étape de mesure n’a pas abouti conformément au scénario prévu.

Enfin, ne déclenchez pas l’enregistrement sur un processus seulement parce que son nom semble correct. Vérifiez que l’application visée est celle du commit en cours et que la capture commence avant l’opération à mesurer. Pour une tâche de rendu ou de lecture audio/vidéo, consignez aussi le fichier source et les réglages qui déterminent le travail effectué : sans ces informations, deux traces portant le même nom peuvent décrire des charges différentes.

Archiver la trace et vérifier qu’elle s’ouvre

Après l’enregistrement, vérifiez le statut de la commande et la présence du fichier de sortie à l’emplacement attendu. Puis publiez la trace comme artefact CI avec un nom qui permet de la relier au commit et au scénario. L’archive doit aussi conserver les métadonnées utiles : version de Xcode, modèle Instruments, cible, identifiant de charge et configuration d’enregistrement. Ces informations ne remplacent pas la trace ; elles rendent son origine vérifiable.

Ne concluez pas à la lisibilité parce qu’un fichier portant l’extension attendue a été créé. Ouvrez-le dans Instruments ou utilisez une voie d’exportation prise en charge, puis contrôlez que l’enregistrement contient les données nécessaires à l’analyse. La référence Xcode décrit les opérations d’importation, d’exportation et de symbolisation ; pour interpréter une comparaison de mesures, la documentation sur les vues d’arbre d’appels et la comparaison des exécutions fournit des indications propres à l’analyse des profils CPU.

Pour vérifier la procédure elle-même, Apple a aussi présenté l’automatisation d’Instruments et de xctrace dans cette démonstration WWDC consacrée à l’automatisation. Servez-vous de cette ressource comme illustration de l’approche ; vérifiez les paramètres effectifs dans la version de Xcode qui exécute votre pipeline plutôt que de transposer sans contrôle un exemple d’une autre version.

La règle de décision reste simple : trace enregistrée signifie artefact recueilli ; trace ouverte et reliée à une charge précise signifie artefact vérifiable ; seule une analyse comparative contrôlée peut soutenir une conclusion de performance. Une trace isolée ne démontre ni amélioration ni régression.

FAQ : résoudre les questions de configuration avant le déploiement

Comment découvrir les options d’enregistrement disponibles pour un modèle Instruments ? Dans le Xcode qui sera utilisé par la tâche, demandez à xctrace d’afficher les options de configuration du modèle retenu avec --show-recording-options. Examinez le JSON réellement retourné, puis archivez-le avec la configuration du pipeline. Ne supposez pas qu’un fichier générique trouvé dans un autre projet conviendra : les paramètres doivent être confirmés pour le modèle et la chaîne d’outils concernés.

Comment conserver une trace xctrace produite sur un Mac distant ? Donnez à la capture un chemin de sortie explicite sur le nœud, vérifiez que le travail courant a bien créé le fichier, puis publiez-le comme artefact CI. Associez-lui le commit, le modèle, la version de Xcode, la cible et l’identifiant de charge. Cette chaîne de métadonnées vous permet de retrouver l’origine de la trace sans confondre sa conservation avec une conclusion sur les performances.

Une trace recueillie automatiquement peut-elle devenir un contrôle bloquant ? La collecte automatique ne suffit pas à établir une porte de performance. Vous devez d’abord constituer une référence reproductible, vérifier que les charges sont comparables et déterminer comment votre projet traite la variabilité. Les seuils et les règles d’échec doivent venir de résultats réellement obtenus et analysés par l’équipe ; sans cela, le CI risque de bloquer sur un bruit de mesure ou de manquer une dérive pertinente.

Que faire si le Xcode actif n’est pas celui attendu par le travail CI ? Contrôlez le répertoire développeur sélectionné et la version signalée dans les journaux de la tâche, puis vérifiez que xcrun résout bien xctrace depuis l’installation prévue. Si la sélection pointe ailleurs, définissez explicitement le chemin Xcode attendu pour ce travail et répétez les vérifications. L’installation séparée des outils de ligne de commande ne garantit pas que l’environnement actif soit celui dont dépend votre capture.

Décider si la collecte doit rejoindre le CI régulier

Avant de rendre la capture périodique, effectuez un essai isolé qui couvre toute la chaîne : sélection du Xcode, construction, préparation de la cible, exécution de la charge, arrêt de xctrace, création de la trace et publication de l’artefact. Vérifiez également le traitement des erreurs : une charge qui échoue ne doit pas être présentée comme une collecte valide simplement parce qu’un fichier est resté dans le répertoire.

Puis choisissez le mode d’exploitation en fonction de la valeur attendue et du coût de maintenance :

• Si la charge est stable et utile à chaque cycle, que la durée et le stockage sont acceptables pour votre équipe et que les échecs sont interprétables, ajoutez la collecte au pipeline régulier.
• Si les captures servent surtout à examiner une modification ou un incident, déclenchez-les à la demande ou sur une branche dédiée, plutôt que d’imposer une trace à chaque exécution.
• Si la cible, les entrées ou les conditions varient sans contrôle, différez la comparaison automatique et commencez par stabiliser le scénario ; conservez éventuellement les traces à des fins d’investigation, sans les traiter comme une mesure de régression.
• Si personne ne peut ouvrir les artefacts ni décider quoi faire des résultats, ne transformez pas encore la collecte en porte bloquante. Automatisez d’abord l’archivage et la revue.

Ce choix sépare la collecte utile du contrôle réellement défendable. Un pipeline peut enregistrer de façon fiable sans avoir encore les références ni les critères qui autorisent une décision automatique. Pour comparer des mesures, définissez avec l’équipe des conditions reproductibles et des seuils issus de votre propre historique ; ne reprenez pas une valeur arbitraire d’un exemple extérieur. <

Mode d’intégration	Quand le retenir	Appréciation
Collecte périodique, sans blocage	Vous avez besoin d’un historique et les traces peuvent être examinées ultérieurement.	Favorable si l’archivage est maîtrisé
Capture déclenchée à la demande	L’analyse sert surtout à une enquête ciblée ou à la validation d’un changement précis.	Favorable pour limiter les exécutions inutiles
Porte de performance automatique	Une charge reproductible, une référence exploitable et une règle d’interprétation sont déjà validées par l’équipe.	Conditionnelle ; à justifier par vos mesures
Pas de collecte CI pour le moment	La cible ou la charge varie trop, ou les traces ne peuvent pas être relues.	Préférable à une alerte trompeuse

Si vous ne disposez pas déjà d’un Mac adapté à l’exécution distante de cette chaîne, comparez d’abord votre environnement actuel à un nœud Mac dédié. Une machine non-Mac ne fournit pas le même contexte d’exécution pour les outils Instruments ; une installation locale mobilisée ponctuellement peut, de son côté, compliquer la disponibilité du travail CI et la conservation des artefacts. La location n’est toutefois pas le meilleur choix pour une charge continue et prévisible qui justifie l’achat d’un matériel dédié, ni si votre tâche exige un accès physique spécifique.

Pour une collecte temporaire, un essai de migration ou une capacité CI que vous ne souhaitez pas acheter immédiatement, MACGPU peut vous permettre de valider le parcours sur un véritable Mac distant avant de décider de la suite. Vous pouvez consulter les informations de MACGPU sur les Mac distants et la présentation des configurations de Mac distant proposées par MACGPU, puis vérifier concrètement l’accès, la sélection de Xcode et le transfert de traces selon les besoins de votre équipe.