Erreurs et exceptions Kusto.Ingest

Article
04/20/2023

Toute erreur pendant la gestion de l’ingestion côté client est indiquée par une exception C#.

Échecs

Exceptions KustoDirectIngestClient

Lors de la tentative d’ingestion à partir de plusieurs sources, des erreurs peuvent se produire pendant le processus d’ingestion. Si une ingestion échoue pour l’une des sources, elle est journalisée et le client continue d’ingérer les sources restantes. Après avoir passé au-dessus de toutes les sources pour l’ingestion, un IngestClientAggregateException est levée, contenant le IList<IngestClientException> IngestionErrors membre .

IngestClientException et ses classes dérivées contiennent un champ IngestionSource et un Error champ. Les deux champs créent ensemble un mappage, à partir de la source qui a échoué l’ingestion, à l’erreur qui s’est produite lors de la tentative d’ingestion. Les informations peuvent être utilisées dans la IngestionErrors liste pour examiner quelles sources ont échoué l’ingestion et pourquoi. L’exception IngestClientAggregateException contient également une propriété GlobalErrorbooléenne , qui indique si une erreur s’est produite pour toutes les sources.

Échecs d’ingestion à partir de fichiers ou d’objets blob

Si un échec d’ingestion se produit lors d’une tentative d’ingestion à partir d’un objet blob ou d’un fichier, les sources d’ingestion ne sont pas supprimées, même si l’indicateur a la deleteSourceOnSuccess valeur true. Les sources sont conservées pour une analyse plus approfondie. Une fois l’origine de l’erreur comprise et si l’erreur ne provient pas de la source d’ingestion elle-même, l’utilisateur du client peut tenter de la réinscrire.

Échecs d’ingestion à partir d’IDataReader

Lors de l’ingestion à partir de DataReader, les données à ingérer sont enregistrées dans un dossier temporaire dont l’emplacement par défaut est <Temp Path>\Ingestions_<current date and time>. Ce dossier par défaut est toujours supprimé après une ingestion réussie.

Dans les IngestFromDataReader méthodes et IngestFromDataReaderAsync , l’indicateur, dont la retainCsvOnFailure valeur par défaut est false, détermine si les fichiers doivent être conservés après une ingestion ayant échoué. Si cet indicateur est défini sur false, les données qui échouent à l’ingestion ne sont pas conservées, ce qui rend difficile la compréhension de ce qui s’est passé.

Exceptions KustoQueuedIngestClient

KustoQueuedIngestClient ingère des données en chargeant des messages dans une file d’attente Azure. Si une erreur se produit avant ou pendant le processus de mise en file d’attente, une IngestClientAggregateException est levée à la fin du processus. L’exception levée inclut une collection de IngestClientException, qui contient la source de chaque échec et qui n’a pas été publiée dans la file d’attente. L’erreur qui s’est produite lors de la tentative de publication du message est également levée.

Échecs de publication dans la file d’attente avec un fichier ou un objet blob en tant que source

Si une erreur se produit lors de l’utilisation KustoQueuedIngestClientdes méthodes de IngestFromFile/IngestFromBlob , les sources ne sont pas supprimées, même si l’indicateur deleteSourceOnSuccess est défini sur true. Au lieu de cela, les sources sont conservées pour une analyse plus approfondie.

Une fois l’origine de l’erreur comprise et si l’erreur ne provient pas de la source d’ingestion elle-même, l’utilisateur du client peut tenter de mettre les données en file d’attente à l’aide des méthodes appropriées IngestFromFile/IngestFromBlob avec la source ayant échoué.

Échecs de publication dans la file d’attente avec IDataReader comme source

Lors de l’utilisation d’une source DataReader, les données à publier dans la file d’attente sont enregistrées dans un dossier temporaire dont l’emplacement par défaut est <Temp Path>\Ingestions_<current date and time>. Ce dossier est toujours supprimé une fois que les données ont été correctement publiées dans la file d’attente. Dans les IngestFromDataReader méthodes et IngestFromDataReaderAsync , l’indicateur, dont la retainCsvOnFailure valeur par défaut est false, détermine si les fichiers doivent être conservés après une ingestion ayant échoué. Si cet indicateur est défini sur false, les données qui échouent à l’ingestion ne sont pas conservées, ce qui rend difficile la compréhension de ce qui s’est passé.

Échecs courants

Error	Motif	Limitation des risques
Le nom> de <la base de données n’existe pas	La base de données n’existe pas	Vérifiez le nom de la base de données dans `kustoIngestionProperties`/Créer la base de données
L’entité « nom de la table qui n’existe pas » de type « Table » est introuvable.	La table n’existe pas et il n’existe aucun mappage CSV.	Ajouter un mappage CSV / créer la table requise
Chemin d’accès <> d’objet blob exclu pour raison : le modèle JSON doit être ingéré avec le paramètre jsonMapping	Ingestion JSON quand aucun mappage JSON n’est fourni.	Fournir un mappage JSON
Échec du téléchargement de l’objet blob : « Le serveur distant a retourné une erreur : (404) Introuvable. »	Le blob n’existe pas.	Vérifiez que l’objet blob existe. S’il existe, réessayez et contactez l’équipe Kusto
Le mappage de colonnes JSON n’est pas valide : deux éléments de mappage ou plus pointent vers la même colonne.	Le mappage JSON comporte 2 colonnes avec des chemins différents	Corriger le mappage JSON
EngineError - [UtilsException] `IngestionDownloader.Download`: Un ou plusieurs fichiers n’ont pas pu être téléchargés (recherchez ActivityID :<GUID1>, RootActivityId :<GUID2> dans KustoLogs)	Un ou plusieurs fichiers n’ont pas pu être téléchargés.	Réessayer
Échec de l’analyse : le flux avec l’ID «< nom> du flux » a un format CSV incorrect, ce qui échoue par la stratégie ValidationOptions	Fichier CSV mal formé (par exemple, n’ayant pas le même nombre de colonnes sur chaque ligne). Échoue uniquement lorsque la stratégie de validation est définie sur `ValidationOptions.ValidateCsvInputConstantColumns`.	Vérifiez vos fichiers CSV. Ce message s’applique uniquement aux fichiers CSV/TSV
`IngestClientAggregateException` avec le message d’erreur « Paramètres obligatoires manquants pour la signature d’accès partagé valide »	La signature d’accès partagé utilisée appartient au service et non au compte de stockage	Utiliser la signature d’accès partagé du compte de stockage

Codes d’erreur d’ingestion

Pour faciliter la gestion des échecs d’ingestion par programme, les informations d’échec sont enrichies avec un code d’erreur numérique (IngestionErrorCode enumeration).

Pour obtenir la liste complète des codes d’erreur d’ingestion, consultez Codes d’erreur d’ingestion.

Informations de référence détaillées sur les exceptions

CloudQueuesNotFoundException

Déclenché quand aucune file d’attente n’a été retournée à partir du cluster Gestion des données

Classe de base : Exception

Nom du champ	Type	Signification
Erreur	`string`	Erreur qui s’est produite lors de la tentative de récupération des files d’attente à partir du DM

Pertinent uniquement lors de l’utilisation du client d’ingestion en file d’attente Kusto. Pendant le processus d’ingestion, plusieurs tentatives sont effectuées pour récupérer les files d’attente Azure liées au DM. Lorsque ces tentatives échouent, l’exception contenant la raison de l’échec est déclenchée dans le champ « Erreur ». Peut-être qu’une exception interne dans le champ « InnerException » est également levée.

CloudBlobContainersNotFoundException

Déclenché lorsqu’aucun conteneur d’objets blob n’a été retourné à partir du cluster Gestion des données

Classe de base : Exception

Nom du champ	Type	Signification
KustoEndpoint	`string`	Point de terminaison du DM approprié

Pertinent uniquement lors de l’utilisation du client d’ingestion en file d’attente Kusto.
Lors de l’ingestion de sources qui ne se trouvent pas déjà dans un conteneur Azure, telles que des fichiers, DataReader ou Stream, les données sont chargées dans un objet blob temporaire pour ingestion. L’exception est levée lorsqu’aucun conteneur n’est trouvé pour charger les données.

DuplicateIngestionPropertyException

Déclenché lorsqu’une propriété d’ingestion est configurée plusieurs fois

Classe de base : Exception

Nom du champ	Type	Signification
PropertyName	`string`	Nom de la propriété dupliquée

PostMessageToQueueFailedException

Déclenché lors de l’échec de la publication d’un message dans la file d’attente

Classe de base : Exception

Nom du champ	Type	Signification
QueueUri	`string`	URI de la file d’attente
Erreur	`string`	Message d’erreur qui a été généré lors de la tentative de publication dans la file d’attente

Pertinent uniquement lors de l’utilisation du client d’ingestion en file d’attente Kusto.
Le client d’ingestion en file d’attente ingère les données en chargeant un message dans la file d’attente Azure appropriée. En cas de post-échec, l’exception est levée. Il contient l’URI de file d’attente, la raison de l’échec dans le champ « Error » et éventuellement une exception interne dans le champ « InnerException ».