Pelaporan status penyerapan Kusto.Ingest

Artikel
03/21/2023

Artikel ini menjelaskan cara menggunakan fitur IKustoQueuedIngestClient untuk melacak status permintaan penyerapan.

Deskripsi kelas

Kelas deskripsi ini berisi detail penting tentang data sumber yang akan diserap, dan harus digunakan dalam operasi penyerapan.

SourceDescription
DataReaderDescription
StreamDescription
FileDescription
BlobDescription

Semua kelas berasal dari kelas SourceDescription abstrak, dan semua kelas tersebut digunakan untuk membuat pengenal unik untuk setiap sumber data. Setiap pengidentifikasi nantinya akan digunakan untuk pelacakan status dan akan muncul di semua laporan, jejak, dan pengecualian yang berkaitan dengan operasi yang relevan.

SourceDescription kelas

Himpunan data besar akan dibagi ke beberapa gugus berukuran 1GB, dan setiap bagian akan diserap secara terpisah. SourceId yang sama kemudian akan diterapkan ke semua operasi penyerapan yang berasal dari himpunan data yang sama.

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

DataReaderDescription kelas

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

StreamDescription kelas

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

FileDescription kelas

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

BlobDescription kelas

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

Representasi hasil penyerapan

IKustoIngestionResult antarmuka

Antarmuka ini menangkap hasil dari operasi penyerapan yang diantrekan tunggal dan dapat diambil oleh 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();
}

IngestionStatus kelas

IngestionStatus berisi status lengkap dari operasi penyerapan tunggal.

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

Enumerasi status

Nilai	Makna	Sementara/Permanen
Tertunda	Nilai dapat berubah selama penyerapan, berdasarkan hasil operasi penyerapan	Sementara
Berhasil	Data telah berhasil diserap	Permanen
Gagal	Penyerapan gagal	Permanen
Dalam antrean	Data telah diantrekan untuk penyerapan	Permanen
Dilewati	Tidak ada data yang disediakan dan operasi penyerapan dilewati	Permanen
PartiallySucceeded	Sebagian data berhasil diserap, sementara beberapa gagal	Permanen

Melacak Status Penyerapan (KustoQueuedIngestClient)

IKustoQueuedIngestClient adalah klien 'fire-and-forget'. Operasi penyerapan di sisi klien berakhir dengan memposting pesan ke antrean Azure. Setelah memposting, pekerjaan klien selesai. Untuk kenyamanan pengguna klien, KustoQueuedIngestClient menyediakan mekanisme untuk melacak status penyerapan individu. Mekanisme ini tidak dimaksudkan untuk penggunaan massal pada alur penyerapan throughput tinggi. Mekanisme ini untuk penyerapan presisi ketika tingkatnya relatif rendah dan persyaratan pelacakan ketat.

Peringatan

Mengaktifkan pemberitahuan positif untuk setiap permintaan penyerapan untuk aliran data volume besar harus dihindari, karena akan menempatkan beban ekstrem pada sumber daya xStore yang mendasarinya, yang dapat menyebabkan peningkatan latensi penyerapan dan bahkan non-responsif kluster yang lengkap.

Properti berikut (diatur pada KustoQueuedIngestionProperties) mengontrol tingkat dan transportasi untuk keberhasilan penyerapan atau pemberitahuan kegagalan.

Enumerasi IngestionReportLevel

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

Enumerasi IngestionReportMethod

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

Untuk melacak status penyerapan Anda, berikan hal berikut ke IKustoQueuedIngestClient bahwa Anda melakukan operasi penyerapan dengan:

Atur properti IngestionReportLevel ke tingkat laporan yang diperlukan. Baik FailuresOnly (yang merupakan nilai default) atau FailuresAndSuccesses. Ketika diatur ke None, tidak ada yang akan dilaporkan pada akhir penyerapan.
Tentukan IngestionReportMethod - Queue, Table, atau QueueAndTable.

Contoh penggunaan dapat ditemukan di halaman Contoh Kusto.Ingest.

Status penyerapan di tabel Azure

Antarmuka IKustoIngestionResult yang dikembalikan dari setiap operasi penyerapan berisi fungsi yang dapat digunakan untuk mengkueri status penyerapan. Perhatikan dengan cermat properti Status dari objek IngestionStatus yang dikembalikan:

Pending menunjukkan bahwa sumber telah diantrekan untuk penyerapan dan masih belum diperbarui. Gunakan fungsi ini lagi untuk mengkueri status sumber
Succeeded menunjukkan bahwa sumber telah berhasil diserap
Failed menunjukkan bahwa sumber gagal diserap

Catatan

Mendapatkan status Queued menunjukkan bahwa IngestionReportMethod dibiarkan dengan nilai default 'Queue'. Ini adalah status permanen, saat memanggil fungsi GetIngestionStatusBySourceId atau GetIngestionStatusCollection kembali, status 'Queued' yang sama akan selalu ditampilkan. Untuk memeriksa status penyerapan di tabel Azure, sebelum melakukan penyerapan, verifikasi bahwa properti IngestionReportMethod dari KustoQueuedIngestionProperties diatur ke Table. Ketika Anda juga ingin melaporkan status penyerapan ke antrean, atur status ke QueueAndTable.

Status penyerapan di antrean Azure

Metode IKustoIngestionResult hanya relevan untuk memeriksa status di tabel Azure. Untuk mengkueri status yang dilaporkan ke antrean Azure, gunakan metode IKustoQueuedIngestClient berikut.

Metode	Tujuan
PeekTopIngestionFailures	Metode asinkron yang mengembalikan informasi tentang kegagalan penyerapan paling awal yang belum dibuang karena batas pesan yang diminta
GetAndDiscardTopIngestionFailures	Metode asinkron yang mengembalikan dan membuang kegagalan penyerapan paling awal yang belum dibuang karena batas pesan yang diminta
GetAndDiscardTopIngestionSuccesses	Metode asinkron yang mengembalikan dan membuang keberhasilan penyerapan paling awal yang belum dibuang karena batas pesan yang diminta. Metode ini hanya relevan jika `IngestionReportLevel` diatur ke `FailuresAndSuccesses`

Kegagalan penyerapan diambil dari antrean Azure

Kegagalan penyerapan diwakili oleh objek IngestionFailure yang berisi informasi berguna tentang kegagalan.

Properti	Makna
Tabel & Database	Nama tabel dan database yang dituju
IngestionSourcePath	Jalur blob yang diserap. Akan berisi nama file asli jika file diserap. Akan bersifat acak jika DataReader diserap
FailureStatus	`Permanent` (tidak ada percobaan ulang yang akan dilakukan), `Transient` (percobaan ulang akan dilakukan), atau `Exhausted` (beberapa percobaan ulang juga gagal)
OperationId & RootActivityId	ID Operasi dan ID RootActivity dari penyerapan (berguna untuk pemecahan masalah lebih lanjut)
FailedOn	Waktu UTC kegagalan. Akan lebih besar dari waktu ketika metode penyerapan dipanggil, karena data diagregasi sebelum menjalankan penyerapan
Detail	Detail lain tentang kegagalan (jika ada)
ErrorCode	Enumerasi `IngestionErrorCode`, mewakili kode kesalahan penyerapan, jika terdapat kegagalan

Bagikan melalui