spark-optimization

spark-optimization スキルの概要

spark-optimization の用途

spark-optimization スキルは、Apache Spark ジョブのパフォーマンスを診断し、改善するための実践的なガイドです。すでにパイプライン自体は正しく動いているものの、処理が遅い、spill が多い、shuffle が過大、skew が発生している、あるいはデータ量増加に伴ってコストが急増している、といった場面で特に役立ちます。単に「Spark を速くする方法」を並べるのではなく、jobs、stages、tasks、partitions、memory、shuffle behavior といった実行モデルに沿って最適化を整理しているのが特徴です。

この spark-optimization スキルが向いている人

この spark-optimization スキルは、Spark SQL や PySpark の性能チューニングで実務的な助けが必要な data engineer、analytics engineer、platform team、そしてエージェント利用者に適しています。特に、join パターン、データサイズ、partition 数、executor 設定、Spark UI 上の症状など、ワークロードの文脈をある程度共有できる場合に効果的です。初心者でも使えますが、何も情報がない状態で依頼するより、具体的なジョブ情報と組み合わせたほうがはるかに有用です。

実際に解決したい仕事

多くのユーザーがやりたいのは、抽象的に「Spark を最適化する」ことではありません。実際には、次のような問いに答えたいはずです。

• なぜこの join stage だけ他より極端に遅いのか？
• なぜ executors が spill したり OOM で落ちたりするのか？
• なぜデータ量が増えた後にこの pipeline は急に遅くなったのか？
• repartition、cache、broadcast、executor 設定変更のどれを優先すべきか？
• ビジネスロジックを変えずに shuffle コストを下げるにはどうするか？

spark-optimization スキルの価値は、こうした課題を単なるコードスタイルの話ではなく、診断可能な性能問題として扱える点にあります。

汎用プロンプトと何が違うのか

一般的なモデル向けプロンプトでは、よくある Spark チューニングのヒントが一度に羅列されがちです。一方で spark-optimization skill は、まず実行時の挙動を把握し、そのうえで適切なレバーを選ぶ、という絞られたワークフローに向いています。特に差別化ポイントになるのは、partitioning strategy、shuffle 削減、memory tuning、そして「なぜその変更が効くのか」を説明する Spark の実行モデルへの強いフォーカスです。

spark-optimization スキルの使い方

spark-optimization のインストール前提

このスキルは wshobson/agents リポジトリ内の以下にあります。

plugins/data-engineering/skills/spark-optimization

skill runner が 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 がうまく機能するために必要な入力

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 size、task 分布、input size
• 現在の設定: 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. ランダムな tuning tips ではなく、ボトルネックの優先順位付けを依頼する。
4. 変更提案をレイヤーごとに求める。
   • query/code changes
   • partitioning changes
   • join strategy changes
   • memory/config changes
5. まずは、確度が高く影響の大きい最小変更から試す。
6. 再実行し、stage レベルの挙動を比較する。

こうすると spark-optimization guide を、根拠のないお作法集ではなく、測定可能な結果に基づく改善に結びつけやすくなります。

spark-optimization が特に強い領域

リポジトリの記述を見る限り、主軸は次の領域です。

• partitioning strategy
• caching choices
• shuffle optimization
• memory tuning
• Spark pipeline のスケーリング
• data skew の低減

実務的には、stage 構造やデータ移動が主なコスト要因になる batch 性能改善で、特に力を発揮しやすいスキルです。

明示的に依頼するとよい出力

実際に行動へ移しやすいよう、次のような出力を明示して頼むのがおすすめです。

• ボトルネック仮説の表
• 期待効果付きの推奨 config 変更
• skew が起きそうな箇所とその検証方法
• broadcast join が適切かどうか
• repartition と coalesce のどちらが妥当か
• 根拠付きの cache / persist 推奨
• transformations に潜む anti-patterns

これは、ただ「best practices の一覧をください」と頼むよりずっと有効です。

リポジトリの内容に沿って重点的に聞くべきトピック

