Kusto.Ingestion status reporting

Article
01/09/2024

Cet article explique comment utiliser les fonctionnalités IKustoQueuedIngestClient pour suivre les status d’une demande d’ingestion.

Classes description

Ces classes de description contiennent des détails importants sur les données sources à ingérer et doivent être utilisées dans l’opération d’ingestion.

SourceDescription
DataReaderDescription
StreamDescription
FileDescription
BlobDescription

Les classes sont toutes dérivées de la classe SourceDescriptionabstraite et sont utilisées pour instancier un identificateur unique pour chaque source de données. Chaque identificateur sera ensuite utilisé pour status suivi et s’affichera dans tous les rapports, traces et exceptions liés à l’opération appropriée.

SourceDescription de la classe

Les jeux de données volumineux seront divisés en blocs de 1 Go et chaque partie sera ingérée séparément. Le même SourceId s’applique ensuite à toutes les opérations d’ingestion provenant du même jeu de données.

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

DataReaderDescription, classe

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

StreamDescription de la classe

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

FileDescription de classe

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

BlobDescription de classe

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

Représentation des résultats d’ingestion

Interface IKustoIngestionResult

Cette interface capture le résultat d’une seule opération d’ingestion en file d’attente et peut être récupérée par 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();
}

Classe IngestionStatus

IngestionStatus contient une status complète d’une seule opération d’ingestion.

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

Énumération d’état

Valeur	Signification	Temporaire/Permanent
Pending	La valeur peut changer au cours de l’ingestion, en fonction du résultat de l’opération d’ingestion	Temporaire
Opération réussie	Les données ont été correctement ingérées	Permanent
Échec	Échec de l’ingestion	Permanent
Mis en file d'attente.	Les données ont été mises en file d’attente pour l’ingestion	Permanent
Ignoré	Aucune donnée n’a été fournie et l’opération d’ingestion a été ignorée	Permanent
Partiellementuccé	Une partie des données a été correctement ingérée, tandis que certaines ont échoué	Permanent

Suivi de l’état d’ingestion (KustoQueuedIngestClient)

IKustoQueuedIngestClient est un client « fire-and-forget ». L’opération d’ingestion côté client se termine par la publication d’un message dans une file d’attente Azure. Après la publication, le travail du client est terminé. Pour la commodité de l’utilisateur client, KustoQueuedIngestClient fournit un mécanisme de suivi des status d’ingestion individuelles. Ce mécanisme n’est pas destiné à une utilisation en masse sur les pipelines d’ingestion à haut débit. Ce mécanisme est destiné à l’ingestion de précision lorsque le taux est relativement faible et que les exigences de suivi sont strictes.

Avertissement

L’activation de notifications positives pour chaque demande d’ingestion pour les flux de données de gros volumes doit être évitée, car cela place une charge extrême sur les ressources xStore sous-jacentes, ce qui peut entraîner une latence d’ingestion accrue et même une non-réactivité complète du cluster.

Les propriétés suivantes (définies sur KustoQueuedIngestionProperties) contrôlent le niveau et le transport pour les notifications de réussite ou d’échec d’ingestion.

IngestionReportLevel, énumération

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

IngestionReportMethod, énumération

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

Pour suivre l’status de votre ingestion, fournissez les informations suivantes au IKustoQueuedIngestClient avec lequel vous effectuez l’opération d’ingestion :

Définissez IngestionReportLevella propriété sur le niveau de rapport requis. ( FailuresOnly qui est la valeur par défaut) ou FailuresAndSuccesses. Lorsque la valeur est définie Nonesur , rien n’est signalé à la fin de l’ingestion.
Spécifiez , IngestionReportMethodTable - Queueou .QueueAndTable

Vous trouverez un exemple d’utilisation dans la page Exemples Kusto.Ingest .

Ingestion status dans la table Azure

L’interface IKustoIngestionResult retournée à partir de chaque opération d’ingestion contient des fonctions qui peuvent être utilisées pour interroger les status de l’ingestion. Portez une attention particulière à la Status propriété des objets retournés IngestionStatus :

Pending indique que la source a été mise en file d’attente pour l’ingestion et qu’elle n’a pas encore été mise à jour. Utilisez à nouveau la fonction pour interroger le status de la source
Succeeded indique que la source a été ingérée avec succès
Failed indique que la source n’a pas pu être ingérée

Notes

L’obtention d’un Queued status indique que le IngestionReportMethod a été laissé à sa valeur par défaut « File d’attente ». Il s’agit d’une status permanente et l’appel GetIngestionStatusBySourceId des fonctions ou GetIngestionStatusCollection entraîne toujours les mêmes status « Mis en file d’attente ». Pour case activée la status d’une ingestion dans une table Azure, avant d’ingérer, vérifiez que la IngestionReportMethod propriété de KustoQueuedIngestionProperties a la Tablevaleur . Si vous souhaitez également que l’ingestion status soit signalée à une file d’attente, définissez le status sur QueueAndTable.

Ingestion status dans la file d’attente Azure

Les IKustoIngestionResult méthodes sont uniquement pertinentes pour la vérification d’un status dans une table Azure. Pour interroger les états signalés à une file d’attente Azure, utilisez les méthodes IKustoQueuedIngestClient suivantes.

Méthode	Objectif
PeekTopIngestionFailures	Méthode asynchrone qui retourne des informations sur les échecs d’ingestion les plus anciens qui n’ont pas encore été ignorés en raison de la limite pour les messages demandés
GetAndDiscardTopIngestionFailures	Méthode asynchrone qui retourne et ignore les échecs d’ingestion les plus anciens qui n’ont pas déjà été ignorés en raison de la limite pour les messages demandés
GetAndDiscardTopIngestionSuccesses	Méthode asynchrone qui retourne et ignore les premiers succès d’ingestion qui n’ont pas déjà été ignorés en raison de la limite pour les messages demandés. Cette méthode n’est pertinente que si est `IngestionReportLevel` défini sur `FailuresAndSuccesses`

Échecs d’ingestion récupérés à partir de la file d’attente Azure

Les échecs d’ingestion sont représentés par l’objet IngestionFailure qui contient des informations utiles sur l’échec.

Propriété	Signification
Table de & de base de données	Noms de base de données et de table prévus
IngestionSourcePath	Chemin d’accès de l’objet blob ingéré. Contient le nom de fichier d’origine si le fichier est ingéré. Sera aléatoire si DataReader est ingéré
FailureStatus	`Permanent` (aucune nouvelle tentative ne sera exécutée), `Transient` (nouvelle tentative sera exécutée) ou `Exhausted` (plusieurs tentatives ont également échoué)
OperationId & RootActivityId	ID d’opération et ID RootActivity de l’ingestion (utile pour la résolution des problèmes)
FailedOn	Heure UTC de l’échec. Est supérieur à l’heure à laquelle la méthode d’ingestion a été appelée, car les données sont agrégées avant d’exécuter l’ingestion
Détails	Autres détails concernant l’échec (le cas échéant)
ErrorCode	`IngestionErrorCode` énumération, représente le code d’erreur d’ingestion, en cas d’échec

Partager via