Notas prácticas: Depuración de Serverless Apache Spark con Gemini y MCP

Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: depurar Serverless Apache Spark utilizando Gemini con MCP. Se centra en pasos operativos, verificaciones explícitas y código que se puede incorporar a un repositorio sin tener que adivinar su propósito. En la etapa de visión general, se deben definir las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad en lugar de un proceso complicado.

Los límites de la IA sin contexto

Al trabajar en la etapa de “Límites del contexto cero”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Registre el ID de la solicitud, el ID del modelo y la latencia en cada llamada. Sin ese registro, los errores intermitentes del proveedor parecen bugs de la aplicación.

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'

Aportando contexto a su terminal con Google Antigravity CLI

Al trabajar en el proceso de integrar el contexto a tu entorno, anota primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestos los cambios posteriores en el código. Registra los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Lleva un registro del ID de la solicitud, el ID del modelo y la latencia en cada llamada. Sin ese historial, los errores intermitentes del proveedor parecen bugs de la aplicación.

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"

Depuración de infraestructura completa con el servidor Spark MCP

Al realizar la depuración de toda la infraestructura con la etapa correspondiente, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos confidenciales y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Registre el ID de la solicitud, el ID del modelo y la latencia en cada llamada. Sin ese registro, los errores intermitentes del proveedor parecen ser defectos de la aplicación. Al realizar la depuración de toda la infraestructura con la etapa correspondiente, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Prefiera unidades pequeñas y probables a scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complejo y entrelazado.

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"

Codificación de planes de juego con habilidades de agente

La etapa de codificación de planes de juego con agentes funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Fije el intérprete y el archivo de bloqueo de dependencias antes de enseñar el bucle. La diferencia entre usar una computadora portátil y los entornos de integración continua es la causa más común de fallos silenciosos en las demostraciones de 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

Resolución de problemas basada en la web con Gemini en Cloud Logging

La resolución de problemas basada en la web con la fase Gemini funciona mejor cuando se trata como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Fije el intérprete y el archivo de bloqueo de dependencias antes de explicar los bucles. La diferencia entre el portátil y los entornos CI es la causa más común de fallos silenciosos en las demostraciones de API.

Resumen

La etapa de Resumen funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Fije el intérprete y el archivo de bloqueo de dependencias antes de explicar el bucle. La diferencia entre la computadora portátil y los entornos de integración continua es la causa más común de fallos silenciosos en las demostraciones de API. La etapa de Resumen funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado.

Lista de verificación operativa

La etapa de lista de verificación operativa funciona mejor cuando se trata como una métrica cuantificable. Consiga un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance.

Documente tanto la ruta óptima como la ruta de recuperación. Los intentos repetidos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes posteriores.

Fije el intérprete y el archivo de bloqueo de dependencias antes de explicar el bucle. La discrepancia entre la computadora portátil y los entornos de integración continua es la causa más común de fallos silenciosos en las demostraciones de API.

Autentique en la pasarela y vuelva a autorizarlo en el plano de datos. Un token de portador por sí solo no constituye un límite entre entornos distintos.

Escriba un manual breve: cómo rotar claves, cómo vaciar la cola y cómo revertir la última inserción.

Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad temprana del costo evita facturas inesperadas cuando la ruta pasa de una demostración a entornos compartidos.

Antes de promocionar el stack, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos de reversión. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de secretos. Prefiera una fiabilidad sólida a demostraciones ingeniosas pero puntuales.

Nota por lotes para 3af041a23886: mantenga las claves del proveedor fuera del repositorio, establezca un límite máximo para tokens por sesión y almacene las transcripciones junto a los fixtures de evaluación para que los cambios posteriores en el modelo sigan siendo comparables.