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.

Por JaviPublicado Actualizado 20 min de lecturaIntermedio

Flujo de registro de ejecución desde el desencadenador hasta la actividad hija y el log operativo
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.

  1. correlation_idOperación de negociosales-daily:2026-10-24
  2. 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
Una operación de negocio, un registro por ejecución. correlation_id une toda la operación. Cada bloque escribe su propio registro con su propio execution_id, y parent_execution_id apunta al llamante.

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ón
  • parent_execution_id: el execution_id del llamante; null para la ejecución de nivel superior
  • correlation_id: la operación de negocio
  • rerun_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, validation
  • pipeline_name, notebook_name: el elemento que se ejecutó
  • pipeline_run_id: el ID de ejecución de Fabric, en los registros de pipeline
  • spark_activity_id: el ID del job de Livy de la sesión del notebook, tomado del contexto de ejecución
  • trigger_type: scheduled, manual, rerun, event

Tiempos

  • start_time, end_time, duration_ms

Estado

  • status: started, succeeded, failed, cancelled, timed_out
  • retry_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_rejected
  • rows_inserted, rows_updated, rows_deleted: de las métricas del MERGE
  • files_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 INSERT y UPDATE fila 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, UPDATE y DELETE a 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)

Consulta SQL: Implementación en SQL (SQL database en Fabric)T-SQL (SQL database in 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);
T-SQL (SQL database in Fabric)47 líneasVista de solo lectura. No está conectada a ninguna base de datos.

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:

Consulta SQL: Implementación en SQL (SQL database en Fabric)T-SQL (SQL database in Fabric)
-- 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';
T-SQL (SQL database in Fabric)12 líneasVista de solo lectura. No está conectada a ninguna base de datos.

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í.

Consulta SQL: Implementación en Delta (Lakehouse, equipos centrados en notebooks)Spark SQL
-- 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;
Spark SQL6 líneasVista de solo lectura. No está conectada a ninguna base de datos.

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:

  1. Crear el ID de ejecución.
  2. Escribir un registro started.
  3. Ejecutar la carga.
  4. Si tiene éxito, escribir succeeded con las métricas.
  5. Si falla, escribir failed con un error depurado.
  6. Volver a lanzar la excepción.
PySpark
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])
    raise
PySpark41 líneasCelda de ejemplo de solo lectura. Nada en esta página ejecuta código.

El 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 como execution_id y pipeline_run_id del registro del pipeline.
  • @pipeline().PipelineName, @pipeline().TriggerTime, @pipeline().TriggerName.
  • @pipeline()?.TriggeredByPipelineRunId y TriggeredByPipelineName: 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_count en 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_id y correlation_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ón MERGE en 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

Consulta SQL: La tabla de eventos opcionalT-SQL (SQL database in Fabric)
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);
T-SQL (SQL database in Fabric)11 líneasVista de solo lectura. No está conectada a ninguna base de datos.

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.

  1. correlation_idOperación de negocioUna por fecha de negocio o lote
  2. execution_idTabla de ejecución
    • parent_execution_id
    • estado y tiempos
    • filas y watermark
    • resumen del error
  3. execution_idTabla de eventos (opcional)
    • hitos
    • métricas
    • avisos
    • detalle del error
El modelo de datos del registro de ejecución. correlation_id agrupa las ejecuciones en una operación de negocio, parent_execution_id construye el árbol y la tabla de eventos opcional cuelga de execution_id.

Consultas operativas

Se ejecutan sobre la implementación en SQL database; la versión Delta es la misma sobre execution_log_current.

Consulta SQL: Consultas operativasT-SQL (SQL database in Fabric)
-- 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';
T-SQL (SQL database in Fabric)43 líneasVista de solo lectura. No está conectada a ninguna base de datos.

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_id creciente mantiene baratas las inserciones; una restricción única sobre execution_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:

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_id por registro, parent_execution_id para el árbol, un correlation_id por 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_count frente a rerun_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.

Etiquetas

  • Observabilidad
  • Monitorización
  • Registro
  • Pipelines de datos
  • Microsoft Fabric
  • PySpark