spark-optimization

spark-optimization 스킬 개요

spark-optimization이 쓰이는 상황

spark-optimization 스킬은 Apache Spark 작업의 성능 문제를 진단하고 개선하는 데 초점을 맞춘 가이드입니다. 파이프라인이 기능적으로는 이미 동작하지만 실행이 지나치게 느리거나, spill이 많이 발생하거나, shuffle 비용이 과도하거나, 데이터 skew가 심하거나, 데이터 규모가 커지면서 비용이 급격히 늘어나는 경우에 특히 적합합니다. 단순히 “Spark를 더 빠르게 만드는 법” 같은 일반론을 나열하는 대신, jobs, stages, tasks, partitions, memory, shuffle behavior 같은 실행 모델을 기준으로 최적화를 구조화해 설명합니다.

어떤 사용자가 이 spark-optimization 스킬을 쓰면 좋은가

이 스킬은 Spark SQL 또는 PySpark 성능 튜닝에 대해 실무적인 도움을 원하는 데이터 엔지니어, 애널리틱스 엔지니어, 플랫폼 팀, 에이전트 사용자에게 잘 맞습니다. 특히 join 패턴, 데이터 크기, partition 수, executor 설정, Spark UI에서 보이는 증상 같은 워크로드 맥락을 함께 제공할 수 있을 때 유용성이 크게 높아집니다. 초보자도 사용할 수는 있지만, 막연한 요청만 던질 때보다 실제 작업 정보가 함께 있을 때 훨씬 더 좋은 결과를 얻을 수 있습니다.

사용자가 실제로 해결하려는 일

대부분의 사용자는 추상적으로 “Spark를 최적화”하려는 것이 아닙니다. 실제로는 보통 이런 질문에 답하려는 경우가 많습니다.

• 왜 이 join stage만 유독 다른 stage보다 훨씬 느린가?
• 왜 executors가 spill을 일으키거나 OOM으로 죽는가?
• 왜 데이터 볼륨이 늘어난 뒤 이 파이프라인이 더 느려졌는가?
• repartition, cache, broadcast, executor 설정 변경 중 무엇을 우선해야 하는가?
• 비즈니스 로직은 바꾸지 않고 shuffle 비용을 줄이려면 어떻게 해야 하는가?

spark-optimization 스킬의 가치는 이런 문제를 단순한 코드 스타일 이슈가 아니라, 원인을 진단할 수 있는 성능 문제로 다룬다는 데 있습니다.

일반적인 프롬프트와 다른 점

일반적인 모델 프롬프트는 흔한 Spark 튜닝 팁을 한꺼번에 늘어놓는 경우가 많습니다. 반면 spark-optimization skill은 더 좁고 실무적인 워크플로에 맞춰져 있습니다. 먼저 실행 동작을 이해한 뒤, 그다음에 맞는 레버를 선택하는 방식입니다. 특히 partitioning strategy, shuffle reduction, memory tuning, 그리고 “왜 이 변경이 효과가 있는지”를 설명해 주는 Spark 실행 모델에 중점을 둔다는 점이 가장 큰 차별점입니다.

spark-optimization 스킬 사용 방법

spark-optimization 설치 맥락

이 스킬은 wshobson/agents 저장소의 다음 경로에 있습니다.

plugins/data-engineering/skills/spark-optimization

스킬 러너가 GitHub 직접 설치를 지원한다면 흔히 다음과 같이 설치합니다.

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

사용 중인 환경에서 설치 방식이 다르다면, 해당 저장소에서 스킬을 추가한 뒤 spark-optimization slug를 선택하면 됩니다. 현재 저장소에서 확인되는 근거는 SKILL.md뿐이므로, helper script나 reference file이 포함된 형태라기보다 문서 중심의 가이드라고 보는 편이 맞습니다.

가장 먼저 읽어야 할 파일

다음 파일부터 읽으세요.

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

이 스킬에는 눈에 보이는 보조 스크립트, 규칙 파일, 참조 자료가 없기 때문에, 핵심 가치는 메인 최적화 프레임워크를 꼼꼼히 읽는 데 있습니다. Spark UI나 클러스터를 자동으로 검사해 주는 도구를 기대하면 안 됩니다. 런타임 사실관계는 사용자가 직접 가져와야 합니다.

이 스킬이 잘 작동하려면 어떤 입력이 필요한가

spark-optimization usage의 품질은 사용자가 얼마나 구체적인 정보를 주느냐에 크게 좌우됩니다. 특히 다음 정보가 유용합니다.

