spark-optimization

Visión general de la skill spark-optimization

Para qué sirve spark-optimization

La skill spark-optimization es una guía especializada para diagnosticar y mejorar el rendimiento de jobs de Apache Spark. Encaja mejor cuando un pipeline ya funciona a nivel funcional, pero corre demasiado lento, hace mucho spill a disco, genera demasiado shuffle, sufre skew o se vuelve costoso al escalar. En lugar de dar consejos genéricos del tipo “haz que Spark vaya más rápido”, organiza la optimización alrededor del modelo de ejecución: jobs, stages, tasks, particiones, memoria y comportamiento del shuffle.

Quién debería usar esta skill spark-optimization

Esta skill encaja bien para data engineers, analytics engineers, equipos de plataforma y usuarios de agentes que necesitan ayuda práctica con ajuste de rendimiento en Spark SQL o PySpark. Es especialmente útil si puedes aportar algo de contexto sobre la carga de trabajo, como patrones de joins, tamaño de los datos, número de particiones, configuración de executors o síntomas observados en la Spark UI. Si eres principiante, también puede ayudarte, pero funciona mucho mejor cuando se acompaña de detalles concretos del job y no de una petición en blanco.

El trabajo real que resuelve

La mayoría de los usuarios no intenta “optimizar Spark” en abstracto. Lo que quiere responder son preguntas como:

• ¿Por qué esta stage de joins es mucho más lenta que el resto?
• ¿Por qué los executors hacen spill o terminan fallando con OOM?
• ¿Por qué este pipeline se volvió más lento después de crecer el volumen de datos?
• ¿Debería usar repartition, cache, broadcast o cambiar la configuración de los executors?
• ¿Cómo reduzco el coste de shuffle sin cambiar la lógica de negocio?

La skill spark-optimization aporta valor porque plantea estos casos como problemas de rendimiento diagnosticables, no solo como cuestiones de estilo de código.

Qué la hace diferente de un prompt genérico

Un prompt genérico para un modelo suele listar a la vez todos los consejos habituales de tuning en Spark. La spark-optimization skill está mejor orientada a un flujo de trabajo más acotado: primero entender el comportamiento de ejecución y luego elegir la palanca correcta. Sus diferenciales más claros son el énfasis en la estrategia de particionado, la reducción de shuffle, el ajuste de memoria y el modelo de ejecución de Spark que explica por qué un cambio debería ayudar.

Cómo usar la skill spark-optimization

Contexto de instalación de spark-optimization

Esta skill está en el repositorio wshobson/agents, en:

plugins/data-engineering/skills/spark-optimization

Si tu runner de skills admite instalaciones directas desde GitHub, un patrón habitual es:

npx skills add https://github.com/wshobson/agents --skill spark-optimization

Si tu entorno usa otro instalador, añade la skill desde ese repositorio y selecciona el slug spark-optimization. La evidencia del repositorio solo muestra SKILL.md, así que conviene esperar una guía centrada en documentación y no respaldada por scripts auxiliares ni archivos de referencia.

Lee primero este archivo

Empieza por:

• plugins/data-engineering/skills/spark-optimization/SKILL.md

Como esta skill no muestra scripts, reglas ni referencias de apoyo, gran parte de su valor está en leer con atención el framework principal de optimización. No esperes automatización que inspeccione por ti la Spark UI o el clúster; necesitas aportar los datos reales de ejecución.

Qué información necesita la skill para funcionar bien

La calidad de uso de spark-optimization depende mucho del nivel de detalle que proporciones. Entre las entradas más útiles están:

• API de Spark utilizada: PySpark DataFrame, Spark SQL, Scala Spark, streaming, batch
• Tamaño de datos: número de filas, número de archivos, tamaño de particiones, patrón de crecimiento
• Forma del clúster: memoria de executor, cores, número de executors, comportamiento del autoscaling
• Síntomas: tasks con skew, shuffle read alto, spills, OOMs, stragglers, pausas de GC
• Patrón de consulta: joins, agregaciones, UDFs, window functions, repartitioning
• Formato de almacenamiento: Parquet, Delta, Iceberg, CSV, JSON
• Observaciones de la Spark UI: IDs de stages lentas, tamaño de shuffle, distribución de tasks, tamaño de entrada
• Configuración actual: spark.sql.shuffle.partitions, umbrales de broadcast, serializer

