DevOps et observabilité

Concevoir un journal d’exécution pour les pipelines et notebooks Microsoft Fabric

Concevez un journal d’exécution de production pour les pipelines et notebooks Microsoft Fabric : identifiants d’exécution et de corrélation, statuts, nombres de lignes, watermarks, erreurs et réexécutions sûres.

Par JaviPublié Mis à jour 20 min de lectureIntermédiaire

Flux de journalisation des exécutions, du déclenchement à l’activité enfant puis au journal opérationnel
Dans cet article

L’historique des exécutions de Fabric vous dit ce que la plateforme a exécuté : une exécution de pipeline avec un ID, ses activités, leurs durées et leurs erreurs. Il ne vous dit pas ce que cette exécution signifiait. Quelle date métier chargeait-elle ? Quelle fenêtre de modifications source a-t-elle lue ? Combien de lignes a-t-elle insérées, mises à jour et rejetées ? A-t-elle fait avancer le watermark ? S’agissait-il de l’exécution d’origine ou d’une réexécution de l’échec de la nuit précédente ?

Ces questions reviennent à chaque incident de production, et y répondre est le rôle d’un journal d’exécution : une petite table dans laquelle vos pipelines et notebooks écrivent, une ligne par exécution, et qui enregistre le contexte métier de la charge à côté de son résultat opérationnel.

Un journal d’exécution ne remplace pas la supervision de Fabric. Il la complète. Le hub de supervision reste l’endroit où consulter le détail des activités et les journaux Spark ; le journal d’exécution est l’enregistrement durable et interrogeable qui relie ces exécutions aux opérations métier, survit à la durée de conservation de l’historique de la plateforme et rend possibles les réexécutions et les chargements incrémentiels. Superviser les pipelines et notebooks Microsoft Fabric en production montre comment la supervision l’exploite au quotidien. Cet article porte sur sa conception.

Le comportement de Fabric décrit ici a été vérifié sur Microsoft Learn en octobre 2026.

Les identifiants, et le rôle de chacun

La plupart des journaux d’exécution dérapent en mélangeant les identifiants. Il y en a plusieurs, et chacun répond à une question différente :

Identifiant Répond à Provient de
ID d’exécution de la plateforme (pipeline_run_id) De quelle exécution de pipeline Fabric s’agit-il ? @pipeline().RunId, généré par Fabric
ID d’exécution (execution_id) De quel enregistrement d’exécution unique s’agit-il ? Votre code de journalisation : l’ID d’exécution du pipeline pour les enregistrements de pipeline, un nouvel UUID pour tout le reste
ID d’exécution parente (parent_execution_id) Qui a appelé cette exécution ? Transmis par l’appelant
ID de corrélation (correlation_id) À quelle opération métier appartient-elle ? Créé une seule fois par l’orchestrateur de plus haut niveau, transmis à chaque enfant
Date métier et fenêtre (business_date, window_start, window_end) De quelles données cette exécution était-elle responsable ? Calculées par l’orchestrateur, transmises en paramètres

La distinction qui compte le plus : execution_id identifie un enregistrement ; parent_execution_id décrit la hiérarchie ; correlation_id regroupe toute l’opération métier, réexécutions comprises. Sans ces trois identifiants, l’échec d’un notebook est difficile à diagnostiquer, car le notebook seul ne sait ni qui l’a appelé, ni quelle journée de données il traitait.

Le modèle d’exécution

Toute charge qui accomplit un travail significatif écrit un enregistrement d’exécution : le pipeline de plus haut niveau, chaque pipeline enfant ou Copy job, chaque notebook et chaque étape de validation.

  1. correlation_idOpération métiersales-daily:2026-10-24
  2. execution_idPipeline parent= @pipeline().RunId
    • Pipeline enfant ou Copy jobparent_execution_id = pipeline parent
    • Notebookparent_execution_id = pipeline parent
    • Validationparent_execution_id = pipeline parent
Une opération métier, un enregistrement par exécution. correlation_id relie toute l’opération. Chaque bloc écrit son propre enregistrement avec son propre execution_id, et parent_execution_id pointe vers l’appelant.

Sous forme d’arbre, pour un chargement quotidien :

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…