見えているソースに基づくと、プロンプトで積極的に触れるべき領域は次のとおりです。

• 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 サイズ、file layout、cluster settings からでも一定の推論は可能です。しかし、skew、shuffle のホットスポット、memory pressure について確度の高い提案が欲しいなら、Spark UI の観測情報があるかどうかで回答の質は大きく変わります。

この spark-optimization スキルは初心者向けか

はい。ただし、Spark の基本概念をある程度わかっていることが前提です。このスキルは jobs、stages、tasks、partitions、shuffle behavior を軸に最適化を説明するため、中級者が理解を一段引き上げるのには非常に向いています。完全な初学者の場合、提案を実際の作業に落とし込むには、先に Spark の基礎を押さえておいたほうがよいかもしれません。

spark-optimization を使うべきでないのはどんなときか

次のような問題が本質である場合、spark-optimization を主な手段にするのは適していません。

• business logic の誤り
• source data quality の悪さ
• orchestration failures
• storage-layer outages
• エンジン外にある non-Spark bottlenecks

また、実行時の事実をほとんど共有できず、一般的な tuning checklist だけが欲しい場合にも相性はよくありません。

普通の Spark アドバイスと何が違うのか

一般的なプロンプトでは、「もっと cache する」「partition を増やす」「broadcast join を使う」といった広めの助言になりがちです。spark-optimization install を検討する価値があるのは、そうしたレバーのうち何を最初に触るべきか、なぜそれが有効なのかを、Spark execution concepts に沿って診断中心で整理したい場合です。単発の tips ではなく、優先順位付きの判断材料が欲しい人向けです。

このスキルは benchmarking の代わりになるか

いいえ。仮説の質や推奨変更の精度は高められますが、前後比較のテストは依然として必要です。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 または persist の使用
• Python UDFs
• file reads and writes

Spark の性能問題は、config だけでなく transformation の形から見えることが少なくありません。

優先順位付きの提案を求める

よくある失敗は、順番のない提案を 10 個並べられて終わることです。次の観点で修正案を順位付けするよう依頼してください。

1. expected performance impact
2. implementation effort
3. operational risk

これによって回答が引き締まり、実際に採用しやすくなります。

各提案のあとに検証手順も求める

強い spark-optimization guide の使い方には、必ず検証が含まれます。各修正について、どう確認すれば効いたと判断できるかも聞いてください。たとえば次のような指標です。

• shuffle read/write の減少
• task duration の均一化
• spill の減少
• GC time の低下
• stage 数の減少
• input partition balance の改善

これにより、「なんとなくの定説で tuning する」状態を避けやすくなります。

制約を伝えて、現実的な助言にする

次のような制約があるなら明示してください。

• cluster size は増やせない
• Scala への書き換えはできない
• 現在の table format を維持する必要がある
• latency target は固定
• broadcast join に使える memory が限られている
• 今 sprint では config changes しか許されない

何が禁止事項なのかがわかっているほど、スキルは実務で使える助言を返しやすくなります。

最初の spark-optimization 出力のあとに反復する

最初の提案を試した後は、次の情報を持って再度相談すると効果的です。

• 何を変えたか
• 何が改善したか
• 何が悪化したか
• 更新後の Spark UI observations

ここからが、このスキルが本当に活きる場面です。Spark 最適化は反復型で進めるものであり、次に打つべき最善手は、前の変更が生んだ副作用に左右されることが少なくありません。

よくある失敗パターンに注意する

回答品質が下がりやすい典型例は次のとおりです。

• ワークロード詳細なしで最適化だけを依頼する
• skew を無視して executor memory だけに注目する
• 再利用根拠がない大規模データを過剰に cache する
• partition 数を当てずっぽうで変える
• すべての join を broadcast 候補だと思い込む
• 高コストな transformations を直す前に config だけをいじる

よりよい結果が欲しいなら、一般論ではなく、観測された事実からスキルに推論させるのが重要です。