Exporter l'historique de l'orchestration avec Durable Task Scheduler (aperçu)

La fonctionnalité d’exportation de l’historique d’orchestration permet à votre application d’extraire les historiques d’exécution des instances d’orchestration de terminal (terminées, ayant échoué ou arrêtées) à partir de Planificateur de tâchesdurable et de les écrire dans Stockage Blob Azure. Utilisez cette fonctionnalité pour l’audit, la conformité, l’analytique et l’archivage à long terme des données d’orchestration en dehors du planificateur.

Comment fonctionne l'exportation de l'historique d'orchestration

L’historique des exportations utilise des orchestrations et des entités durables en interne pour gérer les travaux d’exportation de manière fiable avec le processus suivant.

1. Vous créez un travail d’exportation via la ExportHistoryClient, en spécifiant une fenêtre de temps et un mode d’exportation.
2. Le SDK crée une entité durable (ExportJob) qui suit l’état et la progression du travail.
3. Une orchestration interne répertorie les instances d’orchestration de terminal qui correspondent à la fenêtre de temps et aux filtres d’état spécifiés.
4. Pour chaque instance correspondante, une activité extrait l’historique d’exécution complet de Durable Task Scheduler.
5. L’historique est sérialisé (JSONL avec compression gzip par défaut) et écrit dans Stockage Blob Azure.
6. Le travail contrôle sa progression, de sorte qu’il puisse reprendre en cas d’interruption.

Modes d’exportation pour les travaux par lots et continus

L’historique des exportations prend en charge deux modes :

Prerequisites

• .NET 8 SDK ou version ultérieure
• Un hub de tâches du planificateur de tâches durable (ou l’émulateur local)
• Un compte stockage Azure (ou Azurite pour le développement local)
• Les packages NuGet suivants :
  • Microsoft.DurableTask.ExportHistory
  • Microsoft.DurableTask.Client.AzureManaged
  • Microsoft.DurableTask.Worker.AzureManaged

Activer l’exportation de l’historique d’orchestration

1. Installez le paquet d'historique d'exportation.

   dotnet add package Microsoft.DurableTask.ExportHistory
   

2. Installez les packages de Azure client managé et de travail pour Durable Task Scheduler.

   dotnet add package Microsoft.DurableTask.Client.AzureManaged
   dotnet add package Microsoft.DurableTask.Worker.AzureManaged
   

3. Enregistrez l'historique d'exportation à la fois sur le travailleur et le client.

   using Microsoft.DurableTask.Client;
   using Microsoft.DurableTask.Client.AzureManaged;
   using Microsoft.DurableTask.ExportHistory;
   using Microsoft.DurableTask.Worker;
   using Microsoft.DurableTask.Worker.AzureManaged;
   
   string connectionString = builder.Configuration.GetValue<string>("DURABLE_TASK_CONNECTION_STRING")
       ?? throw new InvalidOperationException("Missing DURABLE_TASK_CONNECTION_STRING");
   
   string storageConnectionString = builder.Configuration.GetValue<string>("EXPORT_HISTORY_STORAGE_CONNECTION_STRING")
       ?? throw new InvalidOperationException("Missing EXPORT_HISTORY_STORAGE_CONNECTION_STRING");
   
   string containerName = builder.Configuration.GetValue<string>("EXPORT_HISTORY_CONTAINER_NAME")
       ?? throw new InvalidOperationException("Missing EXPORT_HISTORY_CONTAINER_NAME");
   
   // Register the worker with export history support.
   // This registers internal entities, orchestrations, and activities that manage export jobs.
   builder.Services.AddDurableTaskWorker(worker =>
   {
       worker.UseDurableTaskScheduler(connectionString);
       worker.UseExportHistory();
   });
   
   // Register the client with export history support.
   // This configures the Azure Blob Storage destination and registers the ExportHistoryClient.
   builder.Services.AddDurableTaskClient(client =>
   {
       client.UseDurableTaskScheduler(connectionString);
       client.UseExportHistory(options =>
       {
           options.ConnectionString = storageConnectionString;
           options.ContainerName = containerName;
   
           // Optional: set a virtual folder path prefix for blob names (for example, "exports/daily").
           // When set, blobs are written to "{prefix}/{hash}.{ext}" instead of "{hash}.{ext}".
           options.Prefix = builder.Configuration.GetValue<string>("EXPORT_HISTORY_PREFIX");
       });
   });
   

Créer et gérer des travaux d’exportation

Après avoir activé l’historique d’exportation, utilisez la ExportHistoryClient commande pour créer et gérer des travaux.

Créer un travail d’exportation par lots

Dans l’exemple suivant, un travail d’exportation par lots exporte toutes les instances d’orchestration qui ont atteint un état terminal dans une fenêtre de temps fixe.

ExportHistoryClient exportClient = app.Services.GetRequiredService<ExportHistoryClient>();

ExportJobCreationOptions options = new(
    mode: ExportMode.Batch,
    completedTimeFrom: DateTimeOffset.UtcNow.AddHours(-24),
    completedTimeTo: DateTimeOffset.UtcNow,
    destination: new ExportDestination("my-export-container")
    {
        // Virtual folder path prefix applied to all blob names for this job
        Prefix = "exports/daily",
    });

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);
ExportJobDescription description = await jobClient.DescribeAsync();

