wieslawsoltes/Performance-Skill

Ingénierie de performance .NET

Utilisez ce skill lorsque vous investiguez, expliquez, corrigez, benchmarkez ou validez la performance d'une application .NET, y compris ASP.NET Core, les services, les applications console, Avalonia, WPF, WinUI, MAUI, Skia, WebGPU, les moteurs de jeu/graphiques, NativeAOT et les charges de travail d'interopérabilité native.

Ce dépôt définit un skill. SKILL.md est le point d'entrée de politique et de routage ; les procédures opérationnelles détaillées vivent dans une arborescence de référence hiérarchique. Chargez uniquement les index et chapitres requis par l'investigation en cours, puis étendez lorsque les preuves traversent une frontière de propriété.

Règles non-négociables

• Profiler et benchmarker une build optimisée, normalement Release, dans la forme de déploiement réelle.
• Enregistrer le commit et l'état sale, le SDK/runtime, l'OS, l'architecture, le matériel, le mode d'alimentation, la charge, les versions des outils, les surcharges d'environnement et les commandes exactes.
• Établir une reproduction déterministe avant de modifier le code.
• Séparer le démarrage à froid, la première utilisation, le régime permanent chaud, la surcharge, la vidange et l'arrêt.
• Chauffer la compilation par niveaux, les shaders, les pipelines, les caches et les pools sauf si le comportement à froid est le sujet.
• Collecter des preuves à chaque frontière de propriété pertinente : runtime managé, bibliothèque native, noyau, planificateur, système de fichiers/réseau, dépendance, pilote, GPU, compositeur et affichage.
• Ne pas déduire la rétention managée de la seule RSS.
• Ne pas déduire la saturation du GPU du seul temps d'image élevé, de l'utilisation de l'API GPU ou de l'utilisation seule.
• Ne pas revendiquer un correctif à partir d'une moyenne, d'une trace, d'une capture d'image, d'un microbenchmark ou de l'exécution de benchmark la plus rapide.
• Préserver les artefacts bruts et signaler les symboles manquants, les événements abandonnés, la surcharge du profileur, la variance environnementale et l'incertitude.
• Protéger les secrets et les données personnelles dans les vidages, traces, logs, spans SQL, captures de paquets et corpus d'entrée de benchmark.
• Traiter les exemples de commandes comme sensibles à la version. Interroger d'abord l'aide de l'outil installé ; elle prévaut sur les exemples lorsque la syntaxe diffère. Utiliser references/command-reference.md pour les règles de sélection vérifiées et les formes canoniques.¹

Sortie d'investigation requise

Rapportez :

1. Symptôme — impact observable et cible violée.
2. Reproduction — charge et environnement déterministes.
3. Collecte — outils exacts, commandes, durée et chemins des artefacts.
4. Preuves — compteurs, traces, captures, vidages, distributions de benchmark et mesures.
5. Propriété — CPU managé, runtime, CPU natif, noyau, planificateur, I/O, dépendance, mémoire, pilote, GPU, compositeur ou affichage.
6. Cause dominante — coût, attente ou ressource à la croissance la plus rapide le plus important.
7. Correctif — plus petit changement de code ou de configuration à fort effet de levier.
8. Validation — exécutions avant/après équivalentes avec métriques de distribution et de queue.
9. Risques résiduels — goulots d'étranglement non résolus et limites de mesure.

Ne jamais revendiquer une amélioration sans preuves avant/après provenant d'une charge équivalente.

Routeur de référence

Commencez toujours par references/index.md, references/core/index.md et le references/command-reference.md vérifié.

Chargez des index de domaine supplémentaires par question :

• CPU managé, allocation, GC, JIT, exceptions, ThreadPool, verrous, piles async, vidages : references/runtime/index.md
• Propriété de la mémoire managée/native/VM/mappée/GPU et analyse de fuite : references/memory/index.md
• Contention, latence async, files d'attente, contre-pression, I/O fichier/réseau/base de données, latence du répartiteur IU : references/latency/index.md
• Démarrage à froid, première image/requête, chargeur, JIT, ReadyToRun, élagage, fichier unique, NativeAOT : references/startup/index.md
• BenchmarkDotNet, benchmarks micro/composant/macro/charge/endurance, benchmarks async/concurrence, comparaisons JIT/AOT, désassemblage, compteurs matériels, statistiques, portes CI : references/benchmarking/index.md
• Production, conteneurs, ports de diagnostic, dotnet-monitor, collecte déclenchée, Kubernetes, sécurité des artefacts : references/production/index.md
• IU/rendu/GPU/WebGPU/Metal/D3D/Vulkan/OpenGL/shader/synchronisation/présentation : references/gpu/index.md

Chargez chaque référence de plateforme pertinente via references/platforms/index.md. Une investigation sur un seul hôte nécessite généralement un document de plateforme ; les comparaisons multiplateformes et les scénarios à distance/client-serveur peuvent en nécessiter plusieurs.

Ne chargez pas chaque document par défaut. Sélectionnez l'ensemble minimum qui répond à l'hypothèse actuelle, mais ne vous arrêtez pas à une frontière de propriété simplement parce qu'un autre guide est nécessaire.

Séquence de triage rapide

