Exportación del historial de orquestación con Durable Task Scheduler (versión preliminar)

La característica de exportación del historial de orquestación permite a la aplicación extraer historiales de ejecución para instancias de orquestación terminal (estado completado, erróneo o terminado) del Programador de Tareas Durable y los escriba en Azure Blob Storage. Use esta característica para auditar, cumplir, analizar y archivar datos de orquestación a largo plazo fuera del programador.

Cómo funciona la exportación del historial de orquestación

El historial de exportación usa entidades y orquestaciones duraderas de forma interna para administrar trabajos de exportación de forma fiable a través del siguiente proceso.

1. Se crea un trabajo de exportación a través de ExportHistoryClient, especificando un período de tiempo y un modo de exportación.
2. El SDK crea una entidad duradera (ExportJob) que realiza un seguimiento del estado y el progreso del trabajo.
3. Una orquestación interna enumera las instancias de orquestación de terminales que coinciden con el período de tiempo y los filtros de estado especificados.
4. Para cada instancia coincidente, una actividad captura el historial de ejecución completo de Durable Task Scheduler.
5. El historial se serializa (JSONL con compresión gzip de forma predeterminada) y se escribe en Azure Blob Storage.
6. El trabajo hacer guardados del progreso, por lo que puede reanudarse si se interrumpe.

Modos de exportación para trabajos por lotes y continuos

El historial de exportación admite dos modos:

Prerrequisitos

• SDK de .NET 8 o posterior
• Un centro de tareas Programador de Tareas Durable (o el emulador local)
• Una cuenta de Azure Storage (o Azurite para el desarrollo local)
• Los siguientes paquetes NuGet:
  • Microsoft.DurableTask.ExportHistory
  • Microsoft.DurableTask.Client.AzureManaged
  • Microsoft.DurableTask.Worker.AzureManaged

Habilitación de la exportación del historial de orquestación

1. Instale el paquete del historial de exportación.

   dotnet add package Microsoft.DurableTask.ExportHistory
   

2. Instale el Azure cliente administrado y los paquetes de trabajo para Durable Task Scheduler.

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

3. Registra el historial de exportación tanto en el trabajador como en el cliente.

   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");
       });
   });
   

Creación y administración de trabajos de exportación

Después de habilitar el historial de exportación, use el ExportHistoryClient para crear y administrar trabajos.

Creación de un trabajo de exportación por lotes

En el ejemplo siguiente, un trabajo de exportación por lotes exporta todas las instancias de orquestación que alcanzaron un estado de terminal dentro de un período de tiempo fijo.

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();

Creación de un trabajo de exportación continua

En el ejemplo siguiente, un trabajo de exportación continuo supervisa indefinidamente las instancias del terminal a partir de una hora de inicio.

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

ExportHistoryJobClient jobClient = await exportClient.CreateJobAsync(options);

Cuando destination es null, el trabajo usa el contenedor predeterminado y el prefijo configurados en ExportHistoryStorageOptions.

Obtener detalles del trabajo de exportación

Use el código siguiente para recuperar la descripción completa de un trabajo, incluidos su estado, contadores de progreso y errores.

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

La ExportJobDescription incluye lo siguiente:

Enumerar trabajos

Exporte una lista de trabajos activos mediante código similar al ejemplo siguiente.

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)");
}

ExportJobQuery admite las siguientes propiedades de filtro:

Eliminación de un trabajo

Use el código siguiente para eliminar un trabajo.

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

Exportar opciones de creación de trabajos

La ExportJobCreationOptions clase controla el comportamiento del trabajo de exportación e incluye los parámetros siguientes.

Dónde se almacenan los datos exportados en Azure Blob Storage

El historial exportado se escribe en Azure Blob Storage con los parámetros siguientes.

• Contenedor: valor predeterminado de EXPORT_HISTORY_CONTAINER_NAME o la invalidación de destination por trabajo.
• Nombre de blob: derivado de un hash SHA-256 de (completedTimestamp, instanceId).
• Formato de archivo:
  • Valor predeterminado: .jsonl.gz (Líneas JSON, gzip-compressed: un evento de historial por línea)
  • Opcional: .json (matriz JSON sin comprimir de eventos de historial)
• Ruta de acceso de blob con prefijo: cuando se configura un prefijo (por ejemplo, exports/daily), la ruta de acceso del blob se convierte en exports/daily/{hash}.{ext}. Sin un prefijo, el blob se escribe directamente en la raíz del contenedor como {hash}.{ext}.

Cada blob incluye una instanceId etiqueta de metadatos para la rastreabilidad.

Variables de entorno para la configuración del historial de exportación

Use estas variables de entorno con el ejemplo de historial de exportación de Durable Task .NET SDK.

permisos de Azure para el historial de exportación

Al usar Azure recursos en lugar de emuladores locales, la identidad de la aplicación necesita acceso a Durable Task Scheduler y Blob Storage:

1. Conceda Durable Task Data Contributor en el centro de tareas de la aplicación.
2. Asigne el rol Storage Blob Data Contributor en la cuenta de almacenamiento que almacene los blobs del historial exportado.

Consideraciones importantes para los trabajos de exportación

• Operaciones de purga simultáneas:
  Si purga instancias de orquestación mientras se ejecuta un trabajo de exportación, la exportación puede verse afectada. Las instancias que se purgan antes de que la exportación las lea estarán ausentes de los datos exportados. Evite ejecutar operaciones de purga simultáneamente con trabajos de exportación activos que cubran la misma ventana de tiempo.

• Limpieza de blobs:
  Al eliminar un trabajo de exportación no se quitan los blobs exportados de Azure Blob Storage. Si necesita quitar los datos exportados, elimine los blobs de la cuenta de almacenamiento por separado.

Verifica que la exportación funcione

Después de crear un trabajo de exportación, compruebe que funciona comprobando ambas señales:

• El estado del trabajo pasa de Pending a Active y finalmente a Completed (para el modo Batch).
• Las entradas de blob aparecen en el contenedor de exportación configurado.

Puede sondear el estado del trabajo mediante programación:

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);

Para el desarrollo local, ejecute este comando CLI de Azure para inspeccionar el contenedor:

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

Pasos siguientes

• Ejemplo de historial de exportación del SDK Durable Task .NET
• Creación de una aplicación con los SDK de Durable Task