• 사용한 Spark API: PySpark DataFrame, Spark SQL, Scala Spark, streaming, batch
• 데이터 크기: row 수, file 수, partition 크기, 증가 패턴
• 클러스터 구성: executor memory, cores, executor 수, autoscaling 동작
• 증상: skewed tasks, 긴 shuffle read, spills, OOMs, stragglers, GC pauses
• 쿼리 패턴: joins, aggregations, UDFs, window functions, repartitioning
• 저장 형식: Parquet, Delta, Iceberg, CSV, JSON
• Spark UI 관찰값: 느린 stage ID, shuffle 크기, task 분포, input 크기
• 현재 설정: spark.sql.shuffle.partitions, broadcast threshold, serializer

이런 정보가 없으면 모델은 결국 일반적인 제안으로 되돌아갈 가능성이 큽니다.

막연한 목표를 강한 프롬프트로 바꾸는 법

약한 프롬프트:

Optimize my Spark job.

더 강한 프롬프트:

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.

이 정도로 써야 스킬이 broadcast join, skew, partition sizing, shuffle pressure 같은 이슈를 근거 있게 추론할 수 있습니다.

실무적인 spark-optimization 워크플로

좋은 워크플로는 보통 다음 순서를 따릅니다.

1. 워크로드와 증상을 설명한다.
2. Spark UI에서 느린 stage의 특성을 공유한다.
3. 무작위 튜닝 팁이 아니라 bottleneck 우선순위 정리를 요청한다.
4. 변경안을 계층별로 요청한다.
   • query/code changes
   • partitioning changes
   • join strategy changes
   • memory/config changes
5. 가장 작은 고신뢰 수정부터 먼저 적용한다.
6. 다시 실행한 뒤 stage 단위 동작을 비교한다.

이렇게 해야 spark-optimization guide를 근거 없는 감 튜닝이 아니라, 측정 가능한 결과 중심으로 활용할 수 있습니다.

이 스킬이 특히 강한 영역

저장소 텍스트를 보면 이 스킬은 분명히 다음 영역을 중심에 두고 있습니다.

• partitioning strategy
• caching choices
• shuffle optimization
• memory tuning
• Spark 파이프라인 확장성
• data skew 감소

실무적으로 보면, stage 구조와 데이터 이동이 주요 비용 요인인 batch 성능 개선 작업에서 가장 도움이 됩니다.

명시적으로 요청하면 좋은 출력

스킬에게 바로 실행에 옮길 수 있는 형태의 결과를 요청하세요. 예를 들면 다음과 같습니다.

• bottleneck 가설 표
• 기대 효과를 포함한 권장 config 변경안
• 발생 가능성이 높은 skew 지점과 검증 방법
• broadcast join이 적절한지 여부
• repartition과 coalesce 중 무엇이 더 적합한지
• 근거가 포함된 cache 또는 persist 권장안
• 현재 transformation의 anti-pattern

이런 식의 요청이 막연한 “best practices list”보다 훨씬 낫습니다.

저장소 근거상 집중해야 할 주제

눈에 보이는 소스를 기준으로 하면, 프롬프트에서 특히 잘 활용할 수 있는 주제는 다음입니다.

• Spark execution model
• key performance factors
• shuffle minimization
• data skew handling
• serialization choices
• memory pressure reduction
• partition right-sizing

이 스킬은 바로 이런 개념을 축으로 설계되어 있기 때문에, 프롬프트에서도 이 용어들을 직접 언급하면 더 잘 맞는 출력을 받을 가능성이 높습니다.

Performance Optimization을 위한 실전 spark-optimization 프롬프트 템플릿

다음과 같은 프롬프트를 사용할 수 있습니다.

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.

이 표현은 단순히 “improve performance”라고 말하는 것보다, 실제 의사결정에 바로 쓸 수 있는 답변을 끌어내는 데 더 유리합니다.

spark-optimization 스킬 FAQ

Spark UI 데이터 없이도 spark-optimization이 유용한가

그렇습니다. 다만 결과의 신뢰도는 떨어집니다. 코드 구조, join 크기, 파일 레이아웃, 클러스터 설정만으로도 어느 정도 추론은 가능합니다. 하지만 skew, shuffle hotspot, memory pressure에 대해 자신 있게 추천을 받으려면 Spark UI 근거가 답변 품질을 크게 높여줍니다.

이 spark-optimization 스킬은 초보자용인가

그렇습니다. 다만 기본적인 Spark 개념은 이미 알고 있다는 전제가 있으면 좋습니다. 이 스킬은 jobs, stages, tasks, partitions, shuffle behavior를 기준으로 최적화를 설명하기 때문에, 중급 사용자에게 특히 빠른 성장을 돕습니다. 완전 초심자라면, 제안이 바로 실행 가능하게 느껴지기 전에 기본 Spark 입문 지식이 먼저 필요할 수 있습니다.

어떤 경우에는 spark-optimization을 쓰지 말아야 하나

문제의 본질이 사실 다음 중 하나라면 spark-optimization을 주력 도구로 쓰는 것은 적합하지 않습니다.

