Informes de estado de ingesta de Kusto.Ingest

  • Artículo

En este artículo se explica cómo usar las características de IKustoQueuedIngestClient para realizar un seguimiento del estado de una solicitud de ingesta.

Clases de descripción

Estas clases de descripción contienen detalles importantes sobre los datos de origen que se van a ingerir y deben usarse en la operación de ingesta.

  • SourceDescription
  • DataReaderDescription
  • StreamDescription
  • FileDescription
  • BlobDescription

Todas las clases se derivan de la clase SourceDescriptionabstracta y se usan para crear instancias de un identificador único para cada origen de datos. A continuación, cada identificador se usará para el seguimiento de estado y se mostrará en todos los informes, seguimientos y excepciones relacionados con la operación pertinente.

Clase SourceDescription

Los conjuntos de datos grandes se dividirán en fragmentos de 1 GB y cada parte se ingerirá por separado. A continuación, el mismo SourceId se aplicará a todas las operaciones de ingesta originadas en el mismo conjunto de datos.

public abstract class SourceDescription
{
    public Guid? SourceId { get; set; }
}

Clase DataReaderDescription

public class DataReaderDescription : SourceDescription
{
    public  IDataReader DataReader { get; set; }
}

Clase StreamDescription

public class StreamDescription : SourceDescription
{
    public Stream Stream { get; set; }
}

Clase FileDescription

public class FileDescription : SourceDescription
{
    public string FilePath { get; set; }
}

Clase BlobDescription

public class BlobDescription : SourceDescription
{
    public string BlobUri { get; set; }
    // Setting the Blob size here is important, as this saves the client the trouble of probing the blob for size
    public long? BlobSize { get; set; }
}

Representación del resultado de la ingesta

IKustoIngestionResult de la interfaz

Esta interfaz captura el resultado de una sola operación de ingesta en cola y se puede recuperar mediante SourceId.

public interface IKustoIngestionResult
{
    // Retrieves the detailed ingestion status of the ingestion source with the given sourceId.
    IngestionStatus GetIngestionStatusBySourceId(Guid sourceId);

    // Retrieves the detailed ingestion status of all data ingestion operations into Kusto associated with this IKustoIngestionResult instance.
    IEnumerable<IngestionStatus> GetIngestionStatusCollection();
}

Clase IngestionStatus

IngestionStatus contiene un estado completo de una sola operación de ingesta.

public class IngestionStatus
{
    // The ingestion status returns from the service. Status remains 'Pending' during the ingestion process and
    // is updated by the service once the ingestion completes. When <see cref="IngestionReportMethod"/> is set to 'Queue' the ingestion status
    // will always be 'Queued' and the caller needs to query the report queues for ingestion status, as configured. To query statuses that were
    // reported to queue, see: <see href="https://learn.microsoft.com/azure/kusto/api/netfx/kusto-ingest-client-status#ingestion-status-in-azure-queue"/>.
    // When <see cref="IngestionReportMethod"/> is set to 'Table', call <see cref="IKustoIngestionResult.GetIngestionStatusBySourceId"/> or
    // <see cref="IKustoIngestionResult.GetIngestionStatusCollection"/> to retrieve the most recent ingestion status.
    public Status Status { get; set; }
    // A unique identifier representing the ingested source. Can be supplied during the ingestion execution.
    public Guid IngestionSourceId { get; set; }
    // The URI of the blob, potentially including the secret needed to access the blob.
    // This can be a filesystem URI (on-premises deployments only), or an Azure Blob Storage URI (including a SAS key or a semicolon followed by the account key)
    public string IngestionSourcePath { get; set; }
    // The name of the database holding the target table.
    public string Database { get; set; }
    // The name of the target table into which the data will be ingested.
    public string Table { get; set; }
    // The last updated time of the ingestion status.
    public DateTime UpdatedOn { get; set; }
    // The ingestion's operation Id.
    public Guid OperationId { get; set; }
    // The ingestion operation activity Id.
    public Guid ActivityId { get; set; }
    // In case of a failure - indicates the failure's error code.
    public IngestionErrorCode ErrorCode { get; set; }
    // In case of a failure - indicates the failure's status.
    public FailureStatus FailureStatus { get; set; }
    // In case of a failure - indicates the failure's details.
    public string Details { get; set; }
    // In case of a failure - indicates whether or not the failures originate from an Update Policy.
    public bool OriginatesFromUpdatePolicy { get; set; }
}

Enumeración de estado

Valor Significado Temporal o permanente
Pending El valor puede cambiar durante el transcurso de la ingesta, en función del resultado de la operación de ingesta. Temporales
Correcto Los datos se han ingerido correctamente Permanente
Con error Error de ingesta Permanente
En cola Los datos se han puesto en cola para la ingesta Permanente
Omitido No se proporcionó ningún dato y se omitió la operación de ingesta. Permanente
ParcialmenteSucceeded Parte de los datos se ingerió correctamente, mientras que se produjo un error Permanente