Sin esa información, el modelo tenderá a volver a sugerencias genéricas.

Convierte un objetivo difuso en un prompt sólido

Prompt débil:

Optimize my Spark job.

Prompt más sólido:

Use the spark-optimization skill to diagnose a slow PySpark batch job. It reads 1.2 TB of Parquet, joins a 1.2 TB fact table with a 20 MB dimension table and a 40 GB history table, then aggregates by customer and day. The slowest stage shows high shuffle read and a few tasks run 10x longer than others. Cluster: 20 executors, 8 cores each, 32 GB memory each. Current spark.sql.shuffle.partitions=200. Suggest likely bottlenecks, code-level fixes, and config changes in priority order, with tradeoffs.

Ese prompt le da a la skill evidencia suficiente para razonar sobre broadcast joins, skew, tamaño de particiones y presión de shuffle.

Un flujo de trabajo práctico con spark-optimization

Un buen flujo de trabajo es:

1. Describe la carga de trabajo y el síntoma.
2. Comparte las características de la stage lenta vistas en la Spark UI.
3. Pide una priorización de cuellos de botella, no solo consejos aleatorios de tuning.
4. Solicita cambios por capas:
   • cambios de query/código
   • cambios de particionado
   • cambios de estrategia de join
   • cambios de memoria/configuración
5. Aplica primero la corrección pequeña con mayor confianza.
6. Vuelve a ejecutar y compara el comportamiento a nivel de stage.

Esto mantiene la spark-optimization guide anclada en resultados medibles en lugar de caer en tuning por imitación.

En qué es más fuerte la skill

El texto del repositorio se centra claramente en estas áreas:

• estrategia de particionado
• decisiones de caching
• optimización de shuffle
• ajuste de memoria
• escalado de pipelines de Spark
• reducción de skew de datos

En la práctica, eso significa que la skill ayuda más en trabajo de rendimiento batch donde la estructura de stages y el movimiento de datos son los principales factores de coste.

Qué pedir de forma explícita

Pídele a la skill salidas que sean fáciles de llevar a la práctica, por ejemplo:

• una tabla de hipótesis de cuellos de botella
• cambios de configuración recomendados con su efecto esperado
• puntos probables de skew y comprobaciones para validarlos
• si un broadcast join es apropiado o no
• si repartition o coalesce es más conveniente
• recomendaciones de cache o persist con justificación
• anti-patrones en tus transformaciones

Esto es mucho mejor que pedir una lista genérica de “best practices”.

Temas respaldados por el repositorio en los que conviene centrarse

Según la fuente visible, las mejores áreas para invocar en los prompts son:

• modelo de ejecución de Spark
• factores clave de rendimiento
• minimización de shuffle
• manejo de skew de datos
• decisiones de serialización
• reducción de presión de memoria
• ajuste correcto del tamaño de particiones

Esos son los conceptos sobre los que la skill está estructurada explícitamente, así que al nombrarlos es más probable obtener una respuesta alineada.

Plantilla práctica de prompt de spark-optimization para Performance Optimization

Usa un prompt como este:

Use the spark-optimization skill for Performance Optimization. Analyze this Spark job for shuffle, skew, memory, and partition issues. Here is the job summary: [pipeline description]. Here are the slow stages and Spark UI symptoms: [details]. Here is current cluster config: [details]. Here is a simplified code excerpt: [code]. Recommend the top 3 changes by expected impact, explain why each helps in Spark’s execution model, and note any tradeoffs or validation steps.

Esa formulación suele producir una salida más útil para tomar decisiones que un simple “improve performance”.

Preguntas frecuentes sobre la skill spark-optimization

¿Es útil spark-optimization sin datos de Spark UI?

Sí, pero los resultados son menos fiables. La skill aún puede razonar a partir de la forma del código, los tamaños de joins, el layout de archivos y la configuración del clúster. Aun así, si quieres recomendaciones sólidas sobre skew, puntos calientes de shuffle o presión de memoria, la evidencia de la Spark UI mejora materialmente la respuesta.

¿Está pensada esta skill spark-optimization para principiantes?

Sí, siempre que ya conozcas los conceptos básicos de Spark. La skill explica la optimización a través de jobs, stages, tasks, particiones y comportamiento del shuffle, lo que ayuda a usuarios intermedios a subir de nivel rápido. Los principiantes absolutos probablemente necesiten antes una introducción básica a Spark para que las recomendaciones les resulten realmente accionables.

¿Cuándo no debería usar spark-optimization?

No uses spark-optimization como herramienta principal si el problema en realidad es:

• lógica de negocio incorrecta
• mala calidad de datos de origen
• fallos de orquestación
• caídas o incidencias en la capa de almacenamiento
• cuellos de botella no relacionados con Spark y fuera del motor

Tampoco encaja bien si no puedes compartir ningún dato real de ejecución y solo quieres un checklist genérico de tuning.

¿En qué se diferencia del consejo habitual sobre Spark?

Los prompts corrientes suelen generar consejos amplios como “usa más cache”, “aumenta las particiones” o “usa broadcast joins”. La decisión de instalar spark-optimization merece la pena si quieres un flujo centrado en diagnosticar cuál de esas palancas importa primero y por qué, usando conceptos de ejecución de Spark en vez de consejos desconectados.

¿Sustituye la skill a las pruebas de benchmark?

No. Mejora la calidad de tus hipótesis y de los cambios recomendados, pero aun así necesitas probar antes y después. La optimización de Spark depende mucho de la carga de trabajo, y algunos cambios que ayudan a una stage pueden perjudicar otra.

Cómo mejorar la skill spark-optimization

Da síntomas, no solo objetivos

La forma más rápida de mejorar el uso de spark-optimization es sustituir objetivos abstractos por síntomas concretos:

• “stage 14 has 2 tasks running 12 minutes while others finish in 40 seconds”
• “shuffle read is 600 GB after a groupBy”
• “executors spill to disk during sortMergeJoin”
• “job got slower after increasing daily input from 200 GB to 900 GB”

Estas pistas permiten a la skill mapear el problema directamente a causas de skew, particionado, memoria o shuffle.

Incluye la forma del código que genera el cuello de botella

No necesitas pegar todo tu proyecto. Un fragmento pequeño que muestre:

• joins
• agregaciones
• llamadas a repartition
• uso de cache o persist
• UDFs de Python
• lecturas y escrituras de archivos

suele ser suficiente. Los problemas de rendimiento en Spark a menudo se ven en la forma de las transformaciones, no solo en la configuración.

Pide recomendaciones priorizadas

Un modo de fallo habitual es recibir diez sugerencias sin ningún orden. Pídele a la skill que priorice las correcciones según:

1. impacto esperado en el rendimiento
2. esfuerzo de implementación
3. riesgo operativo

Eso obliga a producir una respuesta más precisa y facilita la adopción.

Solicita pasos de validación después de cada recomendación

Un uso sólido de la spark-optimization guide incluye verificación. Pídele a la skill que explique cómo confirmar que cada corrección funcionó, por ejemplo:

• reducción de shuffle read/write
• duraciones de tasks más uniformes
• menos spills
• menor tiempo de GC
• menos stages
• mejor equilibrio en las particiones de entrada

Esto evita el “tuning por folklore”.

Indica restricciones para que el consejo sea realista

Menciona restricciones como:

• no se puede aumentar el tamaño del clúster
• no se puede reescribir en Scala
• hay que mantener el formato de tabla actual
• el objetivo de latencia es fijo
• la memoria disponible para broadcast join es limitada
• en este sprint solo se permiten cambios de configuración

La skill dará recomendaciones mucho más utilizables cuando sepa qué opciones quedan fuera de límites.

Itera después de la primera salida de spark-optimization

Después de la primera pasada, vuelve con:

• qué cambió
• qué mejoró
• qué empeoró
• observaciones actualizadas de la Spark UI

Aquí es donde la skill se vuelve realmente útil. La optimización de Spark es iterativa; el mejor siguiente paso suele depender de los efectos secundarios del cambio anterior.

Vigila los fallos más comunes

Los resultados de baja calidad más habituales ocurren cuando los usuarios:

• piden optimización sin detalles de la carga de trabajo
• ignoran el skew y se centran solo en la memoria de executor
• hacen over-cache de datasets grandes sin evidencia de reutilización
• cambian el número de particiones a ciegas
• tratan cualquier join como candidato a broadcast
• optimizan la configuración antes de corregir transformaciones costosas

Si quieres mejores resultados, haz que la skill razone a partir de evidencia, no de preferencias genéricas.