Créer un travail d’exportation continue

Dans l’exemple suivant, une tâche d’exportation continue suit en permanence les instances de terminal à partir d’une heure de départ.

ExportJobCreationOptions options = new(
    mode: ExportMode.Continuous,
    completedTimeFrom: DateTimeOffset.UtcNow,
    completedTimeTo: null,
    destination: null);

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);

Quand destination est nul, la tâche utilise le conteneur et le préfixe par défaut configurés dans ExportHistoryStorageOptions.

Obtenir les détails de la tâche d’exportation

Utilisez le code suivant pour récupérer la description complète d’un travail, y compris son état, ses compteurs de progression et toutes les erreurs.

ExportJobDescription? job = await exportClient.GetJobAsync("my-job-id");

Les ExportJobDescription comprennent :

Liste des emplois

Exportez une liste de travaux actifs à l’aide du code similaire à l’exemple suivant.

ExportJobQuery query = new()
{
    Status = ExportJobStatus.Active,
    CreatedFrom = DateTimeOffset.UtcNow.AddDays(-7),
    PageSize = 50,
};

AsyncPageable<ExportJobDescription> jobs = exportClient.ListJobsAsync(query);

await foreach (ExportJobDescription job in jobs)
{
    Console.WriteLine($"{job.JobId}: {job.Status} ({job.ExportedInstances} exported)");
}

Les ExportJobQuery prennent en charge les propriétés de filtre suivantes :

Supprimer un travail

Utilisez le code suivant pour supprimer un travail.

ExportHistoryJobClient jobClient = exportClient.GetJobClient("my-job-id");
await jobClient.DeleteAsync();

Options de création de travaux d’exportation

La ExportJobCreationOptions classe contrôle le comportement du travail d’exportation et inclut les paramètres suivants.

Où les données exportées sont stockées dans Stockage Blob Azure

L’historique exporté est écrit dans Stockage Blob Azure avec les paramètres suivants.

• Conteneur : valeur par défaut provenant de EXPORT_HISTORY_CONTAINER_NAME ou remplacement de destination par travail.
• Nom de l’objet blob : dérivé d’un hachage SHA-256 de (completedTimestamp, instanceId).
• Format de fichier :
  • Valeur par défaut : .jsonl.gz (lignes JSON, gzip-compressed — un événement d’historique par ligne)
  • Facultatif : .json (tableau JSON non compressé d’événements d’historique)
• Chemin d’accès d’objet blob avec préfixe : lorsqu’un préfixe est configuré (par exemple), exports/dailyle chemin d’accès de l’objet blob devient exports/daily/{hash}.{ext}. Sans préfixe, l’objet blob est écrit directement à la racine du conteneur sous la forme {hash}.{ext}.

Chaque objet blob inclut une instanceId balise de métadonnées pour la traçabilité.

Variables d’environnement pour la configuration de l’historique d’exportation

Utilisez ces variables d’environnement avec l’exemple d’historique d’exportation de la tâche durable .NET SDK.

autorisations de Azure pour l’historique d’exportation

Lorsque vous utilisez Azure ressources au lieu d’émulateurs locaux, l’identité de l’application a besoin d’accéder à Durable Task Scheduler et Stockage Blob :

1. Accorder Durable Task Data Contributor sur le hub de tâches de l’application.
2. Accordez Storage Blob Data Contributor sur le compte de stockage qui contient les objets blob d’historique exportés.

Considérations importantes pour les travaux d’exportation

• Opérations de vidage simultanées :
  Si vous videz les instances d’orchestration pendant qu’un travail d’exportation est en cours d’exécution, l’exportation risque d’être affectée. Les instances qui sont supprimées avant que l'exportation ne les lise ne seront pas présentes dans les données exportées. Évitez d’exécuter des opérations de vidage simultanément avec des travaux d’exportation actifs qui couvrent la même fenêtre de temps.

• Nettoyage de blobs :
  La suppression d'un travail d'exportation ne supprime pas les objets blob exportés de Stockage Blob Azure. Si vous devez supprimer des données exportées, supprimez les objets blob du compte de stockage séparément.

Vérifier que l’exportation fonctionne

Après avoir créé un travail d’exportation, vérifiez qu’il fonctionne en vérifiant les deux signaux :

• L’état du travail passe de Pending vers Active et finalement vers Completed (pour le mode Batch).
• Les blobs apparaissent dans votre conteneur d’exportation configuré.

Vous pouvez interroger l’état de la tâche de manière programmatique :

ExportJobDescription? job;
do
{
    await Task.Delay(TimeSpan.FromSeconds(5));
    job = await exportClient.GetJobAsync(jobId);
    Console.WriteLine($"Status: {job?.Status}, Exported: {job?.ExportedInstances}");
}
while (job?.Status is ExportJobStatus.Pending or ExportJobStatus.Active);

Pour le développement local, exécutez cette commande Azure CLI pour inspecter le conteneur :

az storage blob list \
  --connection-string "UseDevelopmentStorage=true" \
  --container-name export-history \
  --output table

Étapes suivantes

• Exemple d'exportation historique de Durable Task .NET SDK
• Créer une application avec les kits SDK Durable Task