Seguimiento del estado de ingesta (KustoQueuedIngestClient)

IKustoQueuedIngestClient es un cliente "fire-and-forget". La operación de ingesta en el lado cliente finaliza publicando un mensaje en una cola de Azure. Después de la publicación, se realiza el trabajo del cliente. Para la comodidad del usuario cliente, KustoQueuedIngestClient proporciona un mecanismo para realizar un seguimiento del estado de ingesta individual. Este mecanismo no está pensado para el uso masivo en canalizaciones de ingesta de alto rendimiento. Este mecanismo es para la ingesta de precisión cuando la tasa es relativamente baja y los requisitos de seguimiento son estrictos.

Advertencia

Debe evitarse activar notificaciones positivas para cada solicitud de ingesta de flujos de datos de gran volumen, ya que esto coloca una carga extrema en los recursos xStore subyacentes, lo que podría provocar un aumento de la latencia de ingesta e incluso una capacidad de respuesta completa del clúster.

Las siguientes propiedades (establecidas en KustoQueuedIngestionProperties) controlan el nivel y el transporte para las notificaciones correctas o de error de ingesta.

Enumeración IngestionReportLevel

public enum IngestionReportLevel
{
    FailuresOnly = 0,
    None,
    FailuresAndSuccesses
}

Enumeración IngestionReportMethod

public enum IngestionReportMethod
{
    Queue = 0,
    Table,
    QueueAndTable
}

Para realizar un seguimiento del estado de la ingesta, proporcione lo siguiente a IKustoQueuedIngestClient con el que realiza la operación de ingesta:

  1. Establezca IngestionReportLevella propiedad en el nivel necesario de informe. Ya sea FailuresOnly (que es el valor predeterminado) o FailuresAndSuccesses. Cuando se establece Noneen , no se notificará nada al final de la ingesta.
  2. Especifique , IngestionReportMethodTable - Queueo .QueueAndTable

Puede encontrar un ejemplo de uso en la página Ejemplos de Kusto.Ingest .

Estado de ingesta en la tabla de Azure

La IKustoIngestionResult interfaz que se devuelve de cada operación de ingesta contiene funciones que se pueden usar para consultar el estado de la ingesta. Preste especial atención a la Status propiedad de los objetos devueltos IngestionStatus :

  • Pending indica que el origen se ha puesto en cola para la ingesta y que aún no se ha actualizado. Use la función de nuevo para consultar el estado del origen.
  • Succeeded indica que el origen se ha ingerido correctamente.
  • Failed indica que no se pudo ingerir el origen

Nota

La obtención de un Queued estado indica que se ha dejado en IngestionReportMethod su valor predeterminado de "Queue". Se trata de un estado permanente y volver a invocar las GetIngestionStatusBySourceId funciones o GetIngestionStatusCollection , siempre dará como resultado el mismo estado "En cola". Para comprobar el estado de una ingesta en una tabla de Azure, antes de la ingesta, compruebe que la IngestionReportMethod propiedad de KustoQueuedIngestionProperties está establecida Tableen . Si también desea que el estado de ingesta se notifique a una cola, establezca el estado QueueAndTableen .

Estado de ingesta en la cola de Azure

Los IKustoIngestionResult métodos solo son relevantes para comprobar un estado en una tabla de Azure. Para consultar los estados notificados a una cola de Azure, use los siguientes métodos IKustoQueuedIngestClient .

Método Propósito
PeekTopIngestionFailures Método asincrónico que devuelve información sobre los primeros errores de ingesta que aún no se han descartado debido al límite de mensajes solicitados
GetAndDiscardTopIngestionFailures Método asincrónico que devuelve y descarta los errores de ingesta más antiguos que aún no se han descartado debido al límite de mensajes solicitados
GetAndDiscardTopIngestionSuccesses Método asincrónico que devuelve y descarta los primeros éxitos de ingesta que aún no se han descartado debido al límite de mensajes solicitados. Este método solo es relevante si se establece en IngestionReportLevel . FailuresAndSuccesses

Errores de ingesta recuperados de la cola de Azure

Los errores de ingesta se representan mediante el IngestionFailure objeto que contiene información útil sobre el error.

Propiedad Significado
Tabla de & de base de datos Los nombres de base de datos y tablas previstos
IngestionSourcePath Ruta de acceso del blob ingerido. Contendrá el nombre de archivo original si se ingiere el archivo. Será aleatorio si Se ingiere DataReader
FailureStatus Permanent (no se ejecutará ningún reintento), Transient (se ejecutará el reintento) o Exhausted (también se producirá un error en varios reintentos).
OperationId & RootActivityId Identificador de la operación y Id. de rootActivity de la ingesta (útil para solucionar problemas adicionales)
FailedOn Hora UTC del error. Será mayor que el momento en que se llamó al método de ingesta, ya que los datos se agregan antes de ejecutar la ingesta.
Detalles Otros detalles relativos al error (si existen)
ErrorCode IngestionErrorCode enumeración , representa el código de error de ingesta, si se produjo un error.