• 잘못된 비즈니스 로직
• 나쁜 원천 데이터 품질
• 오케스트레이션 실패
• 스토리지 계층 장애
• 엔진 바깥의 non-Spark 병목

또한 런타임 사실을 거의 공유할 수 없고, 그저 일반적인 튜닝 체크리스트만 원한다면 이 스킬과의 궁합이 좋지 않습니다.

일반적인 Spark 조언과 무엇이 다른가

보통의 프롬프트는 “cache를 더 써라”, “partition 수를 늘려라”, “broadcast join을 써라” 같은 넓은 조언으로 끝나는 경우가 많습니다. spark-optimization install을 고려할 가치가 있는 이유는, 이런 선택지들 중 무엇이 먼저 중요한지와 그 이유를 Spark 실행 개념에 근거해 진단하는 워크플로를 제공하기 때문입니다. 단편적인 팁 모음보다 훨씬 실전적입니다.

이 스킬이 벤치마킹을 대체하나

아닙니다. 이 스킬은 가설의 질과 추천 변경안의 방향을 개선해 주지만, 적용 전후 테스트는 여전히 필요합니다. Spark 최적화는 워크로드 의존성이 매우 크고, 한 stage에 도움이 되는 변경이 다른 stage에는 오히려 악영향을 줄 수도 있습니다.

spark-optimization 스킬을 더 잘 활용하는 법

목표만 말하지 말고 증상을 주기

spark-optimization usage를 가장 빠르게 개선하는 방법은 추상적인 목표를 구체적인 증상으로 바꾸는 것입니다.

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

이런 단서가 있어야 스킬이 skew, partitioning, memory, shuffle 원인에 직접 연결해서 분석할 수 있습니다.

병목을 만드는 코드 형태를 함께 보여주기

프로젝트 전체를 붙여 넣을 필요는 없습니다. 다음이 보이는 작은 코드 발췌만 있어도 보통 충분합니다.

• joins
• aggregations
• repartition calls
• cache or persist usage
• Python UDFs
• file reads and writes

Spark 성능 문제는 config만이 아니라 transformation의 형태에서 드러나는 경우가 많습니다.

우선순위가 매겨진 추천을 요청하기

흔한 실패 패턴 중 하나는 순서 없는 제안 10개를 받는 것입니다. 스킬에게 다음 기준으로 수정안을 우선순위화해 달라고 요청하세요.

1. 기대 성능 영향
2. 구현 노력
3. 운영 리스크

이렇게 해야 출력이 더 날카로워지고, 실제 도입도 쉬워집니다.

각 추천 뒤에 검증 단계도 요청하기

좋은 spark-optimization guide 활용에는 검증이 반드시 포함됩니다. 각 수정이 실제로 효과가 있었는지 어떻게 확인할지까지 물어보세요. 예를 들면 다음과 같습니다.

• shuffle read/write 감소
• task duration의 균등화
• spill 감소
• GC time 감소
• stage 수 감소
• input partition balance 개선

이렇게 해야 “전해 내려오는 튜닝 상식”에 기대는 일을 피할 수 있습니다.

제약 조건을 알려줘야 조언이 현실적이 된다

다음과 같은 제약이 있다면 반드시 함께 적어 주세요.

• 클러스터 크기를 늘릴 수 없음
• Scala로 다시 작성할 수 없음
• 현재 table format을 유지해야 함
• latency target이 고정돼 있음
• broadcast join에 사용할 메모리가 제한적임
• 이번 스프린트에서는 config 변경만 가능함

무엇이 불가능한지 알아야, 스킬도 실제로 쓸 수 있는 방향의 조언을 줄 수 있습니다.

첫 번째 spark-optimization 결과 뒤에는 꼭 한 번 더 반복하기

첫 번째 분석 뒤에는 다음 정보를 들고 다시 오세요.

• 무엇을 바꿨는지
• 무엇이 개선됐는지
• 무엇이 더 나빠졌는지
• 업데이트된 Spark UI 관찰값

바로 이 지점에서 스킬의 실용성이 크게 높아집니다. Spark 최적화는 반복적인 작업이고, 다음 최선의 조치는 이전 변경의 부작용에 따라 달라지는 경우가 많습니다.

흔한 오작동 패턴을 경계하기

품질 낮은 결과가 나오는 가장 흔한 경우는 다음과 같습니다.

• 워크로드 세부 정보 없이 최적화만 요청함
• skew는 무시하고 executor memory만 봄
• 재사용 근거 없이 큰 데이터셋을 과도하게 cache함
• partition 수를 근거 없이 바꿈
• 모든 join을 broadcast 후보로 취급함
• 비싼 transformation을 고치기 전에 config부터 만짐

더 나은 결과를 원한다면, 스킬이 일반적인 취향이 아니라 실제 근거를 바탕으로 추론하도록 만들어야 합니다.