Notes pratiques : Débogage de Serverless Apache Spark à l’aide de Gemini et MCP

Ce guide reconstitue le parcours allant des matières premières à un système fonctionnel pour : le débogage de Serverless Apache Spark à l’aide de Gemini et de MCP. L’accent est mis sur des étapes opérationnelles, des vérifications explicites, ainsi que du code que vous pouvez intégrer directement dans un dépôt sans devoir deviner son intention. Pour l’étape d’aperçu, définissez les entrées, le responsable de l’étape et les critères d’achèvement avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un pipeline embrouillé.

Les limites de l’IA sans contexte

Lorsque vous travaillez sur l’étape des limites du contexte zéro, notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez les terminaisons partielles silencieuses. Enregistrez l’ID de la demande, l’ID du modèle et le temps de latence à chaque appel. Sans ce suivi, les erreurs intermittentes du fournisseur ressemblent à des bugs de l’application.

py4j.protocol.Py4JJavaError: An error occurred while calling o80.load.
org.apache.spark.SparkException: Job aborted due to stage failure.
Traceback (most recent call last):
  File "spark_job.py", line 26, in main
    df_with_status = df.withColunm("status", lit("active"))
AttributeError: 'DataFrame' object has no attribute 'withColunm'

Fournir du contexte à votre terminal avec Google Antigravity CLI

Lorsque vous travaillez sur l’intégration du contexte dans votre environnement de développement, notez d’abord les exigences : données requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le système passe de l’environnement de démonstration à des environnements partagés. Journalisez l’ID de la requête, l’ID du modèle et le temps de latence pour chaque appel. Sans ce suivi, les erreurs intermittentes du fournisseur sont prises pour des bugs de l’application.

export GOOGLE_CLOUD_PROJECT="$PROJECT_ID"

mkdir -p ~/.gemini/antigravity-cli
cat << 'EOF' | tee ~/.gemini/antigravity-cli/settings.json ~/.gemini/jetski/cli/settings.json ~/.gemini/antigravity/settings.json ~/.gemini/settings.json
{
  "toolPermission": "always-proceed",
  "permissions": {
    "allow": [
      "read_file(*)",
      "write_file(*)",
      "mcp(*)"
    ]
  }
}
EOF

agy -p "examine spark_job.py, fix the DataFrame method typo, and save the file"

Débogage complet de l’infrastructure avec le serveur Spark MCP

Lors du débogage de l’infrastructure complète avec l’environnement de test, notez d’abord les conditions requises : les entrées nécessaires, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans avoir à lire l’ensemble du système. Enregistrez l’ID de la requête, l’ID du modèle et le temps de réponse pour chaque appel. Sans ces traces, les erreurs intermittentes du fournisseur sont prises pour des bugs de l’application. Lors du débogage de l’infrastructure complète avec l’environnement de test, notez d’abord les conditions requises : les entrées nécessaires, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une responsabilité précise plutôt qu’un processus embrouillé.

mkdir -p ~/.gemini/config
cat << EOF | tee ~/.gemini/config/mcp_config.json
{
  "mcpServers": {
    "spark": {
      "serverUrl": "https://dataproc-${REGION}.googleapis.com/mcp"
    }
  }
}
EOF

agy -p "inspect my latest failed Spark batch via MCP, identify the root cause, and fix spark_job.py so it succeeds"

Codification des livres de procédures avec les compétences des agents

La phase de codification des livres de procédures avec les agents fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemple réussi, un cas d’échec ainsi que la note de réversion avant d’élargir le périmètre. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définites des critères de succès et refusez toute complétion partielle silencieuse. Fixez l’interpréteur et le fichier de verrouillage des dépendances avant d’enseigner la boucle. Les changements entre l’ordinateur portable et l’environnement CI constituent la cause la plus fréquente de dysfonctionnements silencieux dans les démos API.