Les ID d’exécution de la plateforme et vos ID d’exécution n’ont pas le même usage. L’ID de la plateforme vous permet d’ouvrir le hub de supervision pour voir le détail des activités. Votre ID d’exécution vous permet de relier vos propres enregistrements entre eux, y compris des exécutions qui ne sont pas du tout des exécutions de pipeline.

Le schéma de référence

C’est le schéma qu’utilisent les autres articles Fabric de Javi Builds. Les noms de champs sont en snake_case et les horodatages en UTC.

Identité

  • execution_id : unique par enregistrement d’exécution
  • parent_execution_id : l’execution_id de l’appelant ; null pour l’exécution de plus haut niveau
  • correlation_id : l’opération métier
  • rerun_of_execution_id : pour une réexécution manuelle, l’exécution échouée qu’elle remplace

Charge

  • workspace, environment : où elle s’est exécutée (dev, test, prod)
  • item_type : pipeline, notebook, copy_job, validation
  • pipeline_name, notebook_name : l’élément exécuté
  • pipeline_run_id : l’ID d’exécution Fabric, pour les enregistrements de pipeline
  • spark_activity_id : l’ID du job Livy de la session du notebook, issu du contexte d’exécution
  • trigger_type : scheduled, manual, rerun, event

Durée

  • start_time, end_time, duration_ms

Statut

  • status : started, succeeded, failed, cancelled, timed_out
  • retry_count : nouvelles tentatives automatiques à l’intérieur de cette exécution

Contexte métier

  • business_date, source_system, target_object

Contexte incrémentiel

  • window_start, window_end : la fenêtre de modifications bornée, comme dans les chargements incrémentiels (en anglais)
  • watermark_advanced : indique si cette exécution a fait avancer le watermark

Mouvement de données

  • rows_read, rows_written, rows_rejected
  • rows_inserted, rows_updated, rows_deleted : issus des métriques du MERGE
  • files_discovered, files_processed, files_skipped, files_failed, bytes_processed : charges de fichiers uniquement

Erreurs

  • error_code, error_stage, error_message

timed_out mérite sa place à côté de failed, car un dépassement de délai a généralement une autre cause (capacité, source bloquée, absence de limite sur le volume de données) et une autre correction. Gardez une liste de statuts aussi courte : tout le reste relève de error_code ou de la table d’événements.

Champs obligatoires et facultatifs

Tous les champs ne s’appliquent pas à toutes les exécutions. Un schéma dont chaque ligne est presque entièrement nulle est le signe d’une table qui veut tout faire ; indiquer les champs par type de charge la garde honnête.

Champ Obligatoire ? Rôle Exemple
execution_id Tous Identifie l’enregistrement 3d02e1c8-…
parent_execution_id Tous sauf le niveau supérieur Hiérarchie 9f1c…
correlation_id Tous Opération métier sales-daily:2026-10-24
item_type, environment Tous Quoi et où notebook, prod
status, start_time Tous Résultat et horodatage succeeded, 2026-10-24 05:00:12
end_time, duration_ms Toutes les exécutions terminées Durée et références 2026-10-24 05:04:40, 268000
pipeline_name, pipeline_run_id, trigger_type Pipelines Lien avec l’historique d’exécution Fabric pl_daily_sales, 9f1c…, scheduled
notebook_name, spark_activity_id Notebooks Lien avec les détails Spark nb_silver_orders
business_date, target_object Exécutions qui déplacent des données Données dont elle était responsable 2026-10-24, silver_sales_orders
rows_read, rows_written Exécutions qui déplacent des données Volume et détection des exécutions à zéro ligne 1240, 1217
rows_inserted, rows_updated, rows_deleted Chargements fondés sur MERGE Ce qui a réellement changé 37, 1180, 0
rows_rejected Exécutions avec validation ou quarantaine Qualité des données 23
window_start, window_end, watermark_advanced Chargements incrémentiels Sûreté des réexécutions 09:50, 11:00, true
files_*, bytes_processed Ingestion de fichiers Santé au niveau des fichiers 300, 298, 0, 2
retry_count, rerun_of_execution_id Selon le cas Nouvelles tentatives et réexécutions 1, 7a40…
error_code, error_stage, error_message Exécutions échouées Diagnostic Py4JJavaError, merge_silver, …

Où le stocker

Le journal est écrit par petites opérations fréquentes : une ligne au début de chaque exécution, puis une mise à jour ou une seconde ligne à la fin. Ce profil d’écriture détermine où il doit vivre.

  • SQL database dans Fabric (ou Azure SQL Database) est le choix naturel pour une implémentation T-SQL. C’est un moteur opérationnel conçu pour des INSERT et UPDATE ligne à ligne ; il prend en charge les index et les procédures stockées, les pipelines peuvent y écrire avec l’activité Script, et Fabric réplique ses données dans OneLake, ce qui permet d’analyser le journal avec tout le reste.
  • Une table Delta de Lakehouse convient aux équipes dont les charges sont surtout des notebooks. Écrite en ajout seul depuis Spark, comme ci-dessous, elle est simple et sans conflit.
  • Fabric Warehouse fonctionne, mais n’est pas idéal. Microsoft recommande lui-même d’éviter les transactions INSERT, UPDATE et DELETE au compte-gouttes dans un Warehouse, car chacune écrit de nouveaux fichiers Parquet et fragmente la table. Un journal d’exécution est exactement ce type de charge.
  • Le point de terminaison d’analytique SQL ne peut pas être la cible. Il est en lecture seule sur les tables du Lakehouse : vous pouvez interroger un journal Delta à travers lui, mais pas y écrire.

Choisissez un seul emplacement pour toute la plateforme. Deux demi-journaux à deux endroits valent moins qu’un seul.

Implémentation SQL (SQL database dans Fabric)

Requête SQL: Implémentation SQL (SQL database dans 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 lignesAffichage en lecture seule. Aucune connexion à une base de données.

Un pipeline écrit ses propres enregistrements de début et de fin avec des activités Script (NonQuery) au démarrage et sur ses chemins de réussite et d’échec, en utilisant du contenu dynamique comme @pipeline().RunId, @pipeline().PipelineName et @pipeline().TriggerTime. Encapsuler les deux instructions dans des procédures stockées garde des expressions de pipeline courtes et le SQL à un seul endroit, relu :

Requête SQL: Implémentation SQL (SQL database dans 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 lignesAffichage en lecture seule. Aucune connexion à une base de données.

La garde AND status = 'started' applique dans la base elle-même les règles de statut décrites plus bas : un enregistrement terminé ne peut être ni rouvert ni basculé.

Implémentation Delta (Lakehouse, équipes centrées sur les notebooks)

Dans un Lakehouse, écrivez le journal en ajout seul : une ligne au début de l’exécution, une autre à la fin. Une vue renvoie la dernière ligne par execution_id. Vous évitez ainsi d’exécuter UPDATE ou MERGE sur une table que de nombreux notebooks écrivent en même temps, où la concurrence optimiste de Delta pourrait faire entrer deux écritures en conflit. Des ajouts aveugles simultanés n’entrent pas en conflit entre eux.

Requête SQL: Implémentation Delta (Lakehouse, équipes centrées sur les 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 lignesAffichage en lecture seule. Aucune connexion à une base de données.

Ici, la table physique porte une colonne event_time (moment où la ligne a été ajoutée) en plus des champs de référence, et la vue présente la forme de référence. De petits ajouts fréquents produisent aussi beaucoup de petits fichiers : activez le compactage automatique sur la table du journal ; la maintenance des tables Delta (en anglais) explique pourquoi.

Le cycle début/fin dans un notebook

La séquence est la même quel que soit l’emplacement :

  1. Créer l’ID d’exécution.
  2. Écrire un enregistrement started.
  3. Exécuter la charge.
  4. En cas de réussite, écrire succeeded avec les métriques.
  5. En cas d’échec, écrire failed avec une erreur expurgée.
  6. Relancer l’exception.
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 lignesCellule d’exemple en lecture seule. Rien sur cette page n’exécute de code.

Le raise final est la ligne la plus importante. Un notebook qui journalise l’échec puis se termine normalement transforme une activité rouge en activité verte : le chemin d’échec du pipeline, ses nouvelles tentatives et ses alertes ne se déclenchent jamais. La journalisation est une preuve, pas une gestion d’erreur. (Le commentaire du code renvoie à la section « Capturer les ID d’exécution Fabric » ci-dessous.)

Capturer les ID d’exécution Fabric

Fabric fournit certains identifiants automatiquement ; les autres, vous les transmettez explicitement.

Dans les pipelines, ces variables système sont disponibles dans le contenu dynamique :

  • @pipeline().RunId : l’exécution de pipeline en cours. Utilisez-le comme execution_id et pipeline_run_id de l’enregistrement du pipeline.
  • @pipeline().PipelineName, @pipeline().TriggerTime, @pipeline().TriggerName.
  • @pipeline()?.TriggeredByPipelineRunId et TriggeredByPipelineName : l’exécution du pipeline appelant, lorsque ce pipeline a été lancé par une activité Invoke pipeline. Null sinon ; notez le ?.

Dans les notebooks, notebookutils.runtime.context indique le nom du notebook, l’espace de travail, le Lakehouse par défaut, si l’exécution est faite pour un pipeline (isForPipeline) et l’activityId de la session. Ses champs currentRunId, parentRunId et rootRunId ne sont renseignés que pour les exécutions de référence de notebooks (notebooks lancés avec notebookutils.notebook.run ou runMultiple). Ils ne contiennent pas l’ID d’exécution du pipeline appelant.

Le modèle fiable est donc explicite : le pipeline transmet son identité à chaque notebook sous forme de paramètres de base :

Paramètre du notebook Valeur
parent_execution_id @pipeline().RunId
correlation_id @pipeline().parameters.correlation_id (voir la section suivante)
business_date, window_start, window_end calculés par le pipeline
environment depuis un paramètre de pipeline ou une bibliothèque de variables

Les paramètres des notebooks expliquent comment les déclarer et les valider, et l’activité Invoke Pipeline comment transmettre des valeurs d’un pipeline parent à un pipeline enfant.

Pour les notebooks qui en orchestrent d’autres par des exécutions de référence, les ID d’exécution du contexte d’exécution sont utiles pour l’arbre interne ; transmettez quand même explicitement les identifiants métier.

Générer l’ID de corrélation

L’orchestrateur de plus haut niveau crée un seul ID de corrélation par opération métier et le transmet à chaque enfant. Les enfants n’en génèrent jamais.

Un ID de corrélation déterministe, construit à partir de la charge et de sa clé métier, fonctionne le mieux :

@concat('sales-daily:', formatDateTime(pipeline().parameters.business_date, 'yyyy-MM-dd'))

Comme il découle de ce qu’est l’opération, et non d’une exécution particulière, une réexécution de la même date métier reçoit le même ID de corrélation. Une seule requête montre alors la tentative échouée d’origine, la réexécution et tout ce qu’elles ont appelé. Un ID de corrélation dérivé de @pipeline().RunId séparerait chaque réexécution en une opération distincte, sans lien avec les autres.

Les pipelines enfants le reçoivent en paramètre et le transmettent à leurs propres enfants. Si un enfant est un jour exécuté seul, il doit exiger ce paramètre plutôt que d’inventer une valeur.

Chargements incrémentiels

Pour les charges incrémentielles, le journal fait partie de la garantie d’exactitude. L’article sur les chargements incrémentiels (en anglais) conserve le watermark dans sa propre table de contrôle ; le journal d’exécution enregistre ce que chaque exécution en a fait, pour répondre à ces questions :

  • Quel était le watermark précédent, et quelle borne supérieure cette exécution a-t-elle retenue ? (window_start, window_end)
  • Combien de lignes ont été lues, insérées, mises à jour et supprimées ?
  • La validation a-t-elle réussi ?
  • Le watermark a-t-il avancé ? (watermark_advanced)

Sûreté du watermark

La séquence sûre échoue de façon récupérable :

les écritures Silver et Gold sont validées
  ↓
l’exécution échoue avant d’enregistrer le watermark
  ↓
enregistrement d’exécution : status = failed, watermark_advanced = false
  ↓
l’exécution suivante lit l’ancien watermark et rejoue la fenêtre sans risque

La séquence dangereuse échoue en silence :

le watermark avance d’abord
  ↓
l’écriture en aval échoue
  ↓
l’exécution suivante démarre après le nouveau watermark : cette fenêtre est sautée pour de bon

Le journal d’exécution rend les deux visibles. Un enregistrement failed avec watermark_advanced = false est attendu et récupérable ; un watermark qui a bougé sans enregistrement succeeded correspondant est un incident. L’article sur la supervision contient la requête qui le détecte.

Réexécutions

N’écrasez jamais un enregistrement en échec. L’exécution échouée est une preuve : quand elle a échoué, où, avec quelles entrées. Une réexécution reçoit son propre enregistrement, avec son propre execution_id, son statut et sa durée :

  • correlation_id : le même, pour que les tentatives apparaissent ensemble.
  • rerun_of_execution_id : pointe vers l’exécution échouée qu’elle remplace.
  • trigger_type = 'rerun'.

rerun_of_execution_id mérite sa colonne : il permet de compter combien de fois une charge nécessite une intervention manuelle, et de répondre à « quelqu’un a-t-il relancé ceci ? » sans lire les tickets. Un attempt_number apporte peu une fois ce lien et l’ID de corrélation en place.

Nouvelle tentative ou réexécution

Les deux termes sont souvent employés l’un pour l’autre. Dans le journal, ce sont deux choses différentes :

  • Nouvelle tentative (retry) : une exécution répète automatiquement une activité en échec. Une activité de pipeline avec des nouvelles tentatives activées, ou une logique de nouvelle tentative dans un notebook, fait plusieurs essais au sein de la même exécution. Enregistrez-la dans retry_count sur l’enregistrement de cette exécution.
  • Réexécution (rerun) : une nouvelle exécution de la charge après la fin ou l’échec d’une précédente. Un rattrapage planifié, un opérateur qui clique sur Réexécuter dans le hub de supervision, un rechargement historique. Elle reçoit un nouvel enregistrement, lié par rerun_of_execution_id et correlation_id.

Une exécution qui réussit après deux nouvelles tentatives est saine, mais mérite d’être suivie dans le temps ; une charge qui a besoin d’une réexécution chaque semaine n’est pas saine, même si chaque réexécution réussit.

Idempotence : le journal ne doit pas bloquer les réexécutions légitimes

Un raccourci tentant consiste à faire ignorer par les charges tout travail déjà présent dans le journal : « si une ligne succeeded existe pour cette date, ne rien faire ». Cela ressemble à une protection contre le double traitement. En pratique, le journal devient un état caché qui bloque les réexécutions dont vous avez besoin après un mauvais chargement, une correction de code ou un rechargement historique.

Gardez les deux préoccupations séparées. L’idempotence vient de la façon dont la charge écrit les données : clés déterministes, MERGE protégé, écrasement d’une tranche bornée. Le journal enregistre ce qui s’est passé ; il ne décide pas si le travail peut avoir lieu. Si une charge doit vraiment s’exécuter au plus une fois par clé (par exemple pour envoyer une notification externe), rendez cette règle explicite, avec sa propre clé et une dérogation documentée, plutôt que d’en faire un effet de bord du journal.

Transitions de statut

De Vers Autorisé ?
(nouveau) started Oui, au début de l’exécution
started succeeded, failed, cancelled, timed_out Oui, une fois, à la fin
failed, cancelled, timed_out succeeded Non : écrivez plutôt un nouvel enregistrement d’exécution
succeeded n’importe quel statut Non

Un enregistrement qui reste started bien après l’heure où il aurait dû se terminer signifie que le processus s’est arrêté sans écrire son statut final : session tuée, rejet par la capacité, plantage de la journalisation elle-même. Détectez-les par une requête (ci-dessous) et clôturez-les en failed avec error_code = 'abandoned' au moyen d’un contrôle planifié, plutôt que de les laisser ouverts indéfiniment.

Gestion des erreurs

Quand une exécution échoue, journalisez de quoi commencer le diagnostic sans ouvrir cinq écrans :

  • error_code : le type d’exception ou un code stable.
  • error_stage : l’étape qui a échoué (extract, merge_silver, validate).
  • error_message : un message concis et tronqué.
  • Les identifiants et l’horodatage, que l’enregistrement contient déjà.

Conservez les traces de pile complètes dans les journaux Spark ou la table d’événements, pas dans la table d’exécution, volontairement étroite. Reliez-les par spark_activity_id.

Ne journalisez jamais de secrets. Pas de mots de passe, clés, jetons, chaînes de connexion ni URL SAS, et pas de charges utiles complètes susceptibles de contenir des données personnelles. Les messages d’erreur des pilotes incluent parfois des détails de connexion : expurgez-les avant l’écriture. Dans les pipelines, marquez les activités dont les entrées ou sorties contiennent des valeurs sensibles comme entrée sécurisée et sortie sécurisée (secure input, secure output), pour qu’elles n’apparaissent pas non plus dans l’historique des exécutions.

Nombres de lignes : soyez précis

Une colonne unique row_count devient ambiguë la première fois que quelqu’un demande « le nombre de lignes de quoi ? ». Nommez les compteurs d’après ce qu’ils mesurent :

  • rows_read : lignes lues dans la source ou la fenêtre.
  • rows_inserted, rows_updated, rows_deleted : ce que l’écriture a modifié. Delta enregistre ces valeurs comme métriques de l’opération MERGE dans l’historique de la table : vous pouvez les lire au lieu de lancer des comptages supplémentaires.
  • rows_rejected : lignes envoyées en quarantaine ou écartées par la validation.
  • rows_written : total des lignes écrites, pour les charges en ajout ou en écrasement où insertion et mise à jour ne s’appliquent pas.

Un nombre final de lignes dans la cible est parfois utile pour un rapprochement, mais il coûte un comptage complet : ne le collectez que là où il se justifie.

Champs d’ingestion de fichiers

Pour les charges fondées sur des fichiers, ajoutez les compteurs de fichiers : files_discovered, files_processed, files_skipped, files_failed et bytes_processed. Laissez-les à null pour les charges issues de bases de données ; ils sont facultatifs par conception. Le détail par fichier (quel fichier a échoué, sa somme de contrôle, la raison) a sa place dans la table des fichiers traités ou la table d’événements, pas en colonnes ici.

Une ligne par exécution, pas par enregistrement

Le journal d’exécution enregistre des exécutions, pas des données. Une ligne par exécution de pipeline, de notebook ou de validation. Journaliser une ligne par enregistrement source, par ligne de fichier ou par itération de boucle transforme une petite table opérationnelle en une table volumineuse et lente que personne ne peut interroger pendant un incident.

Quand vous avez besoin d’un détail plus fin, comme les jalons d’un long notebook, le résultat par fichier ou des métriques intermédiaires, ajoutez une seconde table facultative.

La table d’événements facultative

Requête SQL: La table d’événements facultativeT-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 lignesAffichage en lecture seule. Aucune connexion à une base de données.

Elle est utile quand une même exécution comporte des phases distinctes qui méritent d’être chronométrées (extraction, transformation, écriture), quand le résultat par fichier compte, ou quand vous voulez des avertissements qui ne font pas échouer l’exécution. Gardez-la bornée : quelques événements par exécution, pas un flux. Si vous écrivez des centaines d’événements par exécution, c’est un outil de traçage ou de journalisation qu’il vous faut, pas une table.

  1. correlation_idOpération métierUne par date métier ou par lot
  2. execution_idTable d’exécution
    • parent_execution_id
    • statut et durée
    • lignes et watermark
    • résumé d’erreur
  3. execution_idTable d’événements (facultative)
    • jalons
    • métriques
    • avertissements
    • détail des erreurs
Le modèle de données du journal d’exécution. correlation_id regroupe les exécutions en une opération métier, parent_execution_id construit l’arbre, et la table d’événements facultative se rattache à execution_id.

Requêtes opérationnelles

Ces requêtes s’exécutent sur l’implémentation SQL database ; la version Delta est identique, sur execution_log_current.

Requête SQL: Requêtes opérationnellesT-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 lignesAffichage en lecture seule. Aucune connexion à une base de données.

Le seuil de six heures de la requête 3 n’est qu’un exemple : fondez-le sur la plus longue durée normale de chaque charge. L’article sur la supervision ajoute le contrôle complémentaire sur la table de watermarks elle-même.

Rétention

Il n’existe pas de durée de rétention universelle. Elle dépend :

  • des besoins de dépannage : jusqu’où vous remontez pour comparer quand une charge ralentit ;
  • des fenêtres de réexécution et de rechargement : il vous faut le journal au moins aussi longtemps que vous pourriez réexécuter ;
  • des exigences d’audit et réglementaires : certains flux de données doivent prouver ce qui s’est exécuté, et quand ;
  • du volume : quelques centaines d’exécutions par jour, c’est minuscule ; des milliers avec des événements détaillés, non.

Un modèle courant consiste à conserver la table d’exécution bien plus longtemps que la table d’événements : une ligne par exécution reste petite pendant des années, alors que le détail des événements sert surtout pour les incidents récents. Conservez encore plus longtemps des résumés agrégés (percentiles quotidiens de durée, nombre d’échecs) si vous avez besoin de tendances longues.

Conception physique

Les modes d’interrogation sont prévisibles : recherche par execution_id, regroupement par correlation_id, filtre par status et période, tendance par charge et période. La façon de les servir dépend de l’emplacement :

  • SQL database dans Fabric / Azure SQL : la conception SQL Server habituelle s’applique. Une clé clusterisée étroite sur un log_id croissant garde des insertions peu coûteuses ; une contrainte d’unicité sur execution_id ; des index non clusterisés sur (correlation_id, start_time), (status, start_time) et les colonnes de charge, comme dans le schéma ci-dessus. Évitez de clusteriser sur un UUID aléatoire.
  • Delta dans un Lakehouse : il n’y a pas d’index. La table reste assez petite pour que cela compte rarement ; gardez les fichiers compactés et, si elle grossit un jour, organisez-la par date plutôt que par ID. Les tables Delta pour les ingénieurs SQL Server (en anglais) explique pourquoi les réflexes d’indexation ne se transposent pas.
  • Fabric Warehouse : pas d’index créés par l’utilisateur ; le moteur gère les statistiques et le compactage, et le clustering des données est le levier d’organisation disponible. La question des écritures au compte-gouttes évoquée plus haut compte davantage que l’indexation.

Articulation avec la supervision

Les deux articles de Javi Builds se répartissent volontairement le travail :

  • Le journal d’exécution est le contexte durable de la charge : ce que chaque exécution devait faire, ce qu’elle a fait et comment elle se rattache au reste de l’opération.
  • La supervision est l’usage opérationnel de ce contexte, avec l’historique des exécutions de Fabric, les résultats de validation et l’historique de la capacité : alertes, références, investigations.

Autres articles liés :

Liste de contrôle pour la production

  • Un seul emplacement pour toute la plateforme, adapté aux petites écritures fréquentes.
  • Chaque exécution écrit un enregistrement : pipelines, pipelines enfants, Copy jobs, notebooks, validation.
  • Identifiants séparés : execution_id par enregistrement, parent_execution_id pour l’arbre, un correlation_id par opération métier.
  • ID de corrélation créé une seule fois par l’orchestrateur de plus haut niveau et transmis vers le bas ; déterministe, pour que les réexécutions le partagent.
  • ID d’exécution transmis explicitement des pipelines aux notebooks, en paramètres.
  • Enregistrements de début et de fin écrits ; exceptions relancées après journalisation.
  • Transitions de statut appliquées : un enregistrement terminé ne change jamais ; les réexécutions reçoivent de nouveaux enregistrements.
  • Nouvelles tentatives et réexécutions distinguées : retry_count ou rerun_of_execution_id.
  • Nombres de lignes précis et, pour les chargements incrémentiels, bornes de fenêtre et watermark_advanced.
  • Exécutions abandonnées détectées et clôturées.
  • Aucun secret dans les erreurs ni les paramètres ; entrées et sorties sensibles des activités marquées comme sécurisées.
  • Une ligne par exécution, avec une table d’événements facultative et bornée pour le détail.
  • Rétention décidée pour chaque table, selon les besoins de dépannage, de réexécution et d’audit.

Une fois le journal en place, l’étape suivante de ce parcours le met à l’épreuve : Déboguer les pipelines et notebooks Microsoft Fabric en production (en anglais) utilise ces identifiants pour remonter d’une exécution en échec, lente ou erronée jusqu’à sa cause.

Étiquettes

  • Observabilité
  • Supervision
  • Journalisation
  • Pipelines de données
  • Microsoft Fabric
  • PySpark