wieslawsoltes/Performance-Skill

Ingeniería de Rendimiento .NET

Utiliza esta habilidad al investigar, explicar, corregir, comparar o validar el rendimiento de una aplicación .NET, incluyendo ASP.NET Core, servicios, aplicaciones de consola, Avalonia, WPF, WinUI, MAUI, Skia, WebGPU, motores de juegos/gráficos, NativeAOT y cargas de trabajo de interoperabilidad nativa.

Este repositorio define una habilidad. SKILL.md es el punto de entrada de políticas y enrutamiento; los procedimientos operativos detallados residen en un árbol de referencia jerárquico. Carga solo los índices y capítulos requeridos por la investigación actual, luego expande cuando la evidencia cruza un límite de propiedad.

Reglas no negociables

• Perfila y compara una compilación optimizada, normalmente Release, en la forma de despliegue real.
• Registra el commit y el estado sucio, SDK/entorno de ejecución, SO, arquitectura, hardware, modo de energía, carga de trabajo, versiones de herramientas, anulaciones de entorno y comandos exactos.
• Establece una reproducción determinista antes de cambiar el código.
• Separa el arranque en frío, el primer uso, el estado estable en caliente, la sobrecarga, el drenaje y el apagado.
• Calienta la compilación en capas, shaders, pipelines, cachés y pools a menos que el comportamiento en frío sea el tema.
• Recopila evidencia en cada límite de propiedad relevante: tiempo de ejecución administrado, biblioteca nativa, kernel, planificador, sistema de archivos/red, dependencia, controlador, GPU, compositor y pantalla.
• No infieras la retención administrada solo a partir de RSS.
• No infieras la saturación de GPU solo a partir del alto tiempo de fotograma, el uso de la API de GPU o la utilización.
• No reclames una corrección a partir de un promedio, un trazado, una captura de fotograma, un microbenchmark o la ejecución de benchmark más rápida.
• Conserva los artefactos sin procesar e informa símbolos faltantes, eventos descartados, sobrecarga del generador de perfiles, variación ambiental e incertidumbre.
• Protege secretos y datos personales en volcados, trazados, registros, abarcados SQL, capturas de paquetes y corpus de entrada de benchmark.
• Trata los ejemplos de comandos como sensibles a la versión. Consulta primero la ayuda de la herramienta instalada; anula los ejemplos cuando la sintaxis difiere. Usa references/command-reference.md para reglas de selección verificadas y formas canónicas.¹

Salida de investigación requerida

Informa:

1. Síntoma — impacto observable y objetivo violado.
2. Reproducción — carga de trabajo y entorno deterministas.
3. Recopilación — herramientas exactas, comandos, duración y rutas de artefactos.
4. Evidencia — contadores, trazados, capturas, volcados, distribuciones de benchmark y mediciones.
5. Propiedad — CPU administrada, tiempo de ejecución, CPU nativa, kernel, planificador, E/S, dependencia, memoria, controlador, GPU, compositor o pantalla.
6. Causa dominante — mayor costo respaldado, espera o recurso de crecimiento más rápido.
7. Corrección — cambio de código o configuración más pequeño y de alto apalancamiento.
8. Validación — ejecuciones equivalentes antes/después con métricas de dispersión y cola.
9. Riesgos residuales — cuellos de botella no resueltos y límites de medición.

Nunca reclames una mejora sin evidencia antes/después de una carga de trabajo equivalente.

Enrutador de referencia

Comienza siempre con references/index.md, references/core/index.md y el verificado references/command-reference.md.

Carga índices de dominio adicionales según la pregunta:

• CPU administrada, asignación, GC, JIT, excepciones, ThreadPool, bloqueos, pilas asíncronas, volcados: references/runtime/index.md
• Propiedad de memoria administrada/nativa/VM/mapeada/GPU y análisis de fugas: references/memory/index.md
• Contención, latencia asíncrona, colas, contrapresión, E/S de archivo/red/base de datos, latencia del despachador de la interfaz de usuario: references/latency/index.md
• Arranque en frío, primer fotograma/solicitud, cargador, JIT, ReadyToRun, recorte, archivo único, NativeAOT: references/startup/index.md
• BenchmarkDotNet, benchmarks de micro/componente/macro/carga/saturación, benchmarks asíncronos/concurrencia, comparaciones JIT/AOT, desensamblado, contadores de hardware, estadísticas, puertas de CI: references/benchmarking/index.md
• Producción, contenedores, puertos de diagnóstico, dotnet-monitor, recopilación activada, Kubernetes, seguridad de artefactos: references/production/index.md
• UI/renderizado/GPU/WebGPU/Metal/D3D/Vulkan/OpenGL/shader/sincronización/presentación: references/gpu/index.md

Carga cada referencia de plataforma relevante a través de references/platforms/index.md. Una investigación de un solo host generalmente necesita un documento de plataforma; las comparaciones multiplataforma y los escenarios remotos/cliente-servidor pueden requerir varios.

No cargues todos los documentos por defecto. Selecciona el conjunto mínimo que responda a la hipótesis actual, pero no te detengas en un límite de propiedad solo porque se requiera otra guía.

Secuencia de clasificación rápida