mkdir -p .agents/skills/spark-troubleshooter
cat << 'EOF' > .agents/skills/spark-troubleshooter/SKILL.md
---
name: spark-troubleshooter
description: Diagnoses failed Apache Spark batches on Managed Service for Apache Spark, inspects live batch logs via the Spark MCP server, and recommends resolution commands. Use when troubleshooting Spark job failures.
---

# Spark Troubleshooter Skill

This skill diagnoses failed Apache Spark batches on Managed Service for Apache Spark and offers rapid solutions.

## Instructions
1. Verify local syntax: Locate the PySpark script in the current directory and check for compilation or syntax issues.
2. Fetch live batch state: Call the Spark MCP server tool list_batches and inspect the status of the most recent batch.
3. Check JVM and PySpark logs: Look for standard Spark exceptions, such as FileNotFoundException, AnalysisException, or out-of-memory errors in the batch logs.
4. Recommend action:
    * If a Cloud Storage path is invalid, recommend the exact gcloud storage buckets create command or update the script path.
    * If the job fails due to configuration, generate the correct gcloud dataproc batches submit command with the appropriate parameters.
    * If a syntax error is detected, fix the code in-place.
    * For other errors, recommend a fix.
EOF

agy -p "Diagnose why my last Spark batch failed and recommend a fix"

[Spark Troubleshooter] Running diagnostic playbook...
- Local Syntax: OK (spark_job.py has valid python syntax)
- Spark Batch Status: FAILED (batch-928f1)
- Log Exception: java.io.FileNotFoundException for gs://my-missing-bucket/input.csv

Recommendation:
The bucket gs://my-missing-bucket does not exist. Run this command to create it:

  gcloud storage buckets create gs://my-missing-bucket --location=$REGION

Once created, submit the batch again with:

  gcloud dataproc batches submit pyspark spark_job.py \
      --region=$REGION \
      --deps-bucket=gs://$BUCKET_NAME

Résolution de problèmes en ligne avec Gemini dans Cloud Logging

La résolution de problèmes en ligne avec la phase Gemini fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration à des environnements partagés. Fixez l’interpréteur et le fichier de verrouillage des dépendances avant d’enseigner la boucle. Les différences entre l’ordinateur portable et les environnements CI constituent la cause la plus fréquente de dysfonctionnement silencieux dans les démonstrations API.

Résumé

La phase de résumé fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et une note de réversion avant d’élargir le périmètre. Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Fixez l’interpréteur ainsi que le fichier de verrouillage des dépendances avant d’enseigner la boucle. Les différences entre l’ordinateur portable et l’environnement CI sont la cause la plus fréquente d’échecs silencieux dans les démos API. La phase de résumé fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et une note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité et non un processus embrouillé.

Liste de contrôle opérationnelle

La phase de liste de contrôle opérationnel fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre.

Dokumentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure.

Fixez l’interpréteur et le fichier de verrouillage des dépendances avant d’enseigner la boucle. Les différences entre l’ordinateur portable et les environnements CI sont la cause la plus fréquente de dysfonctionnement silencieux lors des démonstrations API.

Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un simple token porteur ne constitue pas une frontière entre les tenants.

Rédigez un petit manuel opérationnel : comment rotationner les clés, comment vider la file d’attente, comment réversionner la dernière ingestion.

Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le parcours passe de la démonstration aux environnements partagés.

Au préalable de promouvoir le stack, figez les versions, conservez une transcription « or » pour le chemin critique, et confirmez les étapes de rollback. Les environnements partagés nécessitent des limites de débit, des vérifications de location, ainsi qu’un responsable clair pour la rotation des secrets. Préférez une fiabilité solide à des démonstrations brillantes mais ponctuelles.

Note de batch pour 3af041a23886 : gardez les clés du fournisseur hors du repo, fixez un plafond pour les tokens par session, et stockez les transcriptions à côté des fichiers de test afin que les remplacements ultérieurs de modèles restent comparables.