Explorar guías rápidas · Microsoft Fabric
Depurar pipelines de Fabric
Diagnostica los fallos de pipelines de Microsoft Fabric aislando la actividad que falló, separando los errores transitorios de los deterministas, validando parámetros e identidades, y usando reintentos, registro y re-ejecuciones controladas de forma segura.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Empieza por la ejecución del pipeline y luego baja hasta la actividad
- 2. Encuentra el primer fallo real, no cada fallo aguas abajo
- 3. Registra las entradas de la actividad antes de cambiar nada
- 4. Parametriza los notebooks de forma deliberada
- 5. Valida los parámetros de fecha antes de usarlos
- 6. Valida que el origen exista antes de hacer trabajo costoso
- 7. Añade un contexto de ejecución explícito al notebook
- 8. Añade un ID de ejecución del pipeline o un ID de lote a las escrituras
- 9. Haz explícitos los errores del notebook
- 10. Distingue los errores transitorios de los deterministas
- 11. Configura los reintentos de las actividades de forma selectiva
- 12. Usa reintentos condicionales donde estén disponibles
- 13. No reintentes automáticamente los fallos de autenticación
- 14. Confirma con qué identidad se ejecuta el notebook
- 15. Compara la ejecución interactiva del notebook con la ejecución desde el pipeline
- 16. Valida el Lakehouse predeterminado
- 17. Depura el arranque de la actividad Notebook por separado del código del notebook
- 18. Revisa los fallos de stages/tareas de Spark para los errores del notebook
- 19. Vigila los conflictos de concurrencia de Delta
- 20. Comprueba si la ejecución fallida escribió datos parcialmente
- 21. Diseña actividades idempotentes
- 22. Comprueba si hay lotes duplicados antes de volver a ejecutar
- 23. Usa una tabla de control para el estado operativo
- 24. Evita anexiones a ciegas concurrentes al mismo registro de ejecución sin un diseño adecuado
- 25. Haz fallar el pipeline cuando falle la validación de negocio
- 26. No codifiques de forma fija rutas específicas de un entorno
- 27. Depura los fallos de la actividad Copy por capas
- 28. Valida el número de filas de origen y destino cuando esté disponible
- 29. Depura por separado los fallos de la actividad de procedimiento almacenado
- 30. Define el tiempo de espera de la actividad de forma deliberada
- 31. Diferencia un tiempo de espera agotado de una regresión de rendimiento
- 32. Usa las condiciones de dependencia de forma intencionada
- 33. Conserva el error original al añadir gestión de fallos
- 34. Pasa a las alertas solo el contexto de error necesario
- 35. Usa Secure Input / Secure Output para las actividades sensibles
- 36. Usa el monitoreo del workspace para analizar fallos recurrentes
- 37. Consulta las ejecuciones de actividades de pipeline fallidas
- 38. Resume los fallos por actividad
- 39. Haz seguimiento de las regresiones de duración
- 40. Vuelve a ejecutar el alcance seguro más pequeño
- Qué significa el resultado
- Qué revisar
- El fallo ocurre inmediatamente
- El fallo ocurre tras una ejecución larga
- Solo falla la ejecución desde el pipeline
- El fallo desaparece tras un reintento
- La re-ejecución tiene éxito pero los datos se duplican
- Varias actividades aguas abajo fallan o se omiten
- Notas de producción
- La mayoría de los reintentos de actividades deben apuntar a fallos transitorios
- El contexto de ejecución de la actividad Notebook importa
- Las ejecuciones de pipeline no son una única transacción distribuida
- El registro debe ser duradero
- Workspace Monitoring puede centralizar el historial de los pipelines
- Las alertas deben ser accionables
- Los reintentos consumen tiempo y capacidad
- Errores comunes
- 1. Volver a ejecutar todo el pipeline inmediatamente
- 2. Reintentar cada fallo
- 3. Ocultar las excepciones del notebook
- 4. Depurar las actividades omitidas
- 5. Suponer que la identidad interactiva es igual a la identidad del pipeline
- 6. Aumentar el tiempo de espera en lugar de investigar la regresión
- 7. Anexar a ciegas al volver a ejecutar
- 8. Añadir reintentos antes de garantizar la seguridad de las escrituras
- 9. Registrar secretos para depurar
- 10. Tomar una re-ejecución exitosa como prueba de que el problema está resuelto
- Siguiente paso
- Para profundizar
Problema
Un pipeline de Microsoft Fabric falla, se queda detenido, reintenta una y otra vez o produce un resultado incorrecto.
El fallo puede venir de distintas capas:
- orquestación del pipeline
- actividad Notebook
- actividad Copy
- actividad de procedimiento almacenado
- actividad Dataflow
- credenciales o identidad del workspace
- parámetros
- arranque o ejecución de Spark
- conectividad con el origen
- conflictos de escritura en el destino
- deriva del esquema
- lógica de dependencias aguas abajo
El objetivo es identificar qué capa falló y si el fallo es transitorio o determinista antes de volver a ejecutar nada.
Un flujo de depuración seguro para producción debe responder:
- ¿Qué actividad falló primero?
- ¿Qué recibió esa actividad como entrada?
- ¿Con qué identidad se ejecutó?
- ¿El error fue transitorio?
- ¿La actividad que falló escribió datos parcialmente?
- ¿Es seguro volver a ejecutar la actividad?
- ¿El reintento debe ser automático o requerir intervención?
Respuesta rápida
Sigue esta secuencia:
1. Abre la ejecución del pipeline que falló
2. Identifica la primera actividad que falló
3. Lee el error de la actividad, no solo el estado del pipeline
4. Registra el ID de ejecución, el nombre de la actividad, la hora de inicio/fin y los parámetros de entrada
5. Clasifica el error:
- transitorio
- autenticación/permisos
- parámetro/configuración
- datos/esquema
- notebook/Spark
- destino/conflicto de escritura
6. Comprueba si la actividad confirmó datos parcialmente
7. Corrige la causa raíz
8. Vuelve a ejecutar solo si la actividad es idempotente o recuperable de forma segura
9. Añade reintentos específicos solo para los fallos transitorios
10. Persiste metadatos operativos para que el próximo incidente sea más fácil
No empieces con:
"Vuelve a ejecutar todo el pipeline."
hasta que sepas si las actividades anteriores ya escribieron datos.
Código / comandos
1. Empieza por la ejecución del pipeline y luego baja hasta la actividad
En Fabric, usa el historial de ejecuciones del pipeline / la vista Output (salida) para identificar:
Ejecución del pipeline
↓
Actividad que falló
↓
Entrada de la actividad
↓
Salida/error de la actividad
Registra como mínimo:
nombre del pipeline
ID de ejecución del pipeline
nombre de la actividad
tipo de actividad
hora de inicio
hora de fin
duración
estado
código de error
mensaje de error
El estado a nivel de pipeline te dice que algo falló.
La salida de la actividad normalmente te dice qué falló.
2. Encuentra el primer fallo real, no cada fallo aguas abajo
Un pipeline puede mostrar varias actividades fallidas u omitidas porque falló una sola dependencia aguas arriba.
Ejemplo:
Copy_Raw_Data Succeeded
Transform_Notebook Failed
Publish_Warehouse Skipped
Send_Success_Email Skipped
El objetivo de la depuración es:
Transform_Notebook
no las actividades omitidas aguas abajo.
Identifica siempre el primer fallo de la cadena de dependencias.
3. Registra las entradas de la actividad antes de cambiar nada
Para una actividad que falló, registra los valores efectivos que se le pasaron.
Ejemplos:
source_path
target_table
start_date
end_date
environment
workspace
lakehouse
batch_id
run_id
Los errores de parámetros a menudo parecen problemas de datos o de conectividad.
Un notebook puede ser correcto pero recibir:
2026/13/01
en lugar de:
2026-10-01
o apuntar al Lakehouse equivocado.
4. Parametriza los notebooks de forma deliberada
Una actividad Notebook de Fabric puede pasar parámetros a un notebook.
Dentro del notebook, define los parámetros explícitamente en la celda de parámetros designada.
Ejemplo:
source_table = "bronze_sales"
target_table = "silver_sales"
run_date = "2026-10-04"
Después valídalos al principio:
required = {
"source_table": source_table,
"target_table": target_table,
"run_date": run_date,
}
for name, value in required.items():
if value in (None, ""):
raise ValueError(
f"Missing required parameter: {name}"
)
Falla pronto con un mensaje claro en lugar de permitir un fallo impreciso más adelante.
5. Valida los parámetros de fecha antes de usarlos
from datetime import datetime
try:
parsed_run_date = datetime.strptime(
run_date,
"%Y-%m-%d",
).date()
except ValueError as exc:
raise ValueError(
f"run_date must be YYYY-MM-DD; got {run_date!r}"
) from exc
No permitas que fechas mal formadas fallen más tarde dentro de filtros de Spark o rutas de archivos.
6. Valida que el origen exista antes de hacer trabajo costoso
Ejemplo con tablas de Spark:
if not spark.catalog.tableExists(source_table):
raise RuntimeError(
f"Source table does not exist: {source_table}"
)
Para cargas de trabajo basadas en archivos, valida la ruta de origen o la partición esperada antes de iniciar una transformación grande.
Fallar rápido ofrece una señal operativa más clara.
7. Añade un contexto de ejecución explícito al notebook
Al principio de un notebook de producción:
print(
{
"source_table": source_table,
"target_table": target_table,
"run_date": run_date,
}
)
No imprimas:
- contraseñas
- tokens de acceso
- cadenas de conexión que contengan secretos
- contenidos confidenciales
Los registros operativos deben ayudar a depurar sin filtrar credenciales.
8. Añade un ID de ejecución del pipeline o un ID de lote a las escrituras
Si el pipeline pasa un identificador de ejecución:
from pyspark.sql import functions as F
output = (
output
.withColumn(
"pipeline_run_id",
F.lit(pipeline_run_id),
)
.withColumn(
"ingested_at_utc",
F.current_timestamp(),
)
)
Esto ayuda a responder:
¿Qué ejecución del pipeline escribió esta fila?
También ayuda a detectar lotes reprocesados y re-ejecuciones parciales.
9. Haz explícitos los errores del notebook
Mal:
try:
do_work()
except Exception:
print("something failed")
Esto puede ocultarle el fallo al orquestador.
Mejor:
try:
do_work()
except Exception as exc:
print(
f"Notebook failed: {type(exc).__name__}: {exc}"
)
raise
Deja que la actividad Notebook falle cuando la transformación realmente falló.
Un pipeline que informa éxito con datos incompletos es peor que un fallo visible.
10. Distingue los errores transitorios de los deterministas
Ejemplos transitorios:
falta de disponibilidad temporal del servicio
limitación de solicitudes (throttling) HTTP 429
tiempo de espera de red agotado
fallo temporal del endpoint
contención temporal de recursos
Ejemplos deterministas:
nombre de columna incorrecto
SQL no válido
tabla inexistente
permiso denegado
parámetro incorrecto
discrepancia de esquema
claves de negocio duplicadas
credenciales no válidas
Reintenta los problemas transitorios.
Corrige los problemas deterministas.
No uses los reintentos para ocultar una lógica defectuosa.
11. Configura los reintentos de las actividades de forma selectiva
La mayoría de las actividades de pipeline de Fabric Data Factory admiten reintentos.
Usa la configuración de reintentos a nivel de actividad para los fallos que pueden recuperarse automáticamente.
Conceptualmente:
Activity
→ General
→ Enable retries
→ Retry count
→ Retry interval
Para problemas transitorios breves, un retardo fijo puede ser apropiado.
Para la limitación de solicitudes (throttling) o servicios externos inestables, un retardo creciente puede reducir la presión repetida.
No configures un número alto de reintentos de forma predeterminada.
12. Usa reintentos condicionales donde estén disponibles
Fabric admite condiciones de reintento para determinados tipos de actividad.
Los criterios típicos incluyen:
código de error
mensaje de error
tipo de fallo
Ejemplo de política:
Reintentar:
HTTP 429
error temporal del sistema
tiempo de espera de conexión agotado
No reintentar:
fallo de autenticación
esquema incorrecto
SQL no válido
objeto de origen inexistente
La capacidad de reintento condicional depende de la funcionalidad y de la actividad, así que verifica que la actividad que usas la admita.
13. No reintentes automáticamente los fallos de autenticación
Ejemplo:
401
403
credencial no válida
permiso denegado
Los reintentos repetidos normalmente no corrigen:
- un secreto caducado
- un rol que falta
- un permiso incorrecto en el workspace
- una identidad equivocada
Deja de reintentar y corrige el acceso.
14. Confirma con qué identidad se ejecuta el notebook
El contexto de ejecución del notebook importa.
Según cómo se desencadene la ejecución, la identidad puede ser distinta.
Para los notebooks desencadenados por un pipeline, valida el contexto efectivo de autenticación/seguridad del pipeline antes de suponer que el notebook se ejecuta como su propietario.
Cuando un notebook funciona de forma interactiva pero falla en un pipeline, revisa:
identidad
acceso al workspace
acceso al Lakehouse
permisos sobre datos externos
permisos de API
antes de cambiar el código del notebook.
15. Compara la ejecución interactiva del notebook con la ejecución desde el pipeline
Si:
El notebook funciona de forma interactiva
La actividad Notebook del pipeline falla
compara:
identidad
parámetros
Lakehouse predeterminado
Environment
configuración de Spark
modo de sesión
workspace
credenciales del origen
El código puede ser idéntico mientras que el contexto de ejecución no lo es.
16. Valida el Lakehouse predeterminado
Un notebook puede fallar si espera tablas de un Lakehouse pero la actividad/sesión usa otro.
Al iniciar el notebook, registra o valida el espacio de nombres de tablas esperado.
Prefiere referencias explícitas a tablas/rutas en cargas de trabajo críticas que abarcan varios Lakehouses cuando la ambigüedad sería peligrosa.
No supongas que el Lakehouse adjunto al notebook en modo interactivo coincide exactamente con el contexto de ejecución del pipeline.
17. Depura el arranque de la actividad Notebook por separado del código del notebook
Una actividad Notebook puede fallar antes de que empiece cualquier trabajo útil de Spark.
Separa:
obtención de la sesión
arranque de Spark
inicialización del entorno
configuración de bibliotecas
ejecución del código del notebook
Si el fallo ocurre antes de la primera línea de registro esperada, investiga la configuración de la sesión, el entorno o la plataforma en lugar de la transformación.
18. Revisa los fallos de stages/tareas de Spark para los errores del notebook
Si la actividad Notebook falló durante el trabajo de Spark, inspecciona:
stage fallido
tarea fallida
error del executor
error de shuffle
conflicto de Delta
falta de memoria
excepción al analizar los datos
El error del pipeline suele ser solo el envoltorio externo.
Los detalles del job de Spark contienen la causa de la ejecución distribuida.
19. Vigila los conflictos de concurrencia de Delta
Escenario de ejemplo:
Notebook A → MERGE en la tabla de destino
Notebook B → MERGE en la misma tabla de destino
al mismo tiempo.
Los síntomas pueden incluir errores de conflicto de transacciones concurrentes/escritura.
No lo resuelvas aumentando indefinidamente los reintentos del pipeline.
Considera:
añadir a staging
→ serializar/conciliar los MERGE
o aislar los procesos de escritura por partición/dominio de negocio cuando sea seguro.
20. Comprueba si la ejecución fallida escribió datos parcialmente
Antes de volver a ejecutar, pregúntate:
¿Tuvieron éxito las actividades anteriores?
¿Confirmó algo esta actividad?
¿El destino ya contenía el lote?
En las escrituras Delta, una transacción Delta fallida no confirma parcialmente esa transacción, pero las actividades anteriores que terminaron con éxito pueden haber confirmado datos ya.
El pipeline en su conjunto no es una transacción global.
21. Diseña actividades idempotentes
Una re-ejecución segura debe producir el mismo resultado lógico.
Ejemplos:
MERGE por clave de negocio
reemplazar una partición conocida
append con protección contra el reprocesamiento de lotes
escribir en staging y después promover
Patrón de re-ejecución inseguro:
append a ciegas
cuando el mismo lote de origen puede procesarse dos veces.
22. Comprueba si hay lotes duplicados antes de volver a ejecutar
Si persistes metadatos de los lotes:
existing = (
spark.table("pipeline_execution_log")
.filter(
F.col("batch_id") == batch_id
)
)
if existing.count() > 0:
raise RuntimeError(
f"Batch already processed: {batch_id}"
)
En un diseño real de producción, evita las comprobaciones costosas con count() cuando exista una búsqueda por clave o un diseño con tabla de control más eficiente.
Lo importante es hacer explícito el estado de reprocesamiento.
23. Usa una tabla de control para el estado operativo
Esquema lógico de ejemplo:
pipeline_execution_log
----------------------
pipeline_name
pipeline_run_id
batch_id
activity_name
status
started_at
completed_at
rows_read
rows_written
error_type
error_message
Úsala para responder:
¿Ya se procesó este lote?
¿Dónde se detuvo la última ejecución?
¿Cuántas filas se escribieron?
¿Qué actividad falló?
Evita almacenar secretos o enormes trazas de pila directamente en las tablas operativas.
24. Evita anexiones a ciegas concurrentes al mismo registro de ejecución sin un diseño adecuado
Un registro de ejecución puede convertirse en sí mismo en un punto caliente de concurrencia.
Si varios notebooks escriben simultáneamente, diseña la capa de registro para la concurrencia.
Enfoques posibles:
solo append por actividad
clave única de ejecución/actividad
merge/upsert controlado
servicio/tabla de registro centralizado
No dejes que la observabilidad se convierta en el punto de fallo.
25. Haz fallar el pipeline cuando falle la validación de negocio
Ejemplo:
bad_rows = (
output
.filter(
F.col("merchant_id").isNull()
)
)
bad_count = bad_rows.count()
if bad_count > 0:
raise RuntimeError(
f"Validation failed: {bad_count} rows have null merchant_id"
)
Un job de Spark técnicamente correcto puede producir aun así datos de negocio no válidos.
El éxito operativo debe incluir controles de calidad cuando sea necesario.
26. No codifiques de forma fija rutas específicas de un entorno
Mal:
source = "abfss://prod@..."
dentro de cada notebook.
Prefiere parámetros o configuración por entorno:
source_path = source_path_param
Esto reduce:
- el acceso accidental a producción
- la deriva entre despliegues
- los cambios de código entre entornos
27. Depura los fallos de la actividad Copy por capas
Para la actividad Copy, clasifica el error:
Conexión con el origen
Consulta de origen
Autenticación
Red/conectividad
Asignación de esquema
Serialización
Conexión con el sink
Restricción/escritura en el sink
Rendimiento/limitación (throttling)
No trates cada fallo de Copy como un problema de conectividad.
Comprueba si la lectura del origen realmente tuvo éxito antes de investigar el destino (sink).
28. Valida el número de filas de origen y destino cuando esté disponible
Registra:
filas leídas
filas escritas
filas omitidas/rechazadas
Si:
filas leídas = 10,000,000
filas escritas = 0
probablemente el origen no es el problema.
Si:
filas leídas = 0
céntrate primero aguas arriba.
29. Depura por separado los fallos de la actividad de procedimiento almacenado
Una actividad Stored Procedure puede fallar por:
conexión/autenticación
procedimiento inexistente
parámetro no válido
excepción de SQL
transacción/interbloqueo
tiempo de espera agotado
validación de negocio
Registra el número/mensaje de error de SQL cuando esté disponible.
No reintentes automáticamente los errores de lógica.
Para interbloqueos (deadlocks) o fallos de conexión transitorios, los reintentos selectivos pueden ser razonables.
30. Define el tiempo de espera de la actividad de forma deliberada
Las actividades de Fabric admiten la configuración de un tiempo de espera (timeout).
Un tiempo de espera debe representar:
la duración máxima durante la que la actividad puede consumir recursos antes de considerarse anómala
No configures un tiempo de espera extremadamente alto solo para evitar fallos.
Un tiempo de espera puede revelar:
- llamadas externas atascadas
- jobs de Spark descontrolados
- SQL bloqueado
- aumentos de volumen inesperados
Usa la duración histórica para elegir un límite operativo justificable.
31. Diferencia un tiempo de espera agotado de una regresión de rendimiento
Si un notebook normalmente tarda:
20 minutos
y ahora alcanza un:
tiempo de espera de 2 horas
no te limites a aumentar el tiempo de espera.
Investiga:
volumen de entrada
plan de Spark
shuffle
sesgo (skew)
capacidad
latencia del origen
concurrencia
Aumentar el tiempo de espera puede ocultar una regresión real.
32. Usa las condiciones de dependencia de forma intencionada
Lógica de orquestación típica:
On success
On failure
On completion
Diseña explícitamente las rutas de fallo.
Ejemplo:
Transform
├─ éxito → Publish
└─ fallo → Log Failure
No dejes que una actividad de diagnóstico/notificación convierta accidentalmente el resultado lógico del pipeline en éxito.
33. Conserva el error original al añadir gestión de fallos
La lógica de gestión de fallos debe registrar el error o alertar sobre él, pero la actividad de negocio original que falló debe seguir siendo visible.
Evita patrones en los que:
La actividad falla
→ el registro tiene éxito
→ el pipeline parece haber tenido éxito
salvo que ese sea intencionadamente el contrato.
34. Pasa a las alertas solo el contexto de error necesario
Campos útiles para las alertas:
nombre del pipeline
ID de ejecución
actividad
entorno
tipo de fallo
código de error
mensaje de error breve
enlace/contexto de supervisión
Evita enviar:
- credenciales
- tokens
- contenidos sensibles completos
- muestras de datos grandes
35. Usa Secure Input / Secure Output para las actividades sensibles
La configuración de las actividades de Fabric permite ocultar las entradas/salidas sensibles en los registros de ejecución.
Usa los controles de registro seguro cuando el contenido de las actividades pueda incluir valores confidenciales.
Esto reduce el nivel de detalle para la observabilidad, así que combínalo con identificadores operativos seguros.
36. Usa el monitoreo del workspace para analizar fallos recurrentes
Cuando Fabric Workspace Monitoring está habilitado, los registros de pipelines y actividades pueden analizarse de forma centralizada.
Los eventos a nivel de pipeline pueden consultarse desde el eventhouse de monitoreo.
Patrón KQL de ejemplo:
ItemJobEventLogs
| where ItemKind == "Pipeline"
| summarize Runs = count() by JobStatus
Usa los registros a nivel de actividad para una investigación más profunda cuando estén disponibles.
El monitoreo centralizado es más útil que abrir manualmente ejecuciones individuales cuando los fallos se repiten.
37. Consulta las ejecuciones de actividades de pipeline fallidas
Un patrón práctico a nivel de actividad es:
FabricDataPipelinesActivityRunsLogs
| where ActivityStatus == "Failed"
| project
PipelineName,
PipelineRunId,
ActivityName,
ActivityType,
ActivityStartTime,
ActivityEndTime,
FailureType
| order by ActivityStartTime desc
La disponibilidad de columnas puede variar según el esquema/versión del monitoreo, así que inspecciona el esquema real de la tabla en tu workspace.
Úsalo para identificar:
- reincidentes
- agrupaciones de fallos
- tipos de actividad que fallan
- patrones temporales
38. Resume los fallos por actividad
FabricDataPipelinesActivityRunsLogs
| where ActivityStatus == "Failed"
| summarize Failures = count()
by PipelineName, ActivityName, ActivityType
| order by Failures desc
Esto convierte el historial operativo en priorización.
Un pipeline que falló una vez por una interrupción temporal es distinto de una actividad que falla todos los días.
39. Haz seguimiento de las regresiones de duración
Concepto de ejemplo:
FabricDataPipelinesActivityRunsLogs
| where ActivityStatus == "Succeeded"
| summarize
AvgDurationMs = avg(DurationMs),
MaxDurationMs = max(DurationMs)
by PipelineName, ActivityName
Usa los nombres de campo reales disponibles en tu tabla de monitoreo.
No inventes umbrales de rendimiento universales.
Compara cada actividad con su propia línea base histórica.
40. Vuelve a ejecutar el alcance seguro más pequeño
Después de corregir la causa raíz, prefiere:
volver a ejecutar la actividad fallida / la rama fallida
cuando la plataforma/el flujo de trabajo lo admita de forma segura y las salidas aguas arriba sean válidas.
De lo contrario, vuelve a ejecutar todo el pipeline solo cuando:
- las actividades anteriores sean idempotentes
- se eviten los duplicados
- se entienda el estado parcial
El alcance de re-ejecución más seguro depende del diseño del pipeline.
Qué significa el resultado
| Señal | Dirección probable |
|---|---|
| El notebook funciona de forma interactiva, falla en el pipeline | Identidad / parámetros / entorno / contexto del Lakehouse |
| HTTP 429 / fallo temporal del servicio | Candidato a reintento por fallo transitorio |
| 401 / 403 | Autenticación o permisos |
| Columna no válida / discrepancia de esquema | Problema determinista de datos o de código |
| Fallo de un stage de Spark | Problema de ejecución distribuida del notebook |
| Conflicto de Delta | Problema de escritura / merge concurrentes |
| Tiempo de espera agotado | Problema de rendimiento, bloqueo, dependencia o recursos |
| Aguas arriba tuvo éxito, aguas abajo se omitió | Comportamiento de las dependencias, no varios fallos independientes |
| La re-ejecución crea duplicados | Diseño de escritura no idempotente |
| Fallo repetido de la misma actividad | Problema estructural, no un incidente aleatorio |
Qué revisar
El fallo ocurre inmediatamente
Causas probables:
- parámetro no válido
- objeto inexistente
- permisos
- configuración
- ruta incorrecta
- sintaxis
Revisa la configuración antes que el rendimiento.
El fallo ocurre tras una ejecución larga
Causas probables:
- fallo de un stage de Spark
- tiempo de espera agotado
- conflicto de escritura
- presión de memoria
- inestabilidad del origen/destino
- caso límite de gran volumen
Inspecciona la telemetría de ejecución.
Solo falla la ejecución desde el pipeline
Compara el contexto de ejecución del pipeline con la ejecución interactiva.
En especial:
- identidad
- parámetros
- Lakehouse predeterminado
- workspace
- Environment
- permisos externos
El fallo desaparece tras un reintento
Eso respalda la hipótesis de un fallo transitorio.
Aun así, revisa la frecuencia.
Si los reintentos se necesitan constantemente, la dependencia puede estar en mal estado o sobrecargada.
La re-ejecución tiene éxito pero los datos se duplican
La política de reintentos/re-ejecución no es segura.
Corrige la idempotencia antes de aumentar el número de reintentos.
Varias actividades aguas abajo fallan o se omiten
Recorre el grafo de dependencias hacia atrás hasta el primer fallo genuino.
No depures cada síntoma aguas abajo de forma independiente.
Notas de producción
La mayoría de los reintentos de actividades deben apuntar a fallos transitorios
Fabric Data Factory admite reintentos de actividades e intervalos entre reintentos.
Las capacidades de reintento actuales también incluyen un comportamiento de retardo creciente y reintentos condicionales para determinados tipos de actividad.
Usa estas funciones para fallos recuperables de infraestructura/servicio, no para errores de código deterministas.
El contexto de ejecución de la actividad Notebook importa
La ejecución de un notebook desencadenada por un pipeline puede usar un contexto de seguridad distinto al de una ejecución interactiva del notebook.
Por lo tanto, un notebook que funciona manualmente puede fallar desde el pipeline porque las condiciones de acceso son distintas.
Las ejecuciones de pipeline no son una única transacción distribuida
Una actividad puede tener éxito y confirmar datos antes de que falle una actividad posterior.
La seguridad de las re-ejecuciones debe diseñarse por actividad.
El registro debe ser duradero
La salida de print de un notebook es útil para la solución de problemas inmediata.
Para la operación, persiste:
- IDs de ejecución
- IDs de lote
- número de filas
- estado
- marcas de tiempo
- metadatos de error seguros
para poder comparar los incidentes a lo largo del tiempo.
Workspace Monitoring puede centralizar el historial de los pipelines
Fabric Workspace Monitoring puede exponer los registros de ejecución a nivel de pipeline y de actividad a través de un eventhouse/base de datos KQL de monitoreo.
Esto es mucho mejor para el análisis operativo recurrente que abrir manualmente páginas de ejecuciones individuales.
Las alertas deben ser accionables
Fabric admite patrones de alertas a nivel de pipeline/actividad.
Alerta sobre los fallos que necesitan intervención, no sobre cada evento transitorio que se recupera solo dentro de la política de reintentos prevista.
Los reintentos consumen tiempo y capacidad
Un reintento no es gratis.
Un exceso de reintentos puede:
- aumentar la latencia del pipeline
- aumentar el consumo de capacidad
- aumentar la carga sobre una dependencia que ya está en mal estado
- duplicar trabajo si las escrituras no son idempotentes
Usa el número de reintentos de forma deliberada.
Errores comunes
1. Volver a ejecutar todo el pipeline inmediatamente
Las actividades anteriores pueden haber confirmado datos ya.
Revisa primero el estado parcial.
2. Reintentar cada fallo
La autenticación, el SQL incorrecto, un esquema no válido y los parámetros incorrectos no van a mejorar porque esperes 30 segundos.
3. Ocultar las excepciones del notebook
Imprimir un error sin volver a lanzarlo puede hacer que el notebook parezca haber tenido éxito.
Falla de forma visible cuando la carga de trabajo falló.
4. Depurar las actividades omitidas
Las actividades omitidas aguas abajo suelen ser consecuencias.
Encuentra el primer fallo real.
5. Suponer que la identidad interactiva es igual a la identidad del pipeline
El contexto de ejecución puede ser distinto.
Compara siempre la identidad y los permisos.
6. Aumentar el tiempo de espera en lugar de investigar la regresión
Una actividad mucho más lenta puede indicar crecimiento del volumen, sesgo de datos (skew), bloqueos o presión sobre los recursos.
7. Anexar a ciegas al volver a ejecutar
Es una forma habitual de crear datos duplicados.
Diseña la idempotencia.
8. Añadir reintentos antes de garantizar la seguridad de las escrituras
Los reintentos automáticos son peligrosos cuando la actividad puede escribir datos no idempotentes de forma parcial o repetida.
9. Registrar secretos para depurar
Nunca expongas credenciales ni tokens en la salida del pipeline.
Usa los controles de entrada/salida segura cuando corresponda.
10. Tomar una re-ejecución exitosa como prueba de que el problema está resuelto
Una re-ejecución exitosa sugiere un fallo transitorio, pero no explica los fallos repetidos.
Haz seguimiento de la tendencia del fallo a lo largo del tiempo.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.