Relatório de status de ingestão do Kusto.Ingestion

Artigo
05/23/2023

Este artigo explica como usar os recursos IKustoQueuedIngestClient para acompanhar o status de uma solicitação de ingestão.

Classes de descrição

Essas classes de descrição contêm detalhes importantes sobre os dados de origem a serem ingeridos e devem ser usadas na operação de ingestão.

SourceDescription
DataReaderDescription
StreamDescription
FileDescription
BlobDescription

Todas as classes são derivadas da classe SourceDescriptionabstrata e são usadas para instanciar um identificador exclusivo para cada fonte de dados. Cada identificador será usado para status acompanhamento e aparecerá em todos os relatórios, rastreamentos e exceções relacionados à operação relevante.

Classe SourceDescription

Grandes conjuntos de dados serão divididos em partes de 1 GB e cada parte será ingerida separadamente. A mesma SourceId se aplicará a todas as operações de ingestão originadas do mesmo conjunto de dados.

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

Classe DataReaderDescription

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

StreamDescription de classe

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

Arquivo de classeDescription

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

BlobDescription de classe

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

Representação do resultado da ingestão

Interface IKustoIngestionResult

Essa interface captura o resultado de uma única operação de ingestão na fila e pode ser recuperada por 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();
}

Ingestão de classeStatus

IngestionStatus contém uma status completa de uma única operação de ingestão.

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

Enumeração de status

Valor	Significado	Temporário/Permanente
Pendente	O valor pode ser alterado durante o curso da ingestão, com base no resultado da operação de ingestão	Temporário
Com sucesso	Os dados foram ingeridos com êxito	Permanente
Com falha	Falha na ingestão	Permanente
Em fila	Os dados foram enfileirados para ingestão	Permanente
Ignorado	Nenhum dado foi fornecido e a operação de ingestão foi ignorada	Permanente
ParcialmenteSucceedido	Parte dos dados foi ingerida com êxito, enquanto alguns falharam	Permanente

Status de ingestão de acompanhamento (KustoQueuedIngestClient)

IKustoQueuedIngestClient é um cliente 'fire-and-forget'. A operação de ingestão no lado do cliente termina postando uma mensagem em uma fila do Azure. Após a postagem, o trabalho do cliente é feito. Para conveniência do usuário cliente, o KustoQueuedIngestClient fornece um mecanismo para acompanhar a ingestão individual status. Esse mecanismo não se destina ao uso em massa em pipelines de ingestão de alta taxa de transferência. Esse mecanismo é para ingestão de precisão quando a taxa é relativamente baixa e os requisitos de acompanhamento são estritos.

Aviso

A ativação de notificações positivas para cada solicitação de ingestão para fluxos de dados de grande volume deve ser evitada, pois isso coloca uma carga extrema nos recursos xStore subjacentes, o que pode levar a uma maior latência de ingestão e até mesmo à completa não capacidade de resposta do cluster.

As propriedades a seguir ( definidas em KustoQueuedIngestionProperties) controlam o nível e o transporte para notificações de êxito ou falha de ingestão.

Enumeração IngestionReportLevel

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

Enumeração IngestionReportMethod

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

Para acompanhar o status de sua ingestão, forneça o seguinte para o IKustoQueuedIngestClient com o qual você faz a operação de ingestão:

Defina IngestionReportLevela propriedade como o nível necessário do relatório. ( FailuresOnly que é o valor padrão) ou FailuresAndSuccesses. Quando definido como None, nada será relatado no final da ingestão.
Especifique o IngestionReportMethod - Queue, Tableou .QueueAndTable

Um exemplo de uso pode ser encontrado na página Exemplos de Kusto.Ingest .

Ingestão status na tabela do Azure

A IKustoIngestionResult interface retornada de cada operação de ingestão contém funções que podem ser usadas para consultar o status da ingestão. Preste atenção especial à Status propriedade dos objetos retornados IngestionStatus :

Pending indica que a origem foi enfileirada para ingestão e ainda não foi atualizada. Use a função novamente para consultar o status da origem
Succeeded indica que a origem foi ingerida com êxito
Failed indica que a origem não foi ingerida

Observação

Obter um Queued status indica que o IngestionReportMethod foi deixado no valor padrão de 'Queue'. Essa é uma status permanente e invocar novamente as GetIngestionStatusBySourceId funções ou GetIngestionStatusCollection sempre resultará na mesma status 'Enfileirada'. Para marcar o status de uma ingestão em uma tabela do Azure, antes de ingerir, verifique se a IngestionReportMethod propriedade do KustoQueuedIngestionProperties está definida Tablecomo . Se você também quiser que a ingestão status seja relatada a uma fila, defina o status como QueueAndTable.

Status de ingestão na fila do Azure

Os IKustoIngestionResult métodos são relevantes apenas para verificar um status em uma tabela do Azure. Para consultar status que foram relatados a uma fila do Azure, use os seguintes métodos IKustoQueuedIngestClient .

Método	Finalidade
PeekTopIngestionFailures	Método assíncrono que retorna informações sobre as primeiras falhas de ingestão que ainda não foram descartadas devido ao limite de mensagens solicitadas
GetAndDiscardTopIngestionFailures	Método assíncrono que retorna e descarta as primeiras falhas de ingestão que ainda não foram descartadas devido ao limite de mensagens solicitadas
GetAndDiscardTopIngestionSuccesses	Método assíncrono que retorna e descarta as primeiras sucessões de ingestão que ainda não foram descartadas devido ao limite de mensagens solicitadas. Esse método só será relevante se o `IngestionReportLevel` estiver definido como `FailuresAndSuccesses`

Falhas de ingestão recuperadas da fila do Azure

As falhas de ingestão são representadas pelo IngestionFailure objeto que contém informações úteis sobre a falha.

Propriedade	Significado
Tabela de & de banco de dados	Os nomes de banco de dados e tabelas pretendidos
IngestionSourcePath	O caminho do blob ingerido. Conterá o nome do arquivo original se o arquivo for ingerido. Será aleatório se DataReader for ingerido
FailureStatus	`Permanent` (nenhuma repetição será executada), `Transient` (a repetição será executada) ou `Exhausted` (várias tentativas também falharam)
OperationId & RootActivityId	ID da operação e ID de RootActivity da ingestão (útil para solução de problemas posteriores)
FailedOn	Hora UTC da falha. Será maior do que a hora em que o método de ingestão foi chamado, já que os dados são agregados antes de executar a ingestão
Detalhes	Outros detalhes sobre a falha (se houver algum)
ErrorCode	`IngestionErrorCode` enumeração representa o código de erro de ingestão, se houve uma falha

Compartilhar via