Errores y excepciones de Kusto.Ingest

Artículo
05/23/2023

Cualquier error durante el control de ingesta en el lado cliente se indica mediante una excepción de C#.

Errores

Excepciones de KustoDirectIngestClient

Al intentar ingerir desde varios orígenes, es posible que se produzcan errores durante el proceso de ingesta. Si se produce un error en una ingesta para uno de los orígenes, se registra y el cliente continúa ingeriendo los orígenes restantes. Después de pasar por todos los orígenes para la ingesta, se produce una IngestClientAggregateException excepción que contiene el IList<IngestClientException> IngestionErrors miembro .

IngestClientException y sus clases derivadas contienen un campo IngestionSource y un Error campo . Los dos campos crean una asignación, desde el origen que produjo un error en la ingesta, hasta el error que se produjo al intentar la ingesta. La información se puede usar en la IngestionErrors lista para investigar qué orígenes no se pudieron ingerir y por qué. La IngestClientAggregateException excepción también contiene una propiedad GlobalErrorbooleana , que indica si se produjo un error para todos los orígenes.

Errores al ingerir archivos o blobs

Si se produce un error de ingesta al intentar ingerir desde un blob o archivo, los orígenes de ingesta no se eliminarán, incluso si la deleteSourceOnSuccess marca está establecida trueen . Los orígenes se conservan para su posterior análisis. Una vez que se entiende el origen del error y si el error no se originó en el propio origen de ingesta, el usuario del cliente puede intentar volver a hacerlo.

Errores al ingerir desde IDataReader

Durante la ingesta desde DataReader, los datos que se van a ingerir se guardan en una carpeta temporal cuya ubicación predeterminada es <Temp Path>\Ingestions_<current date and time>. Esta carpeta predeterminada siempre se elimina después de una ingesta correcta.

En los IngestFromDataReader métodos y IngestFromDataReaderAsync , la retainCsvOnFailure marca , cuyo valor predeterminado es false, determina si los archivos deben conservarse después de una ingesta con errores. Si esta marca se establece falseen , los datos que no se realizan correctamente en la ingesta no se conservarán, lo que dificulta la comprensión de lo que salió mal.

Excepciones de KustoQueuedIngestClient

KustoQueuedIngestClient ingiere datos mediante la carga de mensajes en una cola de Azure. Si se produce un error antes o durante el proceso de puesta en cola, se produce una IngestClientAggregateException excepción al final del proceso. La excepción iniciada incluye una colección de IngestClientException, que contiene el origen de cada error y no se ha publicado en la cola. También se produce el error que se produjo al intentar publicar el mensaje.

Publicar en errores de cola con un archivo o blob como origen

Si se produce un error al usar los métodos de IngestFromFile/IngestFromBlob , los orígenes no se eliminan, aunque la deleteSourceOnSuccess marca esté establecida en true.KustoQueuedIngestClient En su lugar, los orígenes se conservan para su posterior análisis.

Una vez comprendido el origen del error y si el error no se originó en el propio origen de ingesta, el usuario del cliente puede intentar volver a poner en cola los datos mediante los métodos pertinentes IngestFromFile/IngestFromBlob con el origen con errores.

Publicación en errores de cola con IDataReader como origen

Mientras se usa un origen DataReader, los datos que se van a publicar en la cola se guardan en una carpeta temporal cuya ubicación predeterminada es <Temp Path>\Ingestions_<current date and time>. Esta carpeta siempre se elimina después de que los datos se hayan publicado correctamente en la cola. En los IngestFromDataReader métodos y IngestFromDataReaderAsync , la retainCsvOnFailure marca , cuyo valor predeterminado es false, determina si los archivos deben conservarse después de una ingesta con errores. Si esta marca se establece falseen , los datos que no se realizan correctamente en la ingesta no se conservarán, lo que dificulta la comprensión de lo que salió mal.

Errores comunes

Error	Motivo	Solución
El nombre> de la base de datos <de base de datos no existe	La base de datos no existe	Compruebe el nombre de la base de datos en `kustoIngestionProperties`/Create the database (Crear la base de datos).
No se encontró la entidad "nombre de tabla que no existe" del tipo "Table".	La tabla no existe y no hay ninguna asignación de CSV.	Agregar asignación de CSV/crear la tabla necesaria
<Ruta> de acceso de blob excluida por el motivo: el patrón JSON debe ingerirse con el parámetro jsonMapping.	Ingesta de JSON cuando no se proporciona ninguna asignación JSON.	Proporcionar una asignación JSON
No se pudo descargar el blob: "El servidor remoto devolvió un error: (404) No encontrado".	El blob no existe.	Compruebe que el blob existe. Si existe, vuelva a intentarlo y póngase en contacto con el equipo de Kusto.
La asignación de columnas JSON no es válida: dos o más elementos de asignación apuntan a la misma columna.	La asignación de JSON tiene 2 columnas con diferentes rutas de acceso	Corrección de la asignación de JSON
EngineError - [UtilsException] `IngestionDownloader.Download`: no se pudieron descargar uno o más archivos (búsqueda de KustoLogs para ActivityID:<GUID1>, RootActivityId:<GUID2>)	No se pudieron descargar uno o más archivos.	Volver a intentar
No se pudo analizar: La secuencia con el identificador "<nombre> de secuencia" tiene un formato CSV con formato incorrecto, con errores por directiva ValidationOptions	Archivo CSV con formato incorrecto (por ejemplo, que no tiene el mismo número de columnas en cada línea). Solo se produce un error cuando la directiva de validación está establecida `ValidationOptions.ValidateCsvInputConstantColumns`en .	Compruebe los archivos CSV. Este mensaje solo se aplica a los archivos CSV/TSV.
`IngestClientAggregateException` con el mensaje de error "Faltan parámetros obligatorios para la firma de acceso compartido válida"	La SAS que se usa es del servicio y no de la cuenta de almacenamiento	Uso de la SAS de la cuenta de almacenamiento

Códigos de error de ingesta

Para ayudar a controlar los errores de ingesta mediante programación, la información de error se enriquece con un código de error numérico (IngestionErrorCode enumeration).

Para obtener una lista completa de los códigos de error de ingesta, consulte Códigos de error de ingesta.

Referencia de excepciones detalladas

CloudQueuesNotFoundException

Se genera cuando no se devolvió ninguna cola desde el clúster de Administración de datos

Clase base: Excepción

Nombre del campo	Tipo	Significado
Error	`string`	Error que se produjo al intentar recuperar colas de dm

Solo es relevante cuando se usa el cliente de ingesta en cola de Kusto. Durante el proceso de ingesta, se realizan varios intentos para recuperar las colas de Azure vinculadas a dm. Cuando se produce un error en estos intentos, la excepción que contiene el motivo del error se genera en el campo "Error". Posiblemente también se genere una excepción interna en el campo "InnerException".

CloudBlobContainersNotFoundException

Se genera cuando no se devolvió ningún contenedor de blobs desde el clúster de Administración de datos

Clase base: Excepción

Nombre del campo	Tipo	Significado
KustoEndpoint	`string`	Punto de conexión de la dm pertinente

Solo es relevante cuando se usa el cliente de ingesta en cola de Kusto.
Al ingerir orígenes que aún no están en un contenedor de Azure, como archivos, DataReader o Stream, los datos se cargan en un blob temporal para la ingesta. La excepción se produce cuando no se encuentra ningún contenedor en el que cargar los datos.

DuplicateIngestionPropertyException

Se genera cuando se configura una propiedad de ingesta más de una vez

Clase base: Excepción

Nombre del campo	Tipo	Significado
PropertyName	`string`	Nombre de la propiedad duplicada

PostMessageToQueueFailedException

Se genera cuando se produce un error al publicar un mensaje en la cola

Clase base: Excepción

Nombre del campo	Tipo	Significado
QueueUri	`string`	Identificador URI de la cola
Error	`string`	Mensaje de error que se generó al intentar publicar en la cola

Solo es relevante cuando se usa el cliente de ingesta en cola de Kusto.
El cliente de ingesta en cola ingiere datos cargando un mensaje en la cola de Azure correspondiente. Si se produce un error posterior, se genera la excepción. Contendrá el URI de la cola, el motivo del error en el campo "Error" y, posiblemente, una excepción interna en el campo "InnerException".