1. Construire et exécuter la configuration équivalente à la production.
2. Définir les phases de charge, les métriques de succès et une règle d'arrêt.
3. Enregistrer les compteurs System.Runtime ainsi que le CPU du processus et la mémoire totale.
4. Capturer les preuves CPU/runtime managé avec dotnet-trace lorsque la propriété managée est plausible.
5. Capturer les piles répétées lorsque la progression, la famine ou le blocage est suspecté.
6. Si le coût total est inexpliqué, collecter la trace CPU/planificateur/I/O/mémoire native de la plateforme.
7. Pour la mémoire, comparer les octets vivants managés, l'engagement GC, le privé/RSS/PSS, les allocations natives, les mappages, les allocations graphiques et la résidence GPU.
8. Pour le rendu, corréler les marqueurs d'application, la soumission CPU, les horodatages GPU, la capture GPU native, le présent, le compositeur et la synchronisation d'affichage.
9. Pour les demandes de benchmark, choisir la méthodologie micro, composant, macro, charge ou endurance avant de sélectionner BenchmarkDotNet ou un autre harnais.
10. Pour les incidents de production uniquement, utiliser une collecte bornée ou déclenchée et enregistrer les contraintes cgroup/hôte.
11. N'implémenter qu'après que les preuves soutiennent la cause dominante.
12. Répéter la charge identique et publier les valeurs médiane, dispersion, queue et artefacts bruts.

Tests de propriété

• CPU de processus élevé avec piles managées chaudes : travail d'application/JIT/runtime.
• CPU de processus élevé en dessous de P/Invoke : bibliothèque native, allocateur, API graphique ou CPU du pilote.
• CPU faible avec piles bloquées répétées : synchronisation, I/O, planificateur, mise en file d'attente ou dépendance externe.
• File d'attente ThreadPool croissante avec CPU faible et piles bloquées : famine ou synchronisation sur async.
• Octets vivants managés stables avec privé/RSS croissant : tas natif, mappages, tas de code, fragmentation, ressources graphiques ou caches OS.
• Graphe vivant managé croissant après des points de collecte complets équivalents : rétention managée ou cache délibérément non borné.
• Image CPU longue avec horodatages GPU courts : application/file de rendu/pilote lié au CPU.
• Soumission CPU courte avec horodatages GPU longs : exécution liée au GPU.
• CPU et GPU terminent tôt mais le présent est en retard : swapchain, compositeur, vsync, famine drawable ou cadencement d'affichage.
• Écarts GPU inactifs entre les soumissions dépendantes : famine CPU, synchronisation excessive, sérialisation ou mise en mémoire tampon insuffisante.
• Latence élevée avec faible temps sur CPU : attente hors CPU, mise en file d'attente, dépendance, limitation ou retard du planificateur.
• Le démarrage s'améliore mais la première action se détériore : le travail a été différé plutôt que supprimé.
• Le benchmark s'améliore mais la métrique du produit ne suit pas : l'expérience a omis le chemin critique, utilisé la mauvaise distribution d'entrée ou optimisé une opération non dominante.

Procédure opérationnelle de l'agent

• Inspecter la construction du dépôt, le déploiement, les diagnostics, les projets de benchmark, les corpus d'entrée, le CI et les conventions d'artefacts.
• Créer artifacts/performance/<issue-ou-horodatage>/ ou l'équivalent du dépôt.
• Ajouter un pilote de charge déterministe et des marqueurs stables en leur absence.
• Stocker les commandes, les métadonnées d'environnement, les versions de l'analyseur/outil et les liens de référence officiels à côté des artefacts.
• Analyser d'abord les coûts inclusifs, puis les coûts exclusifs, les appelés, les attentes, la mise en file d'attente, la synchronisation et la propriété.
• Modifier le code seulement après que la cause dominante est soutenue.
• Ajouter un benchmark, un budget de régression, un marqueur de télémétrie, une recette de trace ou un invariant de durée de vie qui empêche la récurrence.
• Conserver les grands artefacts de trace, capture, vidage et benchmark hors de Git, sauf si la politique du dépôt les stocke explicitement.
• Valider les chemins d'échec, d'annulation, de surcharge, de nettoyage, de perte d'appareil et d'arrêt — pas seulement le chemin heureux.

Conclusions invalides à rejeter

• « Le CPU est élevé, donc la méthode X est lente » sans piles.
• « La RSS a augmenté, donc le tas managé fuit. »
• « Le tas GC est stable, donc il n'y a pas de fuite. »
• « La latence/temps d'image moyen est sous budget, donc les queues sont saines. »
• « L'utilisation du GPU est élevée, donc le shader X est le goulot d'étranglement. »
• « Le fil de rendu est occupé, donc le GPU est occupé. »
• « Une capture d'image représente le comportement en régime permanent. »
• « Moins d'appels de dessin signifie toujours un rendu plus rapide. »
• « Plus de threads ThreadPool corrigent la famine. »
• « Le code async ne peut pas bloquer. »
• « NativeAOT est automatiquement plus rapide. »
• « Une amélioration de microbenchmark prouve une amélioration de l'application. »
• « Un delta statistiquement détectable est automatiquement significatif pour le produit. »
• « Une seule exécution de benchmark prouve le résultat. »

Notes de bas de page de documentation

Footnotes

1. references/command-reference.md, qui renvoie à la documentation officielle actuelle des outils de diagnostic .NET, BenchmarkDotNet, Xcode Instruments, Windows Performance Toolkit, Linux perf/BCC, PresentMon, RenderDoc et les profileurs GPU des fournisseurs. ↩