Creazione di report sullo stato di inserimento kusto.Kusto.Ingest ingestion status reporting

Questo articolo illustra come usare le funzionalità di IKustoQueuedIngestClient per tenere traccia dello stato di una richiesta di inserimento.This article explains how to use IKustoQueuedIngestClient features to track the status of an ingestion request.

Classi DescriptionDescription classes

Queste classi di descrizione contengono informazioni importanti sui dati di origine da inserire e che devono essere utilizzate nell'operazione di inserimento.These description classes contain important details about the source data to be ingested, and should be used in the ingestion operation.

  • SourceDescriptionSourceDescription
  • DataReaderDescriptionDataReaderDescription
  • StreamDescriptionStreamDescription
  • FileDescriptionFileDescription
  • BlobDescriptionBlobDescription

Tutte le classi sono derivate dalla classe astratta SourceDescription e vengono usate per creare un'istanza di un identificatore univoco per ogni origine dati.The classes are all derived from the abstract class SourceDescription, and they're used to instantiate a unique identifier for each data source. Ogni identificatore verrà quindi utilizzato per il rilevamento dello stato e verrà visualizzato in tutti i report, le tracce e le eccezioni correlate all'operazione pertinente.Each identifier will then be used for status tracking and will show up in all reports, traces, and exceptions related to the relevant operation.

Classe SourceDescriptionClass SourceDescription

I set di impostazioni di grandi dimensioni verranno suddivisi in blocchi da 1 GB e ogni parte verrà inserita separatamente.Large datasets will be split into 1GB chunks, and each part will be ingested separately. Lo stesso SourceId verrà quindi applicato a tutte le operazioni di inserimento originate dallo stesso set di dati.The same SourceId will then apply to all ingest operations originated from the same dataset.

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

Classe DataReaderDescriptionClass DataReaderDescription

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

Classe StreamDescriptionClass StreamDescription

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

Classe FileDescriptionClass FileDescription

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

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

Rappresentazione risultato inserimentoIngestion result representation

Interfaccia IKustoIngestionResultInterface IKustoIngestionResult

Questa interfaccia acquisisce il risultato di una singola operazione di inserimento in coda e può essere recuperato da SourceId .This interface captures the result of a single queued ingestion operation and can be retrieved by 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 IngestionStatusClass IngestionStatus

IngestionStatus contiene lo stato completo di una singola operazione di inserimento.IngestionStatus contains a complete status of a single ingestion operation.

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://docs.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; }
}

Enumerazione dello statoStatus enumeration

ValoreValue SignificatoMeaning Temporanea/permanenteTemporary/Permanent
PendingPending Il valore può cambiare durante il corso di inserimento, in base al risultato dell'operazione di inserimentoThe value may change during the course of ingestion, based on the outcome of the ingestion operation TemporaneaTemporary
Operazione riuscitaSucceeded Il caricamento dei dati è stato completatoThe data has been successfully ingested PermanentePermanent
Operazione non riuscitaFailed Inserimento non riuscitoIngestion failed PermanentePermanent
QueuedQueued I dati sono stati accodati per l'inserimentoThe data has been queued for ingestion PermanentePermanent
Operazione ignorataSkipped Non sono stati specificati dati e l'operazione di inserimento è stata ignorataNo data was supplied and the ingest operation was skipped PermanentePermanent
PartiallySucceededPartiallySucceeded Parte dei dati è stata inserita correttamente, mentre alcune non sono riuscitePart of the data was successfully ingested, while some failed PermanentePermanent

Rilevamento dello stato di inserimento (KustoQueuedIngestClient)Tracking Ingestion Status (KustoQueuedIngestClient)

IKustoQueuedIngestClient è un client "Fire-and-Forget".IKustoQueuedIngestClient is a 'fire-and-forget' client. L'operazione di inserimento sul lato client termina inserendo un messaggio in una coda di Azure.The ingestion operation on the client side ends by posting a message to an Azure queue. Dopo la pubblicazione, viene eseguito il processo client.After the posting, the client job is done. Per comodità dell'utente client, KustoQueuedIngestClient fornisce un meccanismo per tenere traccia dello stato di inserimento singolo.For the client user's convenience, KustoQueuedIngestClient provides a mechanism for tracking the individual ingestion status. Questo meccanismo non è destinato all'utilizzo di massa su pipeline di inserimento con velocità effettiva elevata.This mechanism isn't intended for mass usage on high-throughput ingestion pipelines. Si tratta di un meccanismo per l'inserimento di precisione quando la velocità è relativamente bassa e i requisiti di rilevamento sono rigorosi.This mechanism is for precision ingestion when the rate is relatively low and the tracking requirements are strict.

Avviso

L'attivazione di notifiche positive per ogni richiesta di inserimento di flussi di dati di volumi di grandi dimensioni deve essere evitata, poiché questo comporta un carico estremo sulle risorse xStore sottostanti, il che potrebbe comportare un aumento della latenza di inserimento e persino la mancata risposta completa del cluster.Turning on positive notifications for every ingestion request for large volume data streams should be avoided, since this places an extreme load on the underlying xStore resources, which might lead to increased ingestion latency and even complete cluster non-responsiveness.

Le seguenti proprietà (impostate in KustoQueuedIngestionProperties) controllano il livello e il trasporto per le notifiche di esito positivo o negativo di inserimento.The following properties (set on KustoQueuedIngestionProperties) control the level and transport for ingestion success or failure notifications.

Enumerazione IngestionReportLevelIngestionReportLevel enumeration

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

Enumerazione IngestionReportMethodIngestionReportMethod enumeration

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

Per tenere traccia dello stato dell'inserimento, fornire quanto segue al IKustoQueuedIngestClient con cui si esegue l'operazione di inserimento:To track the status of your ingestion, provide the following to the IKustoQueuedIngestClient that you do the ingest operation with:

  1. Imposta IngestionReportLevel la proprietà sul livello richiesto del report.Set IngestionReportLevelproperty to the required level of report. FailuresOnly(Valore predefinito) o FailuresAndSuccesses .Either FailuresOnly (which is the default value) or FailuresAndSuccesses. Quando è impostato su None , non viene segnalato alcun elemento alla fine dell'inserimento.When set to None, nothing will be reported at the end of the ingestion.
  2. Specificare IngestionReportMethod - Queue , Table o both .Specify the IngestionReportMethod - Queue, Table, or both.

Un esempio di utilizzo è disponibile nella pagina degli esempi di Kusto. inserimenti.A usage example can be found on the Kusto.Ingest Examples page.

Stato di inserimento nella tabella di AzureIngestion status in the Azure table

L' IKustoIngestionResult interfaccia restituita da ogni operazione di inserimento contiene funzioni che possono essere utilizzate per eseguire query sullo stato di inserimento.The IKustoIngestionResult interface that is returned from each ingest operation contains functions that can be used to query the status of the ingestion. Prestare particolare attenzione alla Status proprietà degli IngestionStatus oggetti restituiti:Pay special attention to the Status property of the returned IngestionStatus objects:

  • Pendingindica che l'origine è stata accodata per l'inserimento ed è ancora da aggiornare.Pending indicates that the source has been queued for ingestion and is yet to be updated. Utilizzare di nuovo la funzione per eseguire una query sullo stato dell'origineUse the function again to query the status of the source
  • Succeededindica che l'origine è stata inserita correttamente.Succeeded indicates that the source has been ingested successfully
  • Failedindica che non è stato possibile inserire l'origineFailed indicates that the source failed to be ingested

Nota

Il recupero di uno Queued stato indica che IngestionReportMethod è stato lasciato il valore predefinito "Queue".Getting a Queued status indicates that the IngestionReportMethod was left at its default value of 'Queue'. Si tratta di uno stato permanente e richiamata delle funzioni o, che comporteranno GetIngestionStatusBySourceId GetIngestionStatusCollection sempre lo stesso stato "in coda".This is a permanent status and re-invoking the GetIngestionStatusBySourceId or GetIngestionStatusCollection functions, will always result in the same 'Queued' status. Per controllare lo stato di un inserimento in una tabella di Azure, prima dell'inserimento, verificare che la IngestionReportMethod proprietà di KustoQueuedIngestionProperties sia impostata su Table .To check the status of an ingestion in an Azure table, prior to ingesting, verify that the IngestionReportMethod property of the KustoQueuedIngestionProperties is set to Table. Se si vuole anche che lo stato di inserimento venga segnalato a una coda, impostare lo stato su QueueAndTable .If you also want the ingestion status to be reported to a queue, set the status to QueueAndTable.

Stato di inserimento nella coda di AzureIngestion status in Azure queue

I IKustoIngestionResult metodi sono rilevanti solo per il controllo dello stato in una tabella di Azure.The IKustoIngestionResult methods are only relevant for checking a status in an Azure table. Per eseguire query sugli stati segnalati a una coda di Azure, usare i metodi IKustoQueuedIngestClient seguenti.To query statuses that were reported to an Azure queue, use the following IKustoQueuedIngestClient methods.

MetodoMethod ScopoPurpose
PeekTopIngestionFailuresPeekTopIngestionFailures Metodo asincrono che restituisce informazioni sugli errori di inserimento meno recenti che non sono già stati eliminati a causa del limite per i messaggi richiestiAsync method that returns information about the earliest ingestion failures that haven't already been discarded because of the limit for requested messages
GetAndDiscardTopIngestionFailuresGetAndDiscardTopIngestionFailures Metodo asincrono che restituisce e rimuove gli errori di inserimento meno recenti che non sono già stati eliminati a causa del limite per i messaggi richiestiAsync method that returns and discards the earliest ingestion failures that haven't already been discarded because of the limit for requested messages
GetAndDiscardTopIngestionSuccessesGetAndDiscardTopIngestionSuccesses Metodo asincrono che restituisce e rimuove i primi successi di inserimento che non sono già stati eliminati a causa del limite per i messaggi richiesti.Async method that returns and discards the earliest ingestion successes that haven't already been discarded because of the limit for requested messages. Questo metodo è pertinente solo se IngestionReportLevel è impostato su.FailuresAndSuccessesThis method is only relevant if the IngestionReportLevel is set to FailuresAndSuccesses

Errori di inserimento recuperati dalla coda di AzureIngestion failures retrieved from the Azure queue

Gli errori di inserimento sono rappresentati dall' IngestionFailure oggetto che contiene informazioni utili sull'errore.The ingestion failures are represented by the IngestionFailure object that contains useful information about the failure.

ProprietàProperty SignificatoMeaning
Tabella & databaseDatabase & Table I nomi di database e di tabella desideratiThe intended database and table names
IngestionSourcePathIngestionSourcePath Percorso del BLOB inserito.The path of the ingested blob. Conterrà il nome file originale se il file viene inserito.Will contain the original file name if file is ingested. Sarà casuale se viene inserito DataReaderWill be random if DataReader is ingested
FailureStatusFailureStatus Permanent(nessun nuovo tentativo verrà eseguito), Transient (verrà eseguito un nuovo tentativo) o Exhausted (anche diversi tentativi non riusciti)Permanent (no retry will be executed), Transient (retry will be executed), or Exhausted (several retries also failed)
OperationId & RootActivityIdOperationId & RootActivityId ID operazione e ID attività RootActivity dell'inserimento (utile per ulteriore risoluzione dei problemi)Operation ID and RootActivity ID of the ingestion (useful for further troubleshooting)
FailedOnFailedOn Ora UTC dell'errore.UTC time of the failure. Sarà maggiore dell'ora in cui è stato chiamato il metodo di inserimento, perché i dati vengono aggregati prima di eseguire l'inserimentoWill be greater than the time when the ingestion method was called, since the data is aggregated before running the ingestion
DettagliDetails Altri dettagli relativi all'errore (se presente)Other details concerning the failure (if any exist)
ErrorCodeErrorCode IngestionErrorCodeEnumerazione, rappresenta il codice di errore di inserimento, se si è verificato un erroreIngestionErrorCode enumeration, represents the ingestion error code, if there was a failure