Kusto.Ingest alma durumu raporlaması

Makale
12/08/2023

Bu makalede, bir alım isteğinin durumunu izlemek için IKustoQueuedIngestClient özelliklerinin nasıl kullanılacağı açıklanmaktadır.

Açıklama sınıfları

Bu açıklama sınıfları, alınacak kaynak verilerle ilgili önemli ayrıntıları içerir ve alma işleminde kullanılmalıdır.

SourceDescription
DataReaderDescription
StreamDescription
FileDescription
BlobDescription

Sınıfların tümü soyut sınıfından SourceDescriptiontüretilir ve her veri kaynağı için benzersiz bir tanımlayıcı örneği oluşturmak için kullanılır. Ardından her tanımlayıcı durum izleme için kullanılır ve ilgili işlemle ilgili tüm raporlarda, izlemelerde ve özel durumlarda gösterilir.

Sınıf SourceDescription

Büyük veri kümeleri 1 GB öbeklere bölünür ve her bölüm ayrı olarak alınacaktır. Aynı SourceId daha sonra aynı veri kümesinden kaynaklanan tüm alma işlemleri için geçerli olur.

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

Sınıf DataReaderDescription

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

Sınıf StreamDescription

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

FileDescription Sınıfı

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

Sınıf 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; }
}

Alma sonucu gösterimi

Arabirim IKustoIngestionResult

Bu arabirim, tek bir kuyruğa alınmış alım işleminin sonucunu yakalar ve tarafından SourceIdalınabilir.

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

Sınıf IngestionStatus

IngestionStatus, tek bir alım işleminin tam durumunu içerir.

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

Durum numaralandırması

Değer	Anlamı	Geçici/Kalıcı
Beklemede	Alma işleminin sonucuna bağlı olarak, veri alımı sırasında değer değişebilir	Geçici
Başarılı	Veriler başarıyla alındı	Kalıcı
Başarısız	Alma başarısız oldu	Kalıcı
Kuyruğa alındı	Veriler alım için kuyruğa alındı	Kalıcı
Atlandı	Veri sağlanmadı ve alma işlemi atlandı	Kalıcı
Kısmen Baştan Çıkarılmış	Verilerin bir bölümü başarıyla alındı, bazıları ise başarısız oldu	Kalıcı

İzleme Alımı Durumu (KustoQueuedIngestClient)

IKustoQueuedIngestClient bir 'fire-and-forget' istemcisidir. İstemci tarafındaki alma işlemi, bir Azure kuyruğuna ileti göndererek sona erer. Deftere nakilden sonra istemci işi tamamlanır. İstemci kullanıcının kolaylık sağlaması için KustoQueuedIngestClient, tek tek alım durumunu izlemeye yönelik bir mekanizma sağlar. Bu mekanizma, yüksek aktarım hızına sahip alım işlem hatlarında toplu kullanıma yönelik değildir. Bu mekanizma, oran görece düşük olduğunda ve izleme gereksinimleri katı olduğunda duyarlık alımına yöneliktir.

Uyarı

Büyük hacimli veri akışları için her alım isteği için pozitif bildirimlerin etkinleştirilmesi önlenmelidir, çünkü bu durum temel alınan xStore kaynaklarına aşırı bir yük getirir ve bu da daha fazla veri alımı gecikmesine ve hatta küme yanıt vermemeye devam etmemesine neden olabilir.

Aşağıdaki özellikler ( KustoQueuedIngestionProperties üzerinde ayarlanır) alım başarısı veya hata bildirimleri için düzeyi ve aktarımı denetler.

IngestionReportLevel sabit listesi

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

IngestionReportMethod sabit listesi

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

Alma işleminizin durumunu izlemek için, alma işlemini gerçekleştirdiğiniz IKustoQueuedIngestClient'a aşağıdakileri sağlayın:

Özelliği gerekli rapor düzeyine ayarlayın IngestionReportLevel. FailuresOnly (varsayılan değerdir) veya FailuresAndSuccesses. olarak ayarlandığında None, alımın sonunda hiçbir şey bildirilmeyecektir.
IngestionReportMethod - Queue, Tableveya QueueAndTablebelirtin.

Kusto.Ingest Örnekleri sayfasında bir kullanım örneği bulunabilir.

Azure tablosunda alım durumu

IKustoIngestionResult Her alma işleminden döndürülen arabirim, alımın durumunu sorgulamak için kullanılabilecek işlevler içerir. Döndürülen IngestionStatus nesnelerin özelliğine Status özellikle dikkat edin:

Pending kaynağın alım için kuyruğa alındığını ve henüz güncelleştirilmediğini gösterir. Kaynağın durumunu sorgulamak için işlevini yeniden kullanın
Succeeded kaynağın başarıyla alındığını gösterir
Failed kaynağın alınalamadığını gösterir

Not

Queued Durum almak, öğesinin IngestionReportMethod varsayılan 'Kuyruk' değerinde bırakıldığını gösterir. Bu kalıcı bir durumdur ve veya GetIngestionStatusCollection işlevlerini yeniden çağırmak GetIngestionStatusBySourceId her zaman aynı 'Kuyruğa alındı' durumuna neden olur. Azure tablosundaki bir alımın durumunu denetlemek için, alma öncesinde KustoQueuedIngestionProperties özelliğinin olarak Tableayarlandığını doğrulayınIngestionReportMethod. Ayrıca alma durumunun kuyruğa bildirilmesini istiyorsanız, durumu olarak QueueAndTableayarlayın.

Azure kuyruğunda alma durumu

Yöntemler IKustoIngestionResult yalnızca Azure tablosundaki bir durumu denetlemek için geçerlidir. Azure kuyruğuna bildirilen durumları sorgulamak için aşağıdaki IKustoQueuedIngestClient yöntemlerini kullanın.

Yöntem	Amaç
PeekTopIngestionFailures	İstenen iletilerin sınırı nedeniyle atılmamış olan en erken alma hataları hakkında bilgi döndüren zaman uyumsuz yöntem
GetAndDiscardTopIngestionFailures	İstenen iletilerin sınırı nedeniyle atılmamış olan en erken alma hatalarını döndüren ve atan zaman uyumsuz yöntem
GetAndDiscardTopIngestionSuccesses	İstenen iletilerin sınırı nedeniyle atılmış olmayan en erken alma başarılarını döndüren ve atan zaman uyumsuz yöntem. Bu yöntem yalnızca için olarak ayarlandığında geçerlidir `IngestionReportLevelFailuresAndSuccesses`

Azure kuyruğundan alınan alma hataları

Alma hataları, hata hakkında yararlı bilgiler içeren nesneyle IngestionFailure temsil edilir.

Özellik	Anlamı
Veritabanı & Tablosu	Hedeflenen veritabanı ve tablo adları
IngestionSourcePath	Alınan blobun yolu. Dosya alındıysa özgün dosya adını içerir. DataReader alındıysa rastgele olur
FailureStatus	`Permanent` (yeniden deneme yürütülmeyecek), `Transient` (yeniden deneme yürütülecek) veya `Exhausted` (birkaç yeniden deneme de başarısız oldu)
OperationId & RootActivityId	Alma işleminin İşlem Kimliği ve RootActivity Kimliği (daha fazla sorun giderme için yararlıdır)
FailedOn	Hatanın UTC saati. Veri alımı çalıştırılmadan önce toplandığı için veri alımı yönteminin çağrıldığı zamandan daha uzun olacaktır
Ayrıntılar	Hatayla ilgili diğer ayrıntılar (varsa)
ErrorCode	`IngestionErrorCode` sabit listesi, bir hata varsa alma hata kodunu temsil eder

Aracılığıyla paylaş