Отчеты о состоянии приема Kusto.Ingest

В этой статье объясняется, как использовать функции IKustoQueuedIngestClient для отслеживания состояния запроса на прием.

Классы описания

Эти классы описания содержат важные сведения об исходных данных для приема и должны использоваться в операции приема.

• SourceDescription
• DataReaderDescription
• StreamDescription
• FileDescription
• BlobDescription

Все классы являются производными от абстрактного класса SourceDescriptionи используются для создания экземпляра уникального идентификатора для каждого источника данных. Затем каждый идентификатор будет использоваться для отслеживания состояния и будет отображаться во всех отчетах, трассировках и исключениях, связанных с соответствующей операцией.

Класс SourceDescription

Большие наборы данных будут разделены на блоки размером 1 ГБ, и каждая часть будет приниматься отдельно. Затем один и тот же SourceId будет применяться ко всем операциям приема, полученным из одного набора данных.

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

Класс DataReaderDescription

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

Класс StreamDescription

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

Описание файла класса

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

Класс 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; }
}

Представление результата приема

Интерфейс IKustoIngestionResult

Этот интерфейс фиксирует результат одной операции приема в очереди и может быть получен с помощью 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

IngestionStatus содержит полное состояние одной операции приема.

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

Перечисление состояния

Значение	Значение	Временные или постоянные
Ожидает	Значение может изменяться в процессе приема в зависимости от результата операции приема.	Временный диск
Выполнено	Данные успешно приняты	Постоянно
Сбой	Сбой приема	Постоянно
Поставлено в очередь	Данные поставлены в очередь для приема	Постоянно
Пропущено	Данные не были предоставлены, и операция приема пропущена	Постоянно
PartiallySucceeded	Часть данных была успешно включена, а часть — сбоем	Постоянно

Отслеживание состояния приема (KustoQueuedIngestClient)

IKustoQueuedIngestClient — это клиент "срабай и забудь". Операция приема на стороне клиента завершается отправкой сообщения в очередь Azure. После публикации задание клиента будет завершено. Для удобства пользователя клиента KustoQueuedIngestClient предоставляет механизм отслеживания состояния приема отдельных пользователей. Этот механизм не предназначен для массового использования в конвейерах приема с высокой пропускной способностью. Этот механизм предназначен для приема данных с точностью, если скорость относительно низкая, а требования к отслеживанию являются строгими.

Предупреждение

Следует избегать включения положительных уведомлений для каждого запроса на прием для потоков данных большого объема, так как это создает крайнюю нагрузку на базовые ресурсы xStore, что может привести к увеличению задержки приема и даже к полной неотложности кластера.

Следующие свойства ( заданные в KustoQueuedIngestionProperties) управляют уровнем и транспортом для уведомлений об успешном приеме или сбое.

Перечисление IngestionReportLevel

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

Перечисление IngestionReportMethod

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

Чтобы отслеживать состояние приема, укажите в IKustoQueuedIngestClient следующее:

1. Задайте IngestionReportLevelдля свойства требуемый уровень отчета. Либо FailuresOnly (это значение по умолчанию), либо FailuresAndSuccesses. Если задано значение None, в конце приема ничего не будет сообщено.
2. IngestionReportMethod - QueueУкажите , Tableили QueueAndTable.

Пример использования можно найти на странице Примеры Kusto.Ingest .

Состояние приема в таблице Azure

Интерфейс IKustoIngestionResult , возвращаемый каждой операцией приема, содержит функции, которые можно использовать для запроса состояния приема. Обратите особое внимание на Status свойство возвращаемых IngestionStatus объектов:

• Pending указывает, что источник поставлен в очередь для приема и еще не обновлен. Повторное использование функции для запроса состояния источника
• Succeeded указывает, что источник был успешно приняты
• Failed указывает, что источник не удалось принять

Примечание

Queued Получение состояния указывает, что IngestionReportMethod объект был оставлен со значением по умолчанию "Очередь". Это постоянное состояние, и повторный вызов GetIngestionStatusBySourceId функций или GetIngestionStatusCollection всегда приведет к одному и тому же состоянию "В очереди". Чтобы проверка состояние приема в таблице Azure, перед приемом убедитесь, что IngestionReportMethod свойство KustoQueuedIngestionProperties имеет значение Table. Если вы также хотите, чтобы состояние приема передавалось в очередь, задайте для этого состояния значение QueueAndTable.

Состояние приема в очереди Azure

Методы IKustoIngestionResult применимы только для проверки состояния в таблице Azure. Чтобы запросить состояния, которые были переданы в очередь Azure, используйте следующие методы IKustoQueuedIngestClient .

Метод	Цель
PeekTopIngestionFailures	Асинхронный метод, возвращающий сведения о самых ранних сбоях приема, которые еще не были отменены из-за ограничения для запрошенных сообщений
GetAndDiscardTopIngestionFailures	Асинхронный метод, который возвращает и отменяет самые ранние сбои приема, которые еще не были отменены из-за ограничения для запрошенных сообщений
GetAndDiscardTopIngestionSuccesses	Асинхронный метод, который возвращает и отменяет самые ранние успешные приемы, которые еще не были отменены из-за ограничения для запрошенных сообщений. Этот метод подходит только в том случае, IngestionReportLevel если для задано значение FailuresAndSuccesses

Сбои приема, полученные из очереди Azure

Сбои приема представлены IngestionFailure объектом , который содержит полезные сведения о сбое.

Свойство	Значение
Таблица & базы данных	Предполагаемые имена баз данных и таблиц
IngestionSourcePath	Путь к приемуемого большого двоичного объекта. Будет содержать исходное имя файла при приеме файла. Будет случайным при приеме DataReader
FailureStatus	Permanent (повторная попытка не будет выполнена), Transient (повторная попытка будет выполнена) или Exhausted (несколько повторных попыток также завершилось ошибкой)
OperationId & RootActivityId	Идентификатор операции и идентификатор RootActivity приема (полезен для дальнейшего устранения неполадок)
FailedOn	Время сбоя в формате UTC. Будет больше времени, когда был вызван метод приема, так как данные агрегируются перед запуском приема
Сведения	Другие сведения о сбое (если таковые существуют)
ErrorCode	IngestionErrorCode перечисление представляет код ошибки приема, если произошел сбой.