Symptom: Ihre CI soll Instruments-Daten auf einem Remote Mac erfassen, aber die verfügbaren xctrace-Optionen sind nicht verlässlich dokumentiert. Schnellster Weg: Fragen Sie in der tatsächlich verwendeten Xcode-27-Umgebung die Optionen des Ziel-Templates ab, fixieren Sie Arbeitslast und Eingaben und archivieren Sie den erzeugten Trace. Die automatische Aufzeichnung ist noch kein Leistungstor.
Dieser Leitfaden ist für iOS- und macOS-Entwickler gedacht, die wiederkehrende App-Abläufe automatisch aufzeichnen möchten. CI-Ingenieure und Plattformverantwortliche erfahren, wie sie Erfassung, Nachweisführung und Leistungsbewertung voneinander trennen.
Zuletzt aktualisiert am 30.10.2026; geprüft anhand der Xcode-27-Versionshinweise von Apple, der Referenz für Xcode-Kommandozeilenwerkzeuge und der Apple-Demonstration zur xctrace-Automatisierung. Ermitteln Sie die verfügbaren Optionen immer erneut in der Xcode-Umgebung, die Ihren Job tatsächlich ausführt.
1. Vor der Aufzeichnung eine vergleichbare Baseline festlegen
Eine Instruments-Aufzeichnung ist nur dann als Vergleichswert brauchbar, wenn sie zu einer nachvollziehbaren Arbeitslast gehört. Legen Sie zunächst fest, welches konkrete Verhalten Sie beobachten möchten: beispielsweise einen reproduzierbaren App-Ablauf, einen festgelegten Test oder eine wiederkehrende Nutzeraktion. Bestimmen Sie anschließend das passende Instruments-Template und die Frage, die der Trace beantworten soll. Ein Trace ohne klar umrissene Frage kann zwar Daten enthalten, liefert aber nicht automatisch eine belastbare Aussage.
Trennen Sie drei Vorgänge ausdrücklich voneinander:
- Build: Das Projekt wird mit einer dokumentierten Toolchain kompiliert.
- Arbeitslast: Die App wird gestartet und durch festgelegte Eingaben in einen definierten Zustand gebracht.
- Aufzeichnung: xctrace erfasst die ausgewählte Instruments-Konfiguration während des Arbeitslaufs.
Wie legen Sie eine Baseline fest, die sich später vergleichen lässt? Verwenden Sie für Vergleichsläufe denselben Commit, dieselben Eingaben, denselben Zieltyp und dieselbe Start- und Stopp-Logik. Ändert sich eine dieser Bedingungen, kennzeichnen Sie den Lauf als eigene Variante, statt beide Traces ohne Einschränkung nebeneinanderzustellen.
Die Aufnahme kann selbst zusätzliche Arbeit verursachen. Wählen Sie deshalb eine Arbeitslast, die lang und stabil genug ist, um den gewünschten Vorgang abzubilden, und halten Sie die Erfassungsschritte konstant. Legen Sie keine pauschalen Grenzwerte fest, bevor Ihr Team die Streuung der eigenen Arbeitslasten kennt. Der geeignete Schwellenwert hängt von Ihrem Projekt und der Frage ab, ob Sie ein einzelnes Ereignis oder einen wiederkehrenden Trend beurteilen.
2. Den tatsächlichen Xcode-Pfad auf dem Remote Mac prüfen
Bevor die Pipeline Optionen abfragt oder einen Trace aufnimmt, muss feststehen, welche Entwicklerumgebung der Job verwendet. Auf einem Remote Mac können eine vollständige Xcode-Installation und die separaten Kommandozeilenwerkzeuge vorhanden sein. Ein erfolgreicher Aufruf eines anderen Apple-Werkzeugs beweist deshalb nicht, dass xctrace aus der erwarteten Xcode-Installation stammt.
Prüfen Sie den aktiven Entwicklerpfad und das tatsächlich aufrufbare Werkzeug im CI-Benutzerkontext:
xcode-select -p
xcodebuild -version
xcrun --find xctraceVergleichen Sie die Ausgabe mit der für den Job vorgesehenen Xcode-Installation. Für xctrace-Aufzeichnungen sollten Sie nicht einfach annehmen, dass die Kommandozeilenwerkzeuge allein dieselbe Umgebung wie eine vollständige Xcode-Installation bereitstellen. Apple beschreibt sowohl die Installation der Kommandozeilenwerkzeuge als auch die Auswahl der Kommandozeilenwerkzeuge in den Xcode-Einstellungen. Diese Dokumentation ist relevant, wenn ein CI-Job einen unerwarteten Entwicklerpfad verwendet oder ein Werkzeug nicht gefunden wird.
Zeigt xcode-select -p auf eine nicht vorgesehene Umgebung, korrigieren Sie die Auswahl kontrolliert und prüfen Sie die Ausgabe erneut. Ein mögliches Installationsmuster sieht so aus:
sudo xcode-select -s /Applications/Xcode.app/Contents/DeveloperVerwenden Sie diesen Beispielpfad nur, wenn Xcode dort tatsächlich installiert ist. Bei einer anderen Installation muss der Pfad angepasst werden. Vermeiden Sie, die Entwicklerauswahl stillschweigend zwischen Jobs zu ändern: Ein auf dem Rechner gespeicherter Zustand kann sonst dazu führen, dass zwei vermeintlich gleiche Pipeline-Läufe verschiedene Toolchains verwenden.
Bevor Sie xctrace starten, prüfen Sie außerdem, ob das Projekt im selben Benutzer- und Umgebungsprofil gebaut werden kann, das die Aufzeichnung ausführt. Verifizieren Sie den Zugriff auf den Zielprozess beziehungsweise das vorgesehene Gerät und stellen Sie sicher, dass Berechtigungen und erforderliche Sitzungen vorhanden sind. Ein Build-Erfolg allein bestätigt weder, dass das Ziel erreichbar ist, noch dass die gewünschte Instruments-Aufzeichnung starten darf.
Wie prüfen Sie den aktiven Entwicklerpfad, wenn die Kommandozeilenwerkzeuge nicht verfügbar erscheinen? Lassen Sie xcode-select -p im Kontext des betroffenen CI-Jobs laufen, ermitteln Sie mit xcrun --find xctrace den Werkzeugpfad und kontrollieren Sie die Xcode-Version. Falls der Entwicklerpfad auf die falsche Installation zeigt, wählen Sie die vorgesehene Installation aus und wiederholen Sie die Prüfungen, statt den fehlenden Befehl durch einen geratenen Pfad zu ersetzen.
3. Die passenden xctrace-Aufzeichnungsoptionen abfragen
Xcode 27 dokumentiert für xctrace record die Möglichkeit, die Aufzeichnungsoptionen eines Templates als JSON auszugeben und eine Konfigurationsdatei mit Aufzeichnungsoptionen zu übergeben. Die Xcode-27-Versionshinweise sind die Quelle für diese hinzugefügte Funktion. Welche Optionen tatsächlich erscheinen, hängt jedoch von der verwendeten Toolchain und dem abgefragten Template ab. Übertragen Sie daher keine vermeintlich universelle JSON-Datei ungeprüft zwischen Projekten.
Fragen Sie die Optionen mit dem vorgesehenen Template ab. Die folgende Form zeigt die relevanten Argumente; ersetzen Sie den Platzhalter durch den Template-Namen, den Ihr Ablauf tatsächlich verwendet:
xcrun xctrace record \
--template "$TEMPLATE" \
--show-recording-optionsVerwenden Sie die Ausgabe dieser Abfrage als Grundlage für die Konfigurationsdatei. Ergänzen Sie keine Felder, die nicht für Ihr Template und Ihre installierte Version bestätigt sind. Speichern Sie die erzeugte oder angepasste JSON-Konfiguration versioniert oder als nachvollziehbares Pipeline-Artefakt und verknüpfen Sie sie mit dem Template sowie der Xcode-Version.
Wie fragen Sie die konfigurierbaren Instruments-Aufzeichnungsoptionen ab? Führen Sie die Abfrage in der Umgebung aus, in der der spätere Erfassungsschritt läuft, und geben Sie das konkrete Template an. Prüfen Sie die zurückgegebene JSON-Struktur, bevor Sie sie in der Pipeline verwenden. So behandeln Sie „Instruments recording options“ nicht als feste, von der Umgebung unabhängige Schnittstelle.
Die Referenz zu den Xcode-Kommandozeilenwerkzeugen ordnet xctrace den Aufgaben Aufzeichnen, Importieren, Exportieren und Symbolisieren von Instruments-Traces zu. Daraus folgt keine Zusicherung, dass jedes Template, jedes Ziel oder jeder CI-Ausführungskontext ohne zusätzliche Prüfung funktioniert. Behandeln Sie das Abfragen als Konfigurationsschritt und nicht als Beweis, dass die spätere Aufzeichnung bereits erfolgreich sein wird.
4. Erfassung und Archivierung im CI-Ablauf verbinden
Die Erfassung sollte einen benannten, kontrollierbaren Schritt bilden: Konfiguration laden, Ziel starten oder auswählen, Arbeitslast ausführen, Aufzeichnung beenden und anschließend den erzeugten Trace prüfen. Ein möglicher Aufruf mit Platzhaltern sieht so aus:
xcrun xctrace record \
--template "$TEMPLATE" \
--recording-options "$OPTIONS_JSON" \
--output "$TRACE_PATH" \
--launch "$APP_OR_PROCESS"Die Platzhalter stehen für Ihre eigenen Werte; sie sind keine allgemein gültige Projekt-, Prozess- oder Gerätekonfiguration. Prüfen Sie anhand der Apple-Dokumentation, welche Argumente für das konkrete Ziel und den vorgesehenen Ablauf erforderlich sind. Wo Ihre Arbeitslast ein separates Start-, Test- oder Stopp-Skript benötigt, führen Sie es explizit aus und behandeln Sie seinen Exit-Status als Teil des Erfassungsergebnisses.
Ein Pipeline-Schritt sollte nicht nur melden, dass der xctrace-Befehl beendet wurde. Prüfen Sie auch, ob die erwartete Ausgabedatei vorhanden ist, ob der vorherige Start der App erfolgreich war und ob das Skript für die Arbeitslast einen Fehler gemeldet hat. Lassen Sie einen fehlgeschlagenen Build oder Test nicht durch eine nachgelagerte Aufzeichnung verdecken. Umgekehrt darf eine fehlende Aufzeichnung nicht als erfolgreicher Lauf gelten, nur weil der eigentliche Build bestanden hat.
Die Artefaktablage sollte jede Datei mit ihrem Entstehungskontext verbinden. Erfassen Sie mindestens die Commit-Kennung, Xcode-Version, Template-Bezeichnung, Zielkennung und Arbeitslastkennung in den Metadaten des Jobs oder in einer begleitenden Manifestdatei. Vermeiden Sie in Dateinamen oder Logs unnötige personenbezogene Daten und sensible Eingaben; für teamübergreifende Ablagen sind Aufbewahrung, Zugriff und Löschung nach Ihren Datenschutzvorgaben zu regeln.
| Ablauf | Eignungsbewertung | Was Sie zuverlässig erhalten | Grenze |
|---|---|---|---|
| Manuelle Aufzeichnung auf einem Entwicklungsgerät | Bedingt geeignet | Direkte Kontrolle über App und Instruments | Der Ablauf ist nicht automatisch reproduzierbar oder als CI-Nachweis verfügbar |
| xctrace-Erfassung in einem Remote-Mac-CI-Job | Stark geeignet, wenn die Arbeitslast festgelegt ist | Automatisierbare Traces mit Pipeline-Kontext und nachvollziehbarer Konfiguration | Ein erzeugter Trace belegt noch keine Regression oder Verbesserung |
| Aufzeichnung als unmittelbares Leistungstor | Schwach geeignet, solange keine Projekt-Baseline vorliegt | Ein automatischer Jobstatus | Ohne kontrollierte Wiederholung und begründete Schwellenwerte kann der Status irreführen |
Wie bewahren Sie einen in Remote-Mac-CI erzeugten Trace auf? Geben Sie einen eindeutigen Ausgabeort an, prüfen Sie nach dem Lauf, ob die Datei vorliegt, und laden Sie sie als Pipeline-Artefakt mit den zugehörigen Metadaten hoch. Behandeln Sie die Ablage als fehlgeschlagen, wenn der Job erfolgreich endet, aber der erwartete Trace oder seine Zuordnung zum Commit fehlt.
5. Lesbarkeit und Aussagekraft getrennt nachweisen
Ein Trace, der als Datei vorliegt, ist noch nicht zwangsläufig sinnvoll auswertbar. Prüfen Sie daher nach der Ablage, ob sich das Artefakt in Instruments öffnen oder mit einem geeigneten Werkzeug exportieren lässt. Diese Prüfung bestätigt, dass das Artefakt lesbar und für die vorgesehene Analyse zugänglich ist. Sie bestätigt für sich genommen weder eine Regression noch eine Leistungsverbesserung.
Für die Analyse müssen die beobachteten Abläufe mit der festgelegten Fragestellung übereinstimmen. Apple beschreibt in der Anleitung zur Analyse von CPU-Profilen mit Aufrufbaumansichten, wie Aufrufbaumansichten und Vergleiche bei der Untersuchung von CPU-Profilen helfen. Übernehmen Sie daraus keine allgemeine Leistungsgrenze: Die Anleitung erklärt Analysefunktionen, nicht den für Ihr Projekt passenden Schwellenwert.
Eine belastbare Auswertung sollte mindestens prüfen:
- ob der Trace den gewünschten Zeitraum und die definierte Arbeitslast abbildet;
- ob die Metadaten mit Commit, Ziel und Toolchain übereinstimmen;
- ob die beobachtete Abweichung in einer kontrollierten Wiederholung sichtbar bleibt;
- ob Unterschiede aus dem Testablauf, der Ausführungsumgebung oder der App selbst stammen können.
6. Mit kontrollierten Probeläufen über die CI-Nutzung entscheiden
Bevor Sie eine Aufzeichnung in reguläre Jobs oder ein Leistungstor aufnehmen, führen Sie den Ablauf in einer isolierten Pipeline aus. Prüfen Sie dabei nacheinander den Entwicklerpfad, die Template-Abfrage, den Start der Arbeitslast, den xctrace-Exit-Status, das Vorhandensein des Artefakts und dessen tatsächliche Lesbarkeit. Dokumentieren Sie außerdem, was bei jedem Fehler passiert: Wird der Job abgebrochen, bleibt ein Teil-Artefakt erhalten oder kann der nächste Schritt fälschlich als erfolgreich erscheinen?
Nutzen Sie anschließend diese Entscheidungszweige:
- Wenn die Arbeitslast reproduzierbar ist, die Optionsabfrage im vorgesehenen Xcode funktioniert und Trace sowie Metadaten vollständig archiviert werden, dann nehmen Sie die Aufzeichnung als Diagnoseartefakt in den passenden CI-Ablauf auf.
- Wenn die Erfassung funktioniert, die Arbeitslast aber noch schwankt oder die Traces nicht verlässlich ausgewertet werden können, dann führen Sie sie zunächst nur bei Bedarf aus und verbessern Baseline und Analyseverfahren.
- Wenn Zielzugriff, Toolchain oder Artefaktübergabe nicht zuverlässig sind, dann nehmen Sie die Aufzeichnung noch nicht als Freigabekriterium auf; beheben Sie zuerst den fehlerhaften Schritt oder verschieben Sie die Analyse in einen kontrollierten manuellen Ablauf.
- Wenn Sie ein automatisches Leistungstor erwägen, dann legen Sie die Schwellenwerte erst aus wiederholbaren Messungen Ihrer eigenen Anwendung und deren kontrollierten Ausführungsbedingungen fest.
Planen Sie auch den Betrieb ein. Eine Remote-Mac-Umgebung muss für den Job erreichbar sein, zur vorgesehenen Toolchain passen und Traces zuverlässig an die nachgelagerte Ablage übergeben. Ein Kauf eines eigenen Mac kann sinnvoller sein, wenn Sie dauerhaft eine gleichbleibende, physisch kontrollierte Entwicklungsmaschine benötigen. Eine vorhandene Linux-CI-Umgebung kann für plattformunabhängige Builds und Tests weiterhin die passende Wahl sein; für die hier beschriebene Instruments-Erfassung ist sie jedoch kein Ersatz für die erforderliche macOS- und Xcode-Umgebung.
Bei einem bestehenden Remote-Mac-Aufbau sollten Sie zusätzlich prüfen, ob die gebuchte Umgebung zu Ihrer Auslastung und Zugriffsmethode passt. Die MACGPU-Übersicht zu verfügbaren Mac-Konfigurationen ist dafür ein möglicher Einstieg; beurteilen Sie die konkrete Eignung anhand Ihrer Anforderungen an Toolchain, Zugriff und Artefaktübergabe, nicht anhand einer allgemeinen Leistungsannahme.
Wenn Sie Instruments nur für einen begrenzten CI-Versuch benötigen, kann die Miete eines Remote Mac die Beschaffung einer eigenen Maschine und deren laufende Pflege vermeiden. Sie sollten dennoch die tatsächlichen Nachteile Ihrer bisherigen Lösung abwägen: Lokale Erfassung bindet den Arbeitsplatz und kann den Vergleich zwischen Rechnern erschweren; ein Linux-Runner stellt die benötigte macOS- und Xcode-Umgebung nicht bereit; eine dauerhaft selbst betriebene Maschine bringt Einrichtungs-, Wartungs- und Wiederherstellungsaufwand mit sich. Für einen zeitlich begrenzten, reproduzierbaren Erfassungslauf kann MACGPU daher die passendere praktische Option sein. Bei dauerhaft hoher Grundlast oder zwingendem Bedarf an lokalen physischen Schnittstellen bleibt ein eigener Mac möglicherweise zweckmäßiger.