1. Compila y ejecuta la configuración equivalente a producción.
2. Define las fases de la carga de trabajo, las métricas de éxito y una regla de parada.
3. Registra los contadores de System.Runtime más la CPU del proceso y la memoria total.
4. Captura evidencia de CPU/tiempo de ejecución administrados con dotnet-trace cuando la propiedad administrada sea plausible.
5. Captura pilas repetidas cuando se sospeche progreso, inanición o bloqueo.
6. Si el costo total no se explica, recopila el trazado de CPU/planificador/E/S/memoria nativa de la plataforma.
7. Para memoria, compara bytes vivos administrados, compromiso de GC, privado/RSS/PSS, asignaciones nativas, asignaciones, asignaciones gráficas y residencia de GPU.
8. Para renderizado, correlaciona marcadores de aplicación, envío de CPU, marcas de tiempo de GPU, captura nativa de GPU, presentación, compositor y sincronización de pantalla.
9. Para solicitudes de benchmark, elige la metodología de micro, componente, macro, carga o saturación antes de seleccionar BenchmarkDotNet u otro arnés.
10. Para incidentes solo de producción, usa recopilación limitada o activada y registra las restricciones de cgroup/host.
11. Implementa solo después de que la evidencia respalde la causa dominante.
12. Repite la carga de trabajo idéntica y publica los valores mediana, dispersión, cola y artefactos sin procesar.

Pruebas de propiedad

• CPU de proceso alta con pilas administradas activas: trabajo de aplicación/JIT/tiempo de ejecución.
• CPU de proceso alta por debajo de P/Invoke: biblioteca nativa, asignador, API de gráficos o CPU del controlador.
• CPU baja con pilas bloqueadas repetidas: sincronización, E/S, planificador, cola o dependencia externa.
• Cola de ThreadPool en aumento con CPU baja y pilas bloqueadas: inanición o sincronización-sobre-asíncrono.
• Bytes vivos administrados estables con privado/RSS en crecimiento: montón nativo, asignaciones, montones de código, fragmentación, recursos gráficos o cachés del SO.
• Gráfico administrado vivo en crecimiento después de puntos de recolección completa equivalentes: retención administrada o caché intencionalmente ilimitada.
• Fotograma de CPU largo con marcas de tiempo de GPU cortas: límite de CPU de aplicación/hilo de renderizado/controlador.
• Envío de CPU corto con marcas de tiempo de GPU largas: límite de ejecución de GPU.
• CPU y GPU completan temprano pero la presentación es tarde: swapchain, compositor, vsync, inanición de drawable o ritmo de pantalla.
• Brechas de GPU inactivas entre envíos dependientes: inanición de CPU, sincronización excesiva, serialización o almacenamiento en búfer insuficiente.
• Latencia alta con tiempo en CPU bajo: espera fuera de CPU, cola, dependencia, limitación o retraso del planificador.
• El inicio mejora pero la primera acción empeora: el trabajo se difirió en lugar de eliminarse.
• El benchmark mejora pero la métrica del producto no: el experimento omitió la ruta crítica, usó la distribución de entrada incorrecta u optimizó una operación no dominante.

Procedimiento operativo del agente

• Inspecciona la compilación del repositorio, el despliegue, los diagnósticos, los proyectos de benchmark, los corpus de entrada, el CI y las convenciones de artefactos.
• Crea artifacts/performance/<issue-or-timestamp>/ o el equivalente del repositorio.
• Agrega un controlador de carga de trabajo determinista y marcadores estables cuando falten.
• Almacena comandos, metadatos de entorno, versiones de analizadores/herramientas y enlaces de referencia oficiales junto a los artefactos.
• Analiza primero los costos inclusivos, luego los costos exclusivos, los llamados subrutinas, las esperas, las colas, la sincronización y la propiedad.
• Modifica el código solo después de que la causa dominante esté respaldada.
• Agrega un benchmark, un presupuesto de regresión, un marcador de telemetría, una receta de trazado o un invariante de tiempo de vida que prevenga la recurrencia.
• Mantén los artefactos grandes de trazado, captura, volcado y benchmark fuera de Git a menos que la política del repositorio los almacene explícitamente.
• Valida las rutas de fallo, cancelación, sobrecarga, limpieza, pérdida de dispositivo y apagado, no solo la ruta feliz.

Conclusiones inválidas a rechazar

• “La CPU es alta, por lo tanto el método X es lento” sin pilas.
• “El RSS creció, por lo tanto el montón administrado tiene fugas.”
• “El montón de GC es estable, por lo tanto no hay fuga.”
• “La latencia/tiempo de fotograma promedio está dentro del presupuesto, por lo tanto las colas están saludables.”
• “La utilización de GPU es alta, por lo tanto el shader X es el cuello de botella.”
• “Una captura de fotograma representa el comportamiento de estado estable.”
• “Menos llamadas de dibujo siempre significa renderizado más rápido.”
• “Más hilos de ThreadPool corrigen la inanición.”
• “El código asíncrono no puede bloquear.”
• “NativeAOT es automáticamente más rápido.”
• “Una mejora de microbenchmark demuestra una mejora de aplicación.”
• “Un delta estadísticamente detectable es automáticamente significativo para el producto.”
• “Una ejecución de benchmark demuestra el resultado.”

Notas al pie de documentación

Footnotes

1. references/command-reference.md, que enlaza a la documentación oficial actual de las herramientas de diagnóstico .NET, BenchmarkDotNet, Xcode Instruments, Windows Performance Toolkit, Linux perf/BCC, PresentMon, RenderDoc y los generadores de perfiles de GPU de proveedores. ↩