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.
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.
- correlation_idOpération métiersales-daily:2026-10-24
- execution_idPipeline parent= @pipeline().RunId
- Pipeline enfant ou Copy jobparent_execution_id = pipeline parent
- Notebookparent_execution_id = pipeline parent
- Validationparent_execution_id = pipeline parent
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écutionparent_execution_id: l’execution_idde l’appelant ; null pour l’exécution de plus haut niveaucorrelation_id: l’opération métierrerun_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,validationpipeline_name,notebook_name: l’élément exécutépipeline_run_id: l’ID d’exécution Fabric, pour les enregistrements de pipelinespark_activity_id: l’ID du job Livy de la session du notebook, issu du contexte d’exécutiontrigger_type:scheduled,manual,rerun,event
Durée
start_time,end_time,duration_ms
Statut
status:started,succeeded,failed,cancelled,timed_outretry_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_rejectedrows_inserted,rows_updated,rows_deleted: issus des métriques duMERGEfiles_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
INSERTetUPDATEligne à 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,UPDATEetDELETEau 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)
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 é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 :
-- 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 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.
-- 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;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 :
- Créer l’ID d’exécution.
- Écrire un enregistrement
started. - Exécuter la charge.
- En cas de réussite, écrire
succeededavec les métriques. - En cas d’échec, écrire
failedavec une erreur expurgée. - Relancer l’exception.
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])
raiseLe 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 commeexecution_idetpipeline_run_idde l’enregistrement du pipeline.@pipeline().PipelineName,@pipeline().TriggerTime,@pipeline().TriggerName.@pipeline()?.TriggeredByPipelineRunIdetTriggeredByPipelineName: 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_countsur 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_idetcorrelation_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érationMERGEdans 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
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);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.
- correlation_idOpération métierUne par date métier ou par lot
- execution_idTable d’exécution
- parent_execution_id
- statut et durée
- lignes et watermark
- résumé d’erreur
- execution_idTable d’événements (facultative)
- jalons
- métriques
- avertissements
- détail des erreurs
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.
-- 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';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_idcroissant garde des insertions peu coûteuses ; une contrainte d’unicité surexecution_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 :
- Pipelines, notebooks, Dataflow Gen2 ou Copy Job (en anglais) explique quel outil possède chaque étape, ce qui détermine qui écrit quels enregistrements.
- La capacité Microsoft Fabric expliquée (en anglais) sert de complément quand une exécution est lente pour des raisons extérieures à son propre code, et le diagnostic d’un problème de saturation de capacité Fabric (en anglais) montre le journal utilisé pour expliquer un pic de capacité.
- CI/CD Microsoft Fabric avec fabric-cicd couvre le déploiement du code de journalisation lui-même ; gardez l’emplacement du journal et ses paramètres propres à chaque environnement.
- Utiliser les session tags dans les pipelines Fabric est utile quand vous journalisez
spark_activity_id: des notebooks étiquetés peuvent partager une session, si bien que plusieurs exécutions peuvent signaler la même session tout en gardant des ID d’exécution distincts. - Les fiches Superviser les pipelines et notebooks Fabric et Déboguer les pipelines Fabric sont des aide-mémoire pour exploiter le journal pendant un incident, et la liste de contrôle de la supervision d’une plateforme de données (en anglais) couvre la revue plus large.
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_idpar enregistrement,parent_execution_idpour l’arbre, uncorrelation_idpar 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_countourerun_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.
Ce contenu vous a-t-il été utile ?
Que pourrions-nous améliorer ?
Merci — cela m’aide à améliorer Javi Builds.
Continuer à apprendre
- Aide-mémoireSuperviser les pipelines et notebooks FabricSupervisez les pipelines et notebooks Microsoft Fabric avec le Monitoring hub, Workspace Monitoring, la supervision Spark, KQL, les alertes et la télémétrie de capacité afin de rendre observables les échecs et les régressions de performances.Ouvrir l’aide-mémoire
- ArticleSuperviser une plateforme de données : que faut-il vraiment mesurer ?Un modèle pratique de supervision qui relie clients, applications, API, moteurs de rapports, plateformes de données, calcul et stockage.Lire l’article
Que devrais-je créer ensuite ?
Je développe Javi Builds autour des problèmes concrets rencontrés par les data engineers. Dites-moi quel sujet vous aimeriez voir ensuite.
Restez au courant
Recevez uniquement les nouvelles de Javi Builds qui vous intéressent.
Consultez votre boîte de réception
Je vous ai envoyé un lien de confirmation. Votre abonnement sera actif après confirmation.