spark-sense-ai

AI 에이전트(Claude Desktop, Claude Code, Devin 또는 MCP 호환 클라이언트)에게 Apache Spark 작업을 처리하는 두 가지 기능을 제공하는 MCP(Model Context Protocol) 서버입니다:

• 🔴 diagnose_spark_failure — Spark 작업이 실패한 경우, 실제 오류 로그와 실패한 특정 코드를 바탕으로 근본 원인과 구체적인 해결 방법을 제공합니다.

• 🟢 optimize_spark_performance — Spark 작업이 성공했지만 느리거나 비용이 많이 드는 경우, 근거 기반의 맞춤형 튜닝 권장 사항을 제공합니다.

12년 이상의 실무 Apache Spark 경험을 가진 데이터 엔지니어가, 동일한 디버깅 직관 — "이 오류가 실제로 어떤 파일에 관한 것이며, 왜 그런가" — 을 AI 지원 워크플로우에 적용하기 위해 만들었습니다.

왜 필요한가

Spark 실패는 대개 로그만으로 진단할 수 있습니다. 그러나 200줄짜리 스택 트레이스를 읽고, 대규모 다중 작업 코드베이스에서 해당 오류가 실제로 가리키는 올바른 파일을 찾아내며, 수십 가지 가능한 원인 중 실제 원인이 무엇인지 파악하는 데는 진짜 Spark 경험이 필요합니다. 이 도구는 그 첫 번째 단계를 자동화합니다. 관련된 코드(전체 저장소가 아닌)를 찾아서 로그와 함께 LLM에 전달하고, 검증하고 조치를 취할 수 있는 구조화된 진단 결과를 돌려받습니다.

차별점

샘플 출력

이 샘플 Scala 오류 로그와 해당 프로젝트 파일이 주어지면 diagnose_spark_failure(공급자 구성 시)는 다음을 반환합니다:

ROOT CAUSE:
CustomerHelper.validate() calls .trim() on the "email" field without
checking for null first. Records with a missing email cause a
NullPointerException, which aborts the job after 4 failed task retries.

EVIDENCE:
- Caused by: java.lang.NullPointerException: Cannot invoke "String.trim()"
  because "email" is null
- at com.company.jobs.CustomerHelper$.validate(CustomerHelper.scala:22)
- Source shows: email.trim().nonEmpty with no null check beforehand

SUGGESTED FIX:
def validate(row: Row): Boolean = {
  val email = Option(row.getAs[String]("email"))
  email.exists(_.trim.nonEmpty)
}

CONFIDENCE: High

도구가 자동으로 CustomerHelper.scala(트레이스의 Caused by가 실제로 가리키는 파일)를 가져온 것을 확인할 수 있습니다. 전체 프로젝트나 최상위 엔트리 파일인 CustomerOrderJoin.scala조차 가져오지 않았습니다. 스택 트레이스 파서가 가장 깊은 관련 프레임을 해석했기 때문입니다.

설치

pip install spark-sense-ai

실제로 사용할 기능에 대해서만 추가 패키지를 설치하세요:

pip install spark-sense-ai[aws]         # for EMR source or Bedrock provider
pip install spark-sense-ai[anthropic]   # for provider="anthropic"
pip install spark-sense-ai[openai]      # for provider="openai"
pip install spark-sense-ai[all]         # everything

provider="none" 및 source_type="local" 조합은 추가 패키지가 전혀 필요 없습니다 — 기본 mcp 의존성만 있으면 됩니다.

사용 방법 4가지

AWS 자격 증명은 필요할 때 기존 설정(aws configure, 연결된 IAM 역할, 표준 AWS_* 환경 변수)에서 자동으로 가져옵니다 — 도구 파라미터로 절대 전달되지 않습니다.

설정

Claude Desktop

claude_desktop_config.json을 편집하세요:

{
  "mcpServers": {
    "sparksense": {
      "command": "sparksense-mcp",
      "env": {
        "SPARKSENSE_AWS_REGION": "ap-south-1"
      }
    }
  }
}

Claude Code

claude mcp add sparksense -- sparksense-mcp

Devin

현재 Devin 에이전트 모드(캐스케이드와 Devin Local은 설정 위치가 약간 다릅니다)의 구성 방법은 Devin의 MCP 문서를 참조하세요. 위와 같은 방식으로 sparksense-mcp 명령을 가리키면 됩니다.

사용 예시

"제 Spark 작업이 실패했습니다 — EMR 클러스터 j-ABC123, 단계 s-XYZ789. sparksense로 Bedrock을 사용해 진단해 주세요."

"제 로컬 작업의 로그는 ./logs/error.log, 코드는 ./src에 있습니다 — 실패를 진단해 주세요."

"실패한 것이 jobs/customer_order_join.py라는 것을 알고 있습니다 — sparksense에서 이를 엔트리 포인트로 사용해 주세요."

"sparksense를 사용해 ./logs/job.log의 로그를 가져와 주세요 — 제가 직접 검토하겠습니다." (provider="none" — 도구는 로그만 가져오고, 호출하는 에이전트가 추론을 수행합니다)

"제 작업이 성공했지만 40분이 걸렸습니다. sparksense를 사용해 최적화 기회가 있는지 실행 통계를 확인해 주세요."

도구 참조

diagnose_spark_failure

optimize_spark_performance

위와 동일한 파라미터에 다음이 추가됩니다:

파일 선택 로직 (두 도구 공통)

1. job_entry_point given?
     → use ONLY that file. No auto-extraction.

2. Else, parse the error log for:
     → Python:      File "<path>", line <N>
     → Scala/Java:  at <package>.<Class>.<method>(<Filename>:<N>)
     (handles mixed PySpark traces — Python frames bottoming into JVM
     frames — by scanning for both patterns in the same log)
     → filters out framework/library internals (site-packages, pyspark,
       org.apache.spark, scala.*, java.*, etc.)
     → fetches up to 10 matched files

3. Else, fallback: broad scan of the project folder, capped at 10 files

환경 변수

테스트

git clone https://github.com/YOUR_GITHUB_USERNAME/spark-sense-ai.git
cd spark-sense-ai
pip install -e ".[all]"

# Local source + Anthropic provider, includes Python and Scala samples
export ANTHROPIC_API_KEY="sk-ant-..."
python tests/test_local_anthropic.py

# EMR source + Bedrock provider (needs a real EMR cluster/step)
aws configure
python tests/test_emr_bedrock.py --cluster-id j-XXXXXXX --step-id s-XXXXXXX

두 스크립트 모두 유료 LLM 호출을 하기 전에 먼저 무료이며 API 호출이 없는 기본 점검(provider="none")을 실행합니다.

로드맵

• EMR/Glue 작업 완료 시 Lambda/EventBridge를 통한 자동 트리거

• 세 번째 source_type으로 Databricks 지원

• 구조화된 Spark History Server API 통합

• 파티션 수준 통계를 활용한 데이터 쏠림 감지

라이선스

MIT — LICENSE 참조.