DevOps y observabilidad
Diseñar un registro de ejecución para pipelines y notebooks de Microsoft Fabric
Diseña un registro de ejecución para producción en pipelines y notebooks de Microsoft Fabric: ID de ejecución y de correlación, estados, recuentos de filas, watermarks, errores y reejecuciones seguras.
En este artículo
El historial de ejecuciones de Fabric te dice qué ejecutó la plataforma: una ejecución de pipeline con un ID, sus actividades, sus duraciones y sus errores. No te dice qué significaba esa ejecución. ¿Qué fecha de negocio estaba cargando? ¿Qué ventana de cambios del origen leyó? ¿Cuántas filas insertó, actualizó y rechazó? ¿Hizo avanzar el watermark? ¿Era la ejecución original o una reejecución del fallo de anoche?
Esas preguntas aparecen en cada incidente de producción, y responderlas es el trabajo de un registro de ejecución: una tabla pequeña en la que escriben tus pipelines y notebooks, una fila por ejecución, que guarda el contexto de negocio de la carga junto a su resultado operativo.
Un registro de ejecución no sustituye al monitoreo de Fabric. Lo complementa. El centro de supervisión sigue siendo el lugar para el detalle de las actividades y los logs de Spark; el registro de ejecución es el registro duradero y consultable que vincula esas ejecuciones con las operaciones de negocio, sobrevive a la retención del historial de la plataforma y permite reejecuciones y cargas incrementales. Monitoreo de pipelines y notebooks de Microsoft Fabric en producción muestra cómo lo usa el monitoreo en el día a día. Este artículo trata de su diseño.
El comportamiento de Fabric que se menciona aquí se comprobó en Microsoft Learn en octubre de 2026.
Los identificadores y para qué sirve cada uno
La mayoría de los registros de ejecución fallan por mezclar identificadores. Hay varios, y cada uno responde a una pregunta distinta:
| Identificador | Responde a | Origen |
|---|---|---|
ID de ejecución de la plataforma (pipeline_run_id) |
¿Qué ejecución de pipeline de Fabric era? | @pipeline().RunId, generado por Fabric |
ID de ejecución (execution_id) |
¿Qué registro de ejecución concreto es este? | Tu código de registro: el ID de ejecución del pipeline para los registros de pipeline y un UUID nuevo para todo lo demás |
ID de ejecución padre (parent_execution_id) |
¿Quién llamó a esta ejecución? | Lo transmite el llamante |
ID de correlación (correlation_id) |
¿A qué operación de negocio pertenece? | Lo crea una sola vez el orquestador de nivel superior y se transmite a cada hijo |
Fecha de negocio y ventana (business_date, window_start, window_end) |
¿De qué datos era responsable esta ejecución? | Las calcula el orquestador y las transmite como parámetros |
La distinción que más importa: execution_id identifica un registro; parent_execution_id describe la jerarquía; correlation_id agrupa toda la operación de negocio, incluidas las reejecuciones. Sin los tres, el fallo de un notebook es difícil de diagnosticar, porque el notebook por sí solo no sabe quién lo llamó ni qué día de datos estaba procesando.
El modelo de ejecución
Toda carga que hace un trabajo significativo escribe un registro de ejecución: el pipeline de nivel superior, cada pipeline hijo o Copy job, cada notebook y cada paso de validación.
- correlation_idOperación de negociosales-daily:2026-10-24
- execution_idPipeline padre= @pipeline().RunId
- Pipeline hijo o Copy jobparent_execution_id = pipeline padre
- Notebookparent_execution_id = pipeline padre
- Validaciónparent_execution_id = pipeline padre
En forma de árbol, para una carga diaria:
correlation_id = sales-daily:2026-10-24
└── pl_daily_sales execution_id = 9f1c… (pipeline run ID)
├── pl_load_orders execution_id = 47ab… parent = 9f1c…
│ └── nb_silver_orders execution_id = 3d02… parent = 47ab…
├── nb_validate_sales execution_id = 8e71… parent = 9f1c…
└── nb_publish_gold execution_id = c5f9… parent = 9f1c…
Los ID de ejecución de la plataforma y tus ID de ejecución sirven para cosas distintas. El de la plataforma te permite saltar al centro de supervisión para ver el detalle de las actividades. El tuyo te permite unir tus propios registros entre sí, incluidas ejecuciones que ni siquiera son ejecuciones de pipeline.
El esquema de referencia
Es el esquema que usan el resto de artículos de Fabric de Javi Builds. Los nombres de campo están en snake_case y las marcas de tiempo, en UTC.
Identidad
execution_id: único por registro de ejecuciónparent_execution_id: elexecution_iddel llamante; null para la ejecución de nivel superiorcorrelation_id: la operación de negociorerun_of_execution_id: en una reejecución manual, la ejecución fallida a la que sustituye
Carga
workspace,environment: dónde se ejecutó (dev,test,prod)item_type:pipeline,notebook,copy_job,validationpipeline_name,notebook_name: el elemento que se ejecutópipeline_run_id: el ID de ejecución de Fabric, en los registros de pipelinespark_activity_id: el ID del job de Livy de la sesión del notebook, tomado del contexto de ejecucióntrigger_type:scheduled,manual,rerun,event
Tiempos
start_time,end_time,duration_ms
Estado
status:started,succeeded,failed,cancelled,timed_outretry_count: reintentos automáticos dentro de esta ejecución
Contexto de negocio
business_date,source_system,target_object
Contexto incremental
window_start,window_end: la ventana de cambios acotada, como en cargas incrementales (en inglés)watermark_advanced: si esta ejecución hizo avanzar el watermark
Movimiento de datos
rows_read,rows_written,rows_rejectedrows_inserted,rows_updated,rows_deleted: de las métricas delMERGEfiles_discovered,files_processed,files_skipped,files_failed,bytes_processed: solo cargas de archivos
Errores
error_code,error_stage,error_message
timed_out se gana su sitio junto a failed porque un tiempo de espera agotado suele tener otra causa (capacidad, un origen colgado, la falta de un límite de volumen de datos) y otra solución. Mantén la lista de estados así de corta: todo lo demás va en error_code o en la tabla de eventos.
Campos obligatorios y opcionales
No todos los campos se aplican a todas las ejecuciones. Un esquema en el que cada fila es casi toda null indica una tabla que intenta serlo todo; marcar los campos por tipo de carga la mantiene honesta.
| Campo | ¿Obligatorio? | Propósito | Ejemplo |
|---|---|---|---|
execution_id |
Todas | Identifica el registro | 3d02e1c8-… |
parent_execution_id |
Todas salvo la de nivel superior | Jerarquía | 9f1c… |
correlation_id |
Todas | Operación de negocio | sales-daily:2026-10-24 |
item_type, environment |
Todas | Qué y dónde | notebook, prod |
status, start_time |
Todas | Resultado y momento | succeeded, 2026-10-24 05:00:12 |
end_time, duration_ms |
Todas las ejecuciones terminadas | Duración y referencias | 2026-10-24 05:04:40, 268000 |
pipeline_name, pipeline_run_id, trigger_type |
Pipelines | Vínculo con el historial de ejecuciones de Fabric | pl_daily_sales, 9f1c…, scheduled |
notebook_name, spark_activity_id |
Notebooks | Vínculo con los detalles de Spark | nb_silver_orders |
business_date, target_object |
Ejecuciones que mueven datos | De qué datos era responsable | 2026-10-24, silver_sales_orders |
rows_read, rows_written |
Ejecuciones que mueven datos | Volumen y detección de ejecuciones con cero filas | 1240, 1217 |
rows_inserted, rows_updated, rows_deleted |
Cargas basadas en MERGE |
Qué cambió realmente | 37, 1180, 0 |
rows_rejected |
Ejecuciones con validación o cuarentena | Calidad de datos | 23 |
window_start, window_end, watermark_advanced |
Cargas incrementales | Seguridad de las reejecuciones | 09:50, 11:00, true |
files_*, bytes_processed |
Ingesta de archivos | Salud a nivel de archivo | 300, 298, 0, 2 |
retry_count, rerun_of_execution_id |
Cuando corresponda | Reintentos y reejecuciones | 1, 7a40… |
error_code, error_stage, error_message |
Ejecuciones fallidas | Diagnóstico | Py4JJavaError, merge_silver, … |
Dónde guardarlo
El registro se escribe con operaciones pequeñas y frecuentes: una fila al inicio de cada ejecución y una actualización o segunda fila al final. Ese patrón de escritura decide dónde debe vivir.
- SQL database en Fabric (o Azure SQL Database) es la opción natural para una implementación en T-SQL. Es un motor operativo pensado para
INSERTyUPDATEfila a fila, admite índices y procedimientos almacenados, los pipelines pueden escribir en él con la actividad Script, y Fabric replica sus datos en OneLake para que puedas analizar el registro junto con todo lo demás. - Una tabla Delta de Lakehouse encaja con equipos cuyas cargas son sobre todo notebooks. Escrita solo con anexos desde Spark, como se muestra más abajo, es sencilla y no genera conflictos.
- Fabric Warehouse funciona, pero no es lo ideal. La propia guía de Microsoft recomienda evitar transacciones
INSERT,UPDATEyDELETEa cuentagotas en Warehouse, porque cada una escribe archivos Parquet nuevos y fragmenta la tabla. Un registro de ejecución es exactamente ese tipo de carga. - El punto de conexión de análisis SQL no puede ser el destino. Es de solo lectura sobre las tablas del Lakehouse: puedes consultar a través de él un registro Delta, pero no escribir en él.
Elige un solo almacén para toda la plataforma. Dos medios registros en sitios distintos son peores que uno.
Implementación en SQL (SQL database en Fabric)
CREATE TABLE dbo.execution_log (
log_id bigint IDENTITY(1,1) NOT NULL,
execution_id varchar(64) NOT NULL,
parent_execution_id varchar(64) NULL,
correlation_id varchar(200) NOT NULL,
rerun_of_execution_id varchar(64) NULL,
workspace varchar(128) NULL,
environment varchar(16) NOT NULL,
item_type varchar(20) NOT NULL,
pipeline_name varchar(200) NULL,
notebook_name varchar(200) NULL,
pipeline_run_id varchar(64) NULL,
spark_activity_id varchar(64) NULL,
trigger_type varchar(20) NULL,
status varchar(16) NOT NULL,
retry_count int NOT NULL CONSTRAINT df_execution_log_retry DEFAULT (0),
start_time datetime2(3) NOT NULL,
end_time datetime2(3) NULL,
duration_ms bigint NULL,
business_date date NULL,
source_system varchar(100) NULL,
target_object varchar(200) NULL,
window_start datetime2(3) NULL,
window_end datetime2(3) NULL,
watermark_advanced bit NULL,
rows_read bigint NULL,
rows_written bigint NULL,
rows_inserted bigint NULL,
rows_updated bigint NULL,
rows_deleted bigint NULL,
rows_rejected bigint NULL,
files_discovered int NULL,
files_processed int NULL,
files_skipped int NULL,
files_failed int NULL,
bytes_processed bigint NULL,
error_code varchar(100) NULL,
error_stage varchar(100) NULL,
error_message nvarchar(2000) NULL,
CONSTRAINT pk_execution_log PRIMARY KEY CLUSTERED (log_id),
CONSTRAINT uq_execution_log_execution UNIQUE (execution_id),
CONSTRAINT ck_execution_log_status CHECK (status IN ('started','succeeded','failed','cancelled','timed_out'))
);
CREATE INDEX ix_execution_log_correlation ON dbo.execution_log (correlation_id, start_time);
CREATE INDEX ix_execution_log_status ON dbo.execution_log (status, start_time);
CREATE INDEX ix_execution_log_workload ON dbo.execution_log (pipeline_name, notebook_name, start_time);Un pipeline escribe sus propios registros de inicio y fin con actividades Script (NonQuery) al principio y en sus rutas de éxito y de fallo, usando contenido dinámico como @pipeline().RunId, @pipeline().PipelineName y @pipeline().TriggerTime. Envolver las dos instrucciones en procedimientos almacenados mantiene cortas las expresiones del pipeline y el SQL en un único lugar revisado:
-- Start
INSERT INTO dbo.execution_log (execution_id, parent_execution_id, correlation_id, environment, item_type,
pipeline_name, pipeline_run_id, trigger_type, status, start_time, business_date)
VALUES (@execution_id, @parent_execution_id, @correlation_id, @environment, 'pipeline',
@pipeline_name, @pipeline_run_id, @trigger_type, 'started', SYSUTCDATETIME(), @business_date);
-- Finish: only an open record can be closed
UPDATE dbo.execution_log
SET status = @final_status, end_time = SYSUTCDATETIME(),
duration_ms = DATEDIFF_BIG(millisecond, start_time, SYSUTCDATETIME()),
error_code = @error_code, error_message = @error_message
WHERE execution_id = @execution_id AND status = 'started';La condición AND status = 'started' aplica en la propia base de datos las reglas de estado que se describen más abajo: un registro terminado no se puede reabrir ni cambiar.
Implementación en Delta (Lakehouse, equipos centrados en notebooks)
En un Lakehouse, escribe el registro solo con anexos: una fila cuando empieza la ejecución y otra cuando termina. Una vista devuelve la última fila por execution_id. Así evitas ejecutar UPDATE o MERGE sobre una tabla en la que escriben muchos notebooks a la vez, donde la concurrencia optimista de Delta podría hacer que dos escrituras entren en conflicto. Los anexos ciegos simultáneos no entran en conflicto entre sí.
-- Latest state per execution (Spark SQL view over the append-only table)
CREATE OR REPLACE VIEW execution_log_current AS
SELECT * FROM (
SELECT *, ROW_NUMBER() OVER (PARTITION BY execution_id ORDER BY event_time DESC) AS rn
FROM execution_log_events_raw
) WHERE rn = 1;Aquí la tabla física lleva una columna event_time (cuándo se anexó la fila) además de los campos de referencia, y la vista presenta la forma de referencia. Los anexos pequeños y frecuentes también generan muchos archivos pequeños, así que activa la compactación automática en la tabla del registro; el mantenimiento de tablas Delta (en inglés) explica por qué.
El ciclo de inicio y fin en un notebook
La secuencia es la misma sea cual sea el almacén:
- Crear el ID de ejecución.
- Escribir un registro
started. - Ejecutar la carga.
- Si tiene éxito, escribir
succeededcon las métricas. - Si falla, escribir
failedcon un error depurado. - Volver a lanzar la excepción.
import uuid
from datetime import datetime, timezone
# Parameters passed by the pipeline (see "Capturing Fabric run IDs")
# correlation_id, parent_execution_id, business_date, window_start, window_end, environment
ctx = notebookutils.runtime.context
execution_id = str(uuid.uuid4())
start_time = datetime.now(timezone.utc)
def log(status, **fields):
now = datetime.now(timezone.utc)
row = {
"execution_id": execution_id,
"parent_execution_id": parent_execution_id,
"correlation_id": correlation_id,
"environment": environment,
"item_type": "notebook",
"notebook_name": ctx["currentNotebookName"],
"spark_activity_id": ctx["activityId"],
"status": status,
"start_time": start_time,
"end_time": None if status == "started" else now,
"duration_ms": None if status == "started" else int((now - start_time).total_seconds() * 1000),
"business_date": business_date,
"window_start": window_start,
"window_end": window_end,
"event_time": now,
**fields,
}
(spark.createDataFrame([row])
.write.format("delta").mode("append").option("mergeSchema", "true")
.saveAsTable("execution_log_events_raw"))
log("started")
try:
metrics = run_silver_merge(window_start, window_end) # returns rows_read, rows_inserted, ...
log("succeeded", target_object="silver_sales_orders", **metrics)
except Exception as e:
log("failed", error_code=type(e).__name__, error_stage="merge_silver", error_message=str(e)[:2000])
raiseEl raise final es la línea más importante. Un notebook que registra el fallo y después termina con normalidad convierte una actividad roja en verde, así que la ruta de fallo del pipeline, sus reintentos y sus alertas nunca se disparan. El registro es una evidencia, no un manejo de errores. (El comentario del código remite a la sección «Capturar los ID de ejecución de Fabric», más abajo.)
Capturar los ID de ejecución de Fabric
Fabric proporciona algunos identificadores automáticamente; el resto los pasas tú de forma explícita.
En los pipelines, estas variables del sistema están disponibles en el contenido dinámico:
@pipeline().RunId: la ejecución de pipeline actual. Úsalo comoexecution_idypipeline_run_iddel registro del pipeline.@pipeline().PipelineName,@pipeline().TriggerTime,@pipeline().TriggerName.@pipeline()?.TriggeredByPipelineRunIdyTriggeredByPipelineName: la ejecución del pipeline que llamó, cuando este pipeline lo inició una actividad Invoke pipeline. Null en otro caso; fíjate en el?.
En los notebooks, notebookutils.runtime.context informa del nombre del notebook, el workspace, el Lakehouse predeterminado, si la ejecución es para un pipeline (isForPipeline) y el activityId de la sesión. Sus campos currentRunId, parentRunId y rootRunId solo se rellenan en las ejecuciones de referencia de notebooks (notebooks iniciados con notebookutils.notebook.run o runMultiple). No contienen el ID de ejecución del pipeline que llamó.
Por eso el patrón fiable es explícito: el pipeline pasa su identidad a cada notebook como parámetros base:
| Parámetro del notebook | Valor |
|---|---|
parent_execution_id |
@pipeline().RunId |
correlation_id |
@pipeline().parameters.correlation_id (ver la siguiente sección) |
business_date, window_start, window_end |
calculados por el pipeline |
environment |
desde un parámetro del pipeline o una biblioteca de variables |
Los parámetros de notebooks explican cómo declararlos y validarlos, y la actividad Invoke Pipeline cómo pasar valores de un pipeline padre a uno hijo.
En notebooks que orquestan otros notebooks mediante ejecuciones de referencia, los ID de ejecución del contexto son útiles para el árbol interno; aun así, pasa explícitamente los identificadores de negocio.
Generar el ID de correlación
El orquestador de nivel superior crea un único ID de correlación por operación de negocio y lo pasa a cada hijo. Los hijos nunca generan el suyo.
Lo que mejor funciona es un ID de correlación determinista, construido a partir de la carga y su clave de negocio:
@concat('sales-daily:', formatDateTime(pipeline().parameters.business_date, 'yyyy-MM-dd'))
Como se deriva de lo que es la operación y no de una ejecución concreta, una reejecución de la misma fecha de negocio recibe el mismo ID de correlación. Una sola consulta muestra entonces el intento fallido original, la reejecución y todo lo que llamaron. Un ID de correlación derivado de @pipeline().RunId separaría cada reejecución en una operación distinta y sin relación.
Los pipelines hijos lo reciben como parámetro y lo pasan a sus propios hijos. Si alguna vez se ejecuta un hijo por su cuenta, debe exigir el parámetro en lugar de inventarse un valor.
Cargas incrementales
En las cargas incrementales, el registro forma parte de la garantía de corrección. El artículo sobre cargas incrementales (en inglés) guarda el watermark en su propia tabla de control; el registro de ejecución anota qué hizo cada ejecución con él, para poder responder:
- ¿Cuál era el watermark anterior y qué límite superior seleccionó esta ejecución? (
window_start,window_end) - ¿Cuántas filas se leyeron, insertaron, actualizaron y eliminaron?
- ¿Pasó la validación?
- ¿Avanzó el watermark? (
watermark_advanced)
Seguridad del watermark
La secuencia segura falla de forma recuperable:
se confirman las escrituras Silver y Gold
↓
la ejecución falla antes de guardar el watermark
↓
registro de ejecución: status = failed, watermark_advanced = false
↓
la siguiente ejecución lee el watermark anterior y vuelve a procesar la ventana sin riesgo
La secuencia peligrosa falla en silencio:
el watermark avanza primero
↓
la escritura posterior falla
↓
la siguiente ejecución empieza después del nuevo watermark: esa ventana se salta para siempre
El registro de ejecución hace visibles ambos casos. Un registro failed con watermark_advanced = false es esperable y recuperable; un watermark que se movió sin un registro succeeded correspondiente es un incidente. El artículo de monitoreo incluye la consulta que lo detecta.
Reejecuciones
Nunca sobrescribas un registro fallido. La ejecución fallida es una evidencia: cuándo falló, dónde y con qué entradas. Una reejecución recibe su propio registro, con su propio execution_id, estado y tiempos:
correlation_id: el mismo, para que los intentos aparezcan juntos.rerun_of_execution_id: apunta a la ejecución fallida a la que sustituye.trigger_type = 'rerun'.
rerun_of_execution_id se gana su columna: permite contar cuántas veces una carga necesita intervención manual y responder «¿alguien volvió a ejecutar esto?» sin leer tickets. Un attempt_number aporta poco cuando ya tienes ese vínculo y el ID de correlación.
Reintento frente a reejecución
Las dos palabras se suelen usar indistintamente. En el registro son cosas distintas:
- Reintento (retry): una ejecución repite automáticamente una actividad fallida. Una actividad de pipeline con reintentos habilitados, o la lógica de reintento dentro de un notebook, hace varios intentos dentro de la misma ejecución. Anótalo como
retry_counten el registro de esa ejecución. - Reejecución (rerun): una ejecución nueva de la carga después de que otra anterior terminara o fallara. Una recuperación programada, un operador que pulsa Volver a ejecutar en el centro de supervisión, una recarga histórica. Recibe un registro nuevo, vinculado por
rerun_of_execution_idycorrelation_id.
Una ejecución que tiene éxito tras dos reintentos está sana, pero conviene seguir su tendencia; una carga que necesita una reejecución cada semana no está sana, aunque todas las reejecuciones tengan éxito.
Idempotencia: el registro no debe bloquear reejecuciones legítimas
Un atajo tentador es hacer que las cargas se salten el trabajo que ya tiene un registro: «si existe una fila succeeded para esta fecha, no hagas nada». Parece una protección contra el procesamiento duplicado. En la práctica convierte el registro en un estado oculto que bloquea justo las reejecuciones que necesitas tras una carga incorrecta, una corrección de código o una recarga histórica.
Mantén separadas las dos preocupaciones. La idempotencia sale de cómo escribe datos la carga: claves deterministas, MERGE protegido, sobrescritura de un segmento acotado. El registro anota lo que pasó; no decide si el trabajo puede hacerse. Si una carga de verdad debe ejecutarse como máximo una vez por clave (por ejemplo, para enviar una notificación externa), haz explícita esa regla, con su propia clave y una excepción documentada, en lugar de convertirla en un efecto secundario del registro.
Transiciones de estado
| De | A | ¿Permitido? |
|---|---|---|
| (nuevo) | started |
Sí, cuando empieza la ejecución |
started |
succeeded, failed, cancelled, timed_out |
Sí, una vez, cuando termina |
failed, cancelled, timed_out |
succeeded |
No: escribe en su lugar un registro de ejecución nuevo |
succeeded |
cualquier estado | No |
Un registro que sigue en started mucho después de cuando debería haber terminado significa que el proceso murió sin escribir su estado final: una sesión terminada, un rechazo por capacidad, un fallo en el propio registro. Detéctalos con una consulta (más abajo) y ciérralos como failed con error_code = 'abandoned' mediante una comprobación programada, en lugar de dejarlos abiertos para siempre.
Gestión de errores
Cuando una ejecución falla, registra lo suficiente para empezar el diagnóstico sin abrir cinco pantallas:
error_code: el tipo de excepción o un código estable.error_stage: qué paso falló (extract,merge_silver,validate).error_message: un mensaje conciso y truncado.- Los identificadores y el momento, que el registro ya contiene.
Guarda las trazas de pila completas en los logs de Spark o en la tabla de eventos, no en la tabla de ejecución, que es deliberadamente estrecha. Vincúlalas mediante spark_activity_id.
Nunca registres secretos. Ni contraseñas, claves, tokens, cadenas de conexión o URL SAS, ni cargas útiles completas que puedan contener datos personales. Los mensajes de error de los controladores a veces incluyen detalles de conexión, así que depúralos antes de escribirlos. En los pipelines, marca las actividades cuyas entradas o salidas contengan valores sensibles como entrada segura y salida segura (secure input, secure output) para que tampoco aparezcan en el historial de ejecuciones.
Recuentos de filas: sé específico
Una única columna row_count se vuelve ambigua la primera vez que alguien pregunta «¿recuento de filas de qué?». Nombra los recuentos según lo que miden:
rows_read: filas leídas del origen o de la ventana.rows_inserted,rows_updated,rows_deleted: lo que cambió la escritura. Delta guarda estos valores como métricas de la operaciónMERGEen el historial de la tabla, así que puedes leerlos en lugar de hacer recuentos adicionales.rows_rejected: filas enviadas a cuarentena o descartadas por la validación.rows_written: total de filas escritas, para cargas de anexado o sobrescritura en las que no aplican inserción y actualización.
Un recuento final de filas del destino a veces es útil para conciliar, pero cuesta un recuento completo, así que obténlo solo donde se justifique.
Campos de ingesta de archivos
En las cargas basadas en archivos, añade los contadores de archivos: files_discovered, files_processed, files_skipped, files_failed y bytes_processed. Déjalos en null en las cargas desde bases de datos; son opcionales por diseño. El detalle por archivo (qué archivo falló, su checksum, el motivo) va en la tabla de archivos procesados o en la tabla de eventos, no como columnas aquí.
Una fila por ejecución, no por registro de datos
El registro de ejecución guarda ejecuciones, no datos. Una fila por ejecución de pipeline, notebook o validación. Registrar una fila por cada registro de origen, cada línea de archivo o cada iteración de un bucle convierte una tabla operativa pequeña en una grande y lenta que nadie puede consultar durante un incidente.
Cuando necesites más detalle, como hitos dentro de un notebook largo, resultados por archivo o métricas intermedias, añade una segunda tabla opcional.
La tabla de eventos opcional
CREATE TABLE dbo.execution_event (
event_id bigint IDENTITY(1,1) NOT NULL PRIMARY KEY,
execution_id varchar(64) NOT NULL,
event_time datetime2(3) NOT NULL,
event_type varchar(30) NOT NULL, -- milestone, metric, warning, error
stage varchar(100) NULL,
message nvarchar(2000) NULL,
metric_name varchar(100) NULL,
metric_value decimal(38,6) NULL
);
CREATE INDEX ix_execution_event_execution ON dbo.execution_event (execution_id, event_time);Es útil cuando una misma ejecución tiene fases distintas que merece la pena cronometrar (extracción, transformación, escritura), cuando importan los resultados por archivo o cuando quieres avisos que no hagan fallar la ejecución. Mantenla acotada: unos pocos eventos por ejecución, no un flujo. Si escribes cientos de eventos por ejecución, lo que necesitas es una herramienta de trazas o de logs, no una tabla.
- correlation_idOperación de negocioUna por fecha de negocio o lote
- execution_idTabla de ejecución
- parent_execution_id
- estado y tiempos
- filas y watermark
- resumen del error
- execution_idTabla de eventos (opcional)
- hitos
- métricas
- avisos
- detalle del error
Consultas operativas
Se ejecutan sobre la implementación en SQL database; la versión Delta es la misma sobre execution_log_current.
-- 1. Everything that happened for one business operation, including reruns
SELECT item_type, pipeline_name, notebook_name, status, start_time, duration_ms,
rows_read, rows_inserted, rows_updated, retry_count, rerun_of_execution_id, error_message
FROM dbo.execution_log
WHERE correlation_id = 'sales-daily:2026-10-24'
ORDER BY start_time;
-- 2. Failed executions in the last day
SELECT start_time, item_type, COALESCE(notebook_name, pipeline_name) AS workload,
error_code, error_stage, error_message, correlation_id
FROM dbo.execution_log
WHERE status IN ('failed', 'timed_out') AND start_time >= DATEADD(day, -1, SYSUTCDATETIME())
ORDER BY start_time DESC;
-- 3. Executions still open long after they should have finished (abandoned)
SELECT execution_id, COALESCE(notebook_name, pipeline_name) AS workload, start_time
FROM dbo.execution_log
WHERE status = 'started' AND start_time < DATEADD(hour, -6, SYSUTCDATETIME()); -- example cutoff
-- 4. Duration against recent history, per workload
WITH recent AS (
SELECT COALESCE(notebook_name, pipeline_name) AS workload, duration_ms,
PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY duration_ms)
OVER (PARTITION BY COALESCE(notebook_name, pipeline_name)) AS p50_ms
FROM dbo.execution_log
WHERE status = 'succeeded' AND start_time >= DATEADD(day, -28, SYSUTCDATETIME())
)
SELECT workload, MAX(p50_ms) / 60000.0 AS median_minutes, MAX(duration_ms) / 60000.0 AS worst_minutes
FROM recent GROUP BY workload ORDER BY worst_minutes DESC;
-- 5. Failures by workload over 30 days
SELECT COALESCE(notebook_name, pipeline_name) AS workload, COUNT(*) AS failures,
SUM(CASE WHEN rerun_of_execution_id IS NOT NULL THEN 1 ELSE 0 END) AS reruns
FROM dbo.execution_log
WHERE start_time >= DATEADD(day, -30, SYSUTCDATETIME())
AND (status IN ('failed', 'timed_out') OR rerun_of_execution_id IS NOT NULL)
GROUP BY COALESCE(notebook_name, pipeline_name)
ORDER BY failures DESC;
-- 6. Suspicious incremental runs: watermark advanced by a run that did not succeed
SELECT execution_id, notebook_name, status, window_start, window_end, start_time
FROM dbo.execution_log
WHERE watermark_advanced = 1 AND status <> 'succeeded';El corte de seis horas de la consulta 3 es solo un ejemplo: básalo en la duración normal más larga de cada carga. El artículo de monitoreo añade la comprobación complementaria contra la propia tabla de watermarks.
Retención
No existe un periodo de retención universal. Depende de:
- Las necesidades de diagnóstico: cuánto tiempo atrás comparas cuando una carga se vuelve lenta.
- Las ventanas de reejecución y recarga: necesitas el registro al menos durante el tiempo en que podrías volver a ejecutar.
- Los requisitos de auditoría y normativos: algunos flujos de datos deben demostrar qué se ejecutó y cuándo.
- El volumen: unos cientos de ejecuciones al día es muy poco; muchos miles con eventos detallados, no.
Un patrón habitual es conservar la tabla de ejecución mucho más tiempo que la de eventos, porque una fila por ejecución sigue siendo pequeña durante años, mientras que el detalle de eventos sirve sobre todo para incidentes recientes. Conserva durante aún más tiempo resúmenes agregados (percentiles diarios de duración, recuentos de fallos) si necesitas tendencias largas.
Diseño físico
Los patrones de consulta son predecibles: búsqueda por execution_id, agrupación por correlation_id, filtros por status y tiempo, tendencias por carga y tiempo. Cómo darles soporte depende del almacén:
- SQL database en Fabric / Azure SQL: se aplica el diseño habitual de SQL Server. Una clave agrupada estrecha sobre un
log_idcreciente mantiene baratas las inserciones; una restricción única sobreexecution_id; índices no agrupados sobre(correlation_id, start_time),(status, start_time)y las columnas de carga, como en el esquema anterior. Evita agrupar por un UUID aleatorio. - Delta en un Lakehouse: no hay índices. La tabla se mantiene lo bastante pequeña como para que eso rara vez importe; mantén los archivos compactados y, si alguna vez crece mucho, organízala por fecha y no por ID. Tablas Delta para ingenieros de SQL Server (en inglés) explica por qué los hábitos de indexación no se trasladan.
- Fabric Warehouse: no hay índices creados por el usuario; el motor gestiona las estadísticas y la compactación, y la agrupación de datos (data clustering) es el control de organización disponible. La cuestión de las escrituras a cuentagotas mencionada antes importa más que la indexación.
Cómo encaja con el monitoreo
Los dos artículos de Javi Builds se reparten el trabajo de forma deliberada:
- El registro de ejecución es el contexto duradero de la carga: qué se le pidió hacer a cada ejecución, qué hizo y cómo se relaciona con el resto de la operación.
- El monitoreo es el uso operativo de ese contexto junto con el historial de ejecuciones de Fabric, los resultados de validación y el historial de capacidad: alertas, referencias, investigaciones.
Otros artículos relacionados:
- Pipelines, notebooks, Dataflow Gen2 o Copy Job (en inglés) explica qué herramienta se encarga de cada paso, lo que decide quién escribe cada registro.
- La capacidad de Microsoft Fabric explicada (en inglés) es el complemento cuando una ejecución es lenta por motivos ajenos a su propio código, y el diagnóstico de un problema de saturación de capacidad en Fabric (en inglés) muestra el registro usado para explicar un pico de capacidad.
- CI/CD de Microsoft Fabric con fabric-cicd cubre el despliegue del propio código de registro; mantén el almacén del registro y sus parámetros específicos de cada entorno.
- Cómo usar session tags en pipelines de Fabric es relevante cuando registras
spark_activity_id: los notebooks etiquetados pueden compartir sesión, así que varias ejecuciones pueden informar la misma sesión manteniendo ID de ejecución distintos. - Las fichas Monitorear pipelines y notebooks de Fabric y Depurar pipelines de Fabric son referencias rápidas para usar el registro durante un incidente, y la lista de comprobación de monitoreo de una plataforma de datos (en inglés) cubre la revisión más amplia.
Lista de comprobación para producción
- Un solo almacén para toda la plataforma, adecuado para escrituras pequeñas y frecuentes.
- Cada ejecución escribe un registro: pipelines, pipelines hijos, Copy jobs, notebooks, validación.
- Identificadores separados:
execution_idpor registro,parent_execution_idpara el árbol, uncorrelation_idpor operación de negocio. - ID de correlación creado una sola vez por el orquestador de nivel superior y transmitido hacia abajo; determinista, para que las reejecuciones lo compartan.
- ID de ejecución pasados explícitamente de los pipelines a los notebooks como parámetros.
- Registros de inicio y fin escritos; excepciones relanzadas tras registrarlas.
- Transiciones de estado aplicadas: los registros terminados nunca cambian; las reejecuciones reciben registros nuevos.
- Reintentos y reejecuciones diferenciados:
retry_countfrente arerun_of_execution_id. - Recuentos de filas específicos y, en cargas incrementales, límites de ventana y
watermark_advanced. - Ejecuciones abandonadas detectadas y cerradas.
- Ningún secreto en errores ni parámetros; entradas y salidas sensibles de las actividades marcadas como seguras.
- Una fila por ejecución, con una tabla de eventos opcional y acotada para el detalle.
- Retención decidida por tabla, según las necesidades de diagnóstico, reejecución y auditoría.
Con el registro en marcha, el siguiente paso de este recorrido lo pone a trabajar: Depurar pipelines y notebooks de Microsoft Fabric en producción (en inglés) usa estos identificadores para rastrear una ejecución fallida, lenta o con resultados incorrectos hasta su causa.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Sigue aprendiendo
- Guía rápidaMonitorear pipelines y notebooks de FabricMonitorea pipelines y notebooks de Microsoft Fabric con Monitoring hub, Workspace Monitoring, el monitoreo de Spark, KQL, alertas y telemetría de capacidad para que los errores y las regresiones de rendimiento sean observables.Abrir guía rápida
- ArtículoMonitoreo de una plataforma de datos: ¿qué conviene medir realmente?Un modelo práctico de monitoreo que conecta clientes, aplicaciones, API, motores de informes, plataformas de datos, cómputo y almacenamiento.Leer artículo
¿Qué debería crear después?
Estoy construyendo Javi Builds alrededor de problemas reales que enfrentan los ingenieros de datos. Dime qué tema te gustaría ver después.
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.