Explorar guías rápidas · Microsoft Fabric

Tecnología: Microsoft FabricCategoría: Solución de problemasNivel: IntermedioActualizado

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
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Empieza por la ejecución del pipeline y luego baja hasta la actividad
  5. 2. Encuentra el primer fallo real, no cada fallo aguas abajo
  6. 3. Registra las entradas de la actividad antes de cambiar nada
  7. 4. Parametriza los notebooks de forma deliberada
  8. 5. Valida los parámetros de fecha antes de usarlos
  9. 6. Valida que el origen exista antes de hacer trabajo costoso
  10. 7. Añade un contexto de ejecución explícito al notebook
  11. 8. Añade un ID de ejecución del pipeline o un ID de lote a las escrituras
  12. 9. Haz explícitos los errores del notebook
  13. 10. Distingue los errores transitorios de los deterministas
  14. 11. Configura los reintentos de las actividades de forma selectiva
  15. 12. Usa reintentos condicionales donde estén disponibles
  16. 13. No reintentes automáticamente los fallos de autenticación
  17. 14. Confirma con qué identidad se ejecuta el notebook
  18. 15. Compara la ejecución interactiva del notebook con la ejecución desde el pipeline
  19. 16. Valida el Lakehouse predeterminado
  20. 17. Depura el arranque de la actividad Notebook por separado del código del notebook
  21. 18. Revisa los fallos de stages/tareas de Spark para los errores del notebook
  22. 19. Vigila los conflictos de concurrencia de Delta
  23. 20. Comprueba si la ejecución fallida escribió datos parcialmente
  24. 21. Diseña actividades idempotentes
  25. 22. Comprueba si hay lotes duplicados antes de volver a ejecutar
  26. 23. Usa una tabla de control para el estado operativo
  27. 24. Evita anexiones a ciegas concurrentes al mismo registro de ejecución sin un diseño adecuado
  28. 25. Haz fallar el pipeline cuando falle la validación de negocio
  29. 26. No codifiques de forma fija rutas específicas de un entorno
  30. 27. Depura los fallos de la actividad Copy por capas
  31. 28. Valida el número de filas de origen y destino cuando esté disponible
  32. 29. Depura por separado los fallos de la actividad de procedimiento almacenado
  33. 30. Define el tiempo de espera de la actividad de forma deliberada
  34. 31. Diferencia un tiempo de espera agotado de una regresión de rendimiento
  35. 32. Usa las condiciones de dependencia de forma intencionada
  36. 33. Conserva el error original al añadir gestión de fallos
  37. 34. Pasa a las alertas solo el contexto de error necesario
  38. 35. Usa Secure Input / Secure Output para las actividades sensibles
  39. 36. Usa el monitoreo del workspace para analizar fallos recurrentes
  40. 37. Consulta las ejecuciones de actividades de pipeline fallidas
  41. 38. Resume los fallos por actividad
  42. 39. Haz seguimiento de las regresiones de duración
  43. 40. Vuelve a ejecutar el alcance seguro más pequeño
  44. Qué significa el resultado
  45. Qué revisar
  46. El fallo ocurre inmediatamente
  47. El fallo ocurre tras una ejecución larga
  48. Solo falla la ejecución desde el pipeline
  49. El fallo desaparece tras un reintento
  50. La re-ejecución tiene éxito pero los datos se duplican
  51. Varias actividades aguas abajo fallan o se omiten
  52. Notas de producción
  53. La mayoría de los reintentos de actividades deben apuntar a fallos transitorios
  54. El contexto de ejecución de la actividad Notebook importa
  55. Las ejecuciones de pipeline no son una única transacción distribuida
  56. El registro debe ser duradero
  57. Workspace Monitoring puede centralizar el historial de los pipelines
  58. Las alertas deben ser accionables
  59. Los reintentos consumen tiempo y capacidad
  60. Errores comunes
  61. 1. Volver a ejecutar todo el pipeline inmediatamente
  62. 2. Reintentar cada fallo
  63. 3. Ocultar las excepciones del notebook
  64. 4. Depurar las actividades omitidas
  65. 5. Suponer que la identidad interactiva es igual a la identidad del pipeline
  66. 6. Aumentar el tiempo de espera en lugar de investigar la regresión
  67. 7. Anexar a ciegas al volver a ejecutar
  68. 8. Añadir reintentos antes de garantizar la seguridad de las escrituras
  69. 9. Registrar secretos para depurar
  70. 10. Tomar una re-ejecución exitosa como prueba de que el problema está resuelto
  71. Siguiente paso
  72. 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.

Siguiente paso

Usa el tipo de fallo para elegir la siguiente acción.

  • 429 / error temporal del servicio → añade un reintento selectivo con un retardo/backoff adecuado.
  • 401 / 403 → corrige la identidad y los permisos; no sigas reintentando.
  • El notebook solo funciona de forma interactiva → compara la identidad del pipeline, los parámetros, el Lakehouse y el Environment.
  • Falla un stage de Spark → inspecciona los diagnósticos del job/stage/tarea de Spark.
  • Conflictos de escritura en Delta → reduce los procesos de escritura que se solapan o escribe primero en staging y luego concilia.
  • Error de esquema/datos → valida las entradas antes del trabajo costoso y falla pronto.
  • Tiempo de espera agotado → compara la duración con la línea base histórica antes de aumentar el límite.
  • La re-ejecución duplica datos → rediseña la actividad para que sea idempotente.
  • El fallo se repite → pasa de la depuración puntual a Workspace Monitoring y al análisis de tendencias.
  • El pipeline tiene éxito pero los datos son incorrectos → añade validación de calidad de negocio, no solo comprobaciones de éxito técnico.

← Todas las guías rápidas