spark-optimization

Visão geral da skill spark-optimization

Para que serve a spark-optimization

A skill spark-optimization é um guia focado em diagnosticar e melhorar a performance de jobs em Apache Spark. Ela é mais útil quando o pipeline já funciona do ponto de vista funcional, mas roda devagar demais, faz muito spill em disco, gera shuffle em excesso, sofre com skew ou fica caro demais em escala. Em vez de trazer dicas genéricas de “como deixar o Spark mais rápido”, ela organiza a otimização em torno do modelo de execução: jobs, stages, tasks, partições, memória e comportamento de shuffle.

Quem deve usar esta skill spark-optimization

Esta skill é indicada para data engineers, analytics engineers, times de plataforma e usuários de agentes que precisam de ajuda prática com tuning de performance em Spark SQL ou PySpark. Ela é especialmente útil quando você consegue fornecer algum contexto sobre a carga, como padrões de join, volume de dados, número de partições, configurações de executor ou sintomas vistos na Spark UI. Se você estiver começando, ela ainda ajuda, mas funciona melhor quando vem acompanhada de detalhes concretos do job, e não de um pedido em branco.

O trabalho real que ela resolve

A maioria dos usuários não está tentando “otimizar Spark” de forma abstrata. Na prática, quer responder perguntas como:

• Por que este stage de join está muito mais lento do que os outros?
• Por que os executors estão fazendo spill ou morrendo com OOM?
• Por que este pipeline ficou mais lento depois que o volume de dados aumentou?
• Devo usar repartition, cache, broadcast ou mudar as configurações dos executors?
• Como reduzir o custo de shuffle sem mexer na lógica de negócio?

A skill spark-optimization é valiosa porque trata isso como problemas de performance diagnosticáveis, e não apenas como questões de estilo de código.

O que diferencia esta skill de um prompt genérico

Um prompt genérico para modelo costuma despejar de uma vez todas as dicas comuns de tuning em Spark. A spark-optimization skill é mais adequada para um fluxo mais objetivo: primeiro entender o comportamento de execução, depois escolher a alavanca certa. Seus maiores diferenciais são a ênfase em estratégia de particionamento, redução de shuffle, tuning de memória e no modelo de execução do Spark para explicar por que uma mudança deve ajudar.

Como usar a skill spark-optimization

Contexto de instalação da spark-optimization

Esta skill fica no repositório wshobson/agents, em:

plugins/data-engineering/skills/spark-optimization

Se o seu executor de skills suporta instalação direta via GitHub, um padrão comum é:

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

Se o seu ambiente usa outro instalador, adicione a skill a partir desse repositório e selecione o slug spark-optimization. As evidências no repositório mostram apenas o arquivo SKILL.md, então espere uma orientação baseada em documentação, não algo apoiado por scripts auxiliares ou arquivos de referência.

Leia este arquivo primeiro

Comece por:

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

Como esta skill não tem scripts, regras ou referências de suporte visíveis, boa parte do valor está em ler com atenção o framework principal de otimização. Não espere automação que inspecione sua Spark UI ou o cluster por você; você precisa trazer os fatos de runtime.

Que tipo de entrada a skill precisa para funcionar bem

A qualidade do uso de spark-optimization depende muito do nível de detalhe que você fornece. Entradas úteis incluem:

• API Spark usada: PySpark DataFrame, Spark SQL, Scala Spark, streaming, batch
• Tamanho dos dados: contagem de linhas, número de arquivos, tamanho das partições, padrão de crescimento
• Formato do cluster: memória dos executors, cores, número de executors, comportamento de autoscaling
• Sintomas: tasks com skew, shuffle read alto, spills, OOMs, stragglers, pausas de GC
• Padrão da query: joins, agregações, UDFs, window functions, repartitioning
• Formato de armazenamento: Parquet, Delta, Iceberg, CSV, JSON
• Observações da Spark UI: IDs dos stages lentos, tamanho do shuffle, distribuição das tasks, tamanho de input
• Configuração atual: spark.sql.shuffle.partitions, thresholds de broadcast, serializer

Sem isso, o modelo tende a voltar para sugestões genéricas.

Como transformar um objetivo vago em um prompt forte

Prompt fraco:

Optimize my Spark job.

Prompt melhor:

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.

Esse prompt dá à skill evidência suficiente para raciocinar sobre broadcast joins, skew, sizing de partições e pressão de shuffle.

Um fluxo prático com spark-optimization

Um bom fluxo é:

1. Descreva a carga e o sintoma.
2. Compartilhe as características do stage lento vistas na Spark UI.
3. Peça um ranking dos gargalos, não apenas dicas soltas de tuning.
4. Solicite mudanças em camadas:
   • mudanças na query/código
   • mudanças de particionamento
   • mudanças na estratégia de join
   • mudanças de memória/configuração
5. Aplique primeiro a correção menor e com maior confiança.
6. Rode de novo e compare o comportamento em nível de stage.

Isso mantém o spark-optimization guide ancorado em resultados mensuráveis, em vez de tuning por imitação.

Onde a skill é mais forte

O texto do repositório deixa claro que ela se concentra nestas áreas:

• estratégia de particionamento
• escolhas de caching
• otimização de shuffle
• tuning de memória
• escala de pipelines Spark
• redução de data skew

Na prática, isso significa que a skill é mais útil em trabalho de performance batch, quando a estrutura dos stages e a movimentação de dados são os principais vetores de custo.

O que pedir explicitamente

Peça que a skill produza saídas fáceis de colocar em prática, como:

• uma tabela de hipóteses de gargalo
• mudanças de configuração recomendadas com efeito esperado
• pontos prováveis de skew e checagens para validar
• se um broadcast join faz sentido ou não
• se repartition ou coalesce é mais apropriado
• recomendações de cache ou persist com justificativa
• anti-patterns nas suas transformações

Isso é muito melhor do que pedir uma “lista de boas práticas” genérica.

Tópicos do repositório em que vale focar

Com base no que está visível na fonte, as melhores áreas para invocar nos prompts são:

• modelo de execução do Spark
• principais fatores de performance
• minimização de shuffle
• tratamento de data skew
• escolhas de serialização
• redução de pressão de memória
• ajuste correto do tamanho das partições

Esses são os conceitos em torno dos quais a skill foi explicitamente estruturada, então você tem mais chance de obter uma resposta alinhada se os nomear no prompt.

Template prático de prompt para spark-optimization em Performance Optimization

Use um 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.

Essa formulação costuma gerar uma resposta mais pronta para decisão do que apenas “improve performance”.

FAQ da skill spark-optimization

A spark-optimization é útil sem dados da Spark UI?

Sim, mas os resultados são menos confiáveis. A skill ainda consegue raciocinar a partir do formato do código, tamanhos de joins, layout dos arquivos e configurações do cluster. Porém, se você quer recomendações mais seguras para skew, hotspots de shuffle ou pressão de memória, evidências da Spark UI melhoram bastante a resposta.

Esta skill spark-optimization serve para iniciantes?

Sim, desde que você já conheça os conceitos básicos de Spark. A skill explica otimização por meio de jobs, stages, tasks, partições e comportamento de shuffle, o que ajuda usuários intermediários a evoluir rápido. Iniciantes absolutos talvez ainda precisem de uma introdução básica a Spark antes que as recomendações se tornem realmente acionáveis.

Quando não devo usar spark-optimization?

Não use spark-optimization como sua ferramenta principal se o problema for, na verdade:

• lógica de negócio incorreta
• má qualidade dos dados de origem
• falhas de orquestração
• indisponibilidade na camada de storage
• gargalos fora do engine Spark

Ela também não é uma boa escolha se você não puder compartilhar nenhum fato de runtime e só quiser um checklist genérico de tuning.

Em que ela difere de conselhos comuns sobre Spark?

Prompts comuns costumam gerar conselhos amplos como “use mais cache”, “aumente o número de partições” ou “faça broadcast joins”. A decisão de instalar spark-optimization vale a pena se você quer um fluxo centrado em diagnosticar qual dessas alavancas importa primeiro e por quê, usando conceitos de execução do Spark em vez de dicas desconectadas.

A skill substitui benchmarking?

Não. Ela melhora a qualidade das suas hipóteses e das mudanças recomendadas, mas você ainda precisa testar antes e depois. Otimização em Spark depende muito da carga, e algumas mudanças que ajudam um stage podem piorar outro.

Como melhorar a skill spark-optimization

Forneça sintomas, não apenas objetivos

A forma mais rápida de melhorar o uso de spark-optimization é trocar objetivos abstratos por sintomas específicos:

• “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”

Esses sinais permitem que a skill conecte diretamente o problema a causas de skew, particionamento, memória ou shuffle.

Inclua o formato do código que cria o gargalo

Você não precisa colar o projeto inteiro. Um trecho pequeno mostrando:

• joins
• agregações
• chamadas de repartition
• uso de cache ou persist
• Python UDFs
• leitura e escrita de arquivos

geralmente já basta. Problemas de performance em Spark muitas vezes ficam visíveis pela forma das transformações, não só pela configuração.

Peça recomendações priorizadas

Um modo comum de falha é receber dez sugestões sem nenhuma ordem. Peça que a skill classifique as correções por:

1. impacto esperado na performance
2. esforço de implementação
3. risco operacional

Isso força uma resposta mais precisa e facilita a adoção.

Peça etapas de validação após cada recomendação

Um uso forte do spark-optimization guide inclui verificação. Peça à skill como confirmar que cada correção funcionou, por exemplo:

• redução de shuffle read/write
• duração das tasks mais equilibrada
• menos spills
• menor tempo de GC
• menos stages
• melhor equilíbrio nas partições de entrada

Isso evita “tuning por folclore”.

Informe restrições para que a recomendação seja realista

Mencione restrições como:

• não é possível aumentar o tamanho do cluster
• não dá para reescrever em Scala
• é preciso manter o formato atual das tabelas
• a meta de latência é fixa
• a memória para broadcast join é limitada
• nesta sprint só são permitidas mudanças de configuração

A skill vai dar recomendações muito mais úteis quando souber o que está fora de alcance.

Itere depois da primeira resposta da spark-optimization

Depois da primeira rodada, volte com:

• o que mudou
• o que melhorou
• o que piorou
• observações atualizadas da Spark UI

É aí que a skill passa a ser realmente útil. Otimização em Spark é iterativa; o melhor próximo passo muitas vezes depende dos efeitos colaterais da mudança anterior.

Fique atento aos erros mais comuns

Os resultados de baixa qualidade mais frequentes acontecem quando os usuários:

• pedem otimização sem nenhum detalhe da carga
• ignoram skew e focam só na memória dos executors
• fazem cache excessivo em datasets grandes sem evidência de reutilização
• mudam a quantidade de partições no escuro
• tratam todo join como candidato a broadcast
• tentam otimizar configuração antes de corrigir transformações caras

Se você quer resultados melhores, faça a skill raciocinar a partir de evidências, não de preferências genéricas.