Kusto.Ingest-Erfassung status Berichterstellung

  • Artikel

In diesem Artikel wird erläutert, wie Sie IKustoQueuedIngestClient-Features verwenden, um die status einer Erfassungsanforderung nachzuverfolgen.

Beschreibungsklassen

Diese Beschreibungsklassen enthalten wichtige Details zu den zu erfassenden Quelldaten und sollten beim Erfassungsvorgang verwendet werden.

  • SourceDescription
  • DataReaderDescription
  • StreamDescription
  • FileDescription
  • BlobDescription

Die Klassen werden alle von der abstrakten Klasse SourceDescriptionabgeleitet und werden verwendet, um einen eindeutigen Bezeichner für jede Datenquelle zu instanziieren. Jeder Bezeichner wird dann für status Nachverfolgung verwendet und in allen Berichten, Ablaufverfolgungen und Ausnahmen im Zusammenhang mit dem relevanten Vorgang angezeigt.

SourceDescription-Klasse

Große Datasets werden in Blöcke mit 1 GB aufgeteilt, und jeder Teil wird separat erfasst. Die gleiche SourceId gilt dann für alle Erfassungsvorgänge, die aus demselben Dataset stammen.

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

DataReaderDescription-Klasse

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

StreamDescription-Klasse

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

Class FileDescription

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

BlobDescription-Klasse

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

Darstellung des Erfassungsergebnisses

Schnittstelle IKustoIngestionResult

Diese Schnittstelle erfasst das Ergebnis eines einzelnen Erfassungsvorgangs in der Warteschlange und kann von SourceIdabgerufen werden.

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

Klasse IngestionStatus

IngestionStatus enthält eine vollständige status eines einzelnen Erfassungsvorgangs.

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

Statusenumeration

Wert Bedeutung Temporär/Dauerhaft
Ausstehend Der Wert kann sich während des Erfassungsverlaufs basierend auf dem Ergebnis des Erfassungsvorgangs ändern. Temporäre Prozeduren
Erfolgreich Die Daten wurden erfolgreich erfasst. Dauerhaft
Fehler Fehler bei der Erfassung Dauerhaft
In Warteschlange Die Daten wurden für die Erfassung in die Warteschlange eingereiht. Dauerhaft
Ausgelassen Es wurden keine Daten angegeben, und der Erfassungsvorgang wurde übersprungen. Dauerhaft
Teilweise abgeschlossen Ein Teil der Daten wurde erfolgreich erfasst, während einige Fehler aufgetreten sind. Dauerhaft

Erfassungsstatus nachverfolgen (KustoQueuedIngestClient)

IKustoQueuedIngestClient ist ein "fire-and-forget"-Client. Der Erfassungsvorgang auf der Clientseite endet, indem eine Nachricht an eine Azure-Warteschlange gesendet wird. Nach der Veröffentlichung ist der Clientauftrag abgeschlossen. KustoQueuedIngestClient bietet für den Clientbenutzer einen Mechanismus zum Nachverfolgen der einzelnen Erfassung status. Dieser Mechanismus ist nicht für die Massennutzung in Erfassungspipelines mit hohem Durchsatz vorgesehen. Dieser Mechanismus dient zur Präzisenerfassung, wenn die Rate relativ niedrig ist und die Nachverfolgungsanforderungen streng sind.

Warnung

Das Aktivieren positiver Benachrichtigungen für jede Erfassungsanforderung für Große Volumedatenströme sollte vermieden werden, da die zugrunde liegenden xStore-Ressourcen dadurch extrem belastet werden, was zu einer erhöhten Erfassungslatenz und sogar einer vollständigen Nichtreaktion des Clusters führen kann.

Die folgenden Eigenschaften (festgelegt auf KustoQueuedIngestionProperties) steuern die Ebene und den Transport für Erfolgs- oder Fehlerbenachrichtigungen bei der Erfassung.

IngestionReportLevel-Enumeration

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

IngestionReportMethod-Enumeration

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

Um die status Ihrer Erfassung nachzuverfolgen, geben Sie Folgendes für den IKustoQueuedIngestClient an, mit dem Sie den Erfassungsvorgang durchführen:

  1. Legen Sie IngestionReportLeveldie -Eigenschaft auf die erforderliche Berichtsebene fest. Entweder FailuresOnly (der Standardwert) oder FailuresAndSuccesses. Wenn auf Nonefestgelegt ist, wird am Ende der Erfassung nichts gemeldet.
  2. Geben Sie , IngestionReportMethodTable - Queueoder QueueAndTablean.

Ein Verwendungsbeispiel finden Sie auf der Seite Kusto.Ingest-Beispiele .

Erfassung status in der Azure-Tabelle

Die IKustoIngestionResult Schnittstelle, die von jedem Erfassungsvorgang zurückgegeben wird, enthält Funktionen, mit denen die status der Erfassung abgefragt werden kann. Achten Sie besonders auf die Status Eigenschaft der zurückgegebenen IngestionStatus Objekte:

  • Pending gibt an, dass die Quelle für die Erfassung in die Warteschlange eingereiht wurde und noch aktualisiert werden muss. Verwenden Sie die Funktion erneut, um die status der Quelle abzufragen.
  • Succeeded gibt an, dass die Quelle erfolgreich erfasst wurde.
  • Failed gibt an, dass die Quelle nicht erfasst werden konnte.

Hinweis

Wenn Sie eine Queued status erhalten, wird angegeben, dass der IngestionReportMethod Standardwert "Queue" beibehalten wurde. Dies ist eine permanente status und das erneute Aufrufen der GetIngestionStatusBySourceId Funktionen oder GetIngestionStatusCollection führt immer zu derselben "Warteschlangen"-status. Um die status einer Erfassung in einer Azure-Tabelle zu überprüfen, überprüfen Sie vor der Erfassung, ob die IngestionReportMethod Eigenschaft von KustoQueuedIngestionProperties auf Tablefestgelegt ist. Wenn die Erfassungs-status auch an eine Warteschlange gemeldet werden soll, legen Sie die status auf festQueueAndTable.

Erfassung status in Azure-Warteschlange

Die IKustoIngestionResult Methoden sind nur für die Überprüfung eines status in einer Azure-Tabelle relevant. Verwenden Sie die folgenden IKustoQueuedIngestClient-Methoden , um statuses abzufragen, die an eine Azure-Warteschlange gemeldet wurden.

Methode Zweck
PeekTopIngestionFailures Async-Methode, die Informationen zu den frühesten Erfassungsfehlern zurückgibt, die aufgrund des Grenzwerts für angeforderte Nachrichten noch nicht verworfen wurden
GetAndDiscardTopIngestionFailures Async-Methode, die die frühesten Erfassungsfehler zurückgibt und verwirft, die aufgrund des Grenzwerts für angeforderte Nachrichten noch nicht verworfen wurden
GetAndDiscardTopIngestionSuccesses Asynchrone Methode, die die frühesten Erfassungserfolge zurückgibt und verwirft, die aufgrund des Grenzwerts für angeforderte Nachrichten noch nicht verworfen wurden. Diese Methode ist nur relevant, wenn auf IngestionReportLevel festgelegt ist. FailuresAndSuccesses

Erfassungsfehler, die aus der Azure-Warteschlange abgerufen wurden

Die Erfassungsfehler werden durch das IngestionFailure -Objekt dargestellt, das nützliche Informationen zum Fehler enthält.

Eigenschaft Bedeutung
Datenbank-&-Tabelle Die beabsichtigten Datenbank- und Tabellennamen
IngestionSourcePath Der Pfad des erfassten Blobs. Enthält den ursprünglichen Dateinamen, wenn die Datei erfasst wird. Zufällig, wenn DataReader erfasst wird
FailureStatus Permanent (Es wird kein Wiederholungsversuch ausgeführt), Transient (Wiederholungsversuche werden ausgeführt) oder Exhausted (mehrere Wiederholungen sind ebenfalls fehlgeschlagen)
OperationId & RootActivityId Vorgangs-ID und RootActivity-ID der Erfassung (nützlich für die weitere Problembehandlung)
FailedOn UTC-Zeit des Fehlers. Ist größer als der Zeitpunkt, zu dem die Erfassungsmethode aufgerufen wurde, da die Daten vor dem Ausführen der Erfassung aggregiert werden.
Details Sonstige Angaben zum Fehler (falls vorhanden)
ErrorCode IngestionErrorCode -Enumeration, stellt den Erfassungsfehlercode dar, wenn ein Fehler aufgetreten ist