Relatórios de estado de ingestão kusto.ingestão

Artigo
05/23/2023

Este artigo explica como utilizar as funcionalidades IKustoQueuedIngestClient para controlar o estado de um pedido de ingestão.

Classes de descrição

Estas classes de descrição contêm detalhes importantes sobre os dados de origem a ingerir e devem ser utilizadas na operação de ingestão.

SourceDescription
DataReaderDescription
StreamDescription
FileDescription
BlobDescription

As classes são todas derivadas da classe SourceDescriptionabstrata e são utilizadas para instanciar um identificador exclusivo para cada origem de dados. Cada identificador será utilizado para controlo de estado e será apresentado em todos os relatórios, rastreios e exceções relacionados com a operação relevante.

Class SourceDescription

Os conjuntos de dados grandes serão divididos em segmentos de 1 GB e cada parte será ingerida separadamente. Em seguida, o mesmo SourceId será aplicado a todas as operações de ingestão originadas a partir 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; }
}

Classe StreamDescription

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

Ficheiro de ClasseDescription

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

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

Representação do resultado da ingestão

Interface IKustoIngestionResult

Esta interface captura o resultado de uma única operação de ingestão em fila e pode ser obtida pelo 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 um estado completo 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 estado

Valor	Significado	Temporário/Permanente
Pendente	O valor pode ser alterado durante a ingestão, com base no resultado da operação de ingestão	Temporária
Com êxito	Os dados foram ingeridos com êxito	Permanente
Com falhas	Falha na ingestão	Permanente
Em fila	Os dados foram colocados em fila para ingestão	Permanente
Ignorado	Não foram fornecidos dados e a operação de ingestão foi ignorada	Permanente
ParcialmenteSucceeded	Parte dos dados foi ingerido com êxito, enquanto alguns falharam	Permanente

Estado da Ingestão de Controlo (KustoQueuedIngestClient)

O IKustoQueuedIngestClient é um cliente "fire-and-forget". A operação de ingestão no lado do cliente termina ao publicar uma mensagem numa fila do Azure. Após a publicação, a tarefa de cliente é efetuada. Para a conveniência do utilizador cliente, o KustoQueuedIngestClient fornece um mecanismo para controlar o estado de ingestão individual. Este mecanismo não se destina à utilização em massa em pipelines de ingestão de débito elevado. Este mecanismo destina-se à ingestão de precisão quando a taxa é relativamente baixa e os requisitos de controlo são rigorosos.

Aviso

A ativação de notificações positivas para cada pedido de ingestão de fluxos de dados de grandes volumes deve ser evitada, uma vez que esta ação coloca uma carga extrema nos recursos xStore subjacentes, o que pode levar a uma maior latência de ingestão e até mesmo a uma total falta de capacidade de resposta do cluster.

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

IngestionReportLevel enumeration

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

IngestionReportMethod enumeration

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

Para controlar o estado da ingestão, forneça o seguinte ao IKustoQueuedIngestClient com o qual efetua a operação de ingestão:

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

Pode encontrar um exemplo de utilização na página Exemplos de Kusto.Ingest .

Estado da ingestão na tabela do Azure

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

Pending indica que a origem foi colocada em fila para ingestão e ainda não foi atualizada. Utilize a função novamente para consultar o estado da origem
Succeeded indica que a origem foi ingerida com êxito
Failed indica que a origem não foi ingerida

Nota

Obter um Queued estado indica que o IngestionReportMethod foi deixado no valor predefinido de "Fila". Este é um estado permanente e invocar novamente as GetIngestionStatusBySourceId funções ou GetIngestionStatusCollection resultará sempre no mesmo estado "Em fila". Para verificar o estado de uma ingestão numa tabela do Azure, antes de ingerir, verifique se a IngestionReportMethod propriedade do KustoQueuedIngestionProperties está definida como Table. Se também quiser que o estado de ingestão seja comunicado a uma fila, defina o estado como QueueAndTable.

Estado da ingestão na fila do Azure

Os IKustoIngestionResult métodos só são relevantes para verificar um estado numa tabela do Azure. Para consultar os estados que foram comunicados a uma fila do Azure, utilize os seguintes métodos IKustoQueuedIngestClient .

Método	Objetivo
PeekTopIngestionFailures	Método assíncrono que devolve informações sobre as falhas de ingestão mais antigas que ainda não foram eliminadas devido ao limite de mensagens pedidas
GetAndDiscardTopIngestionFailures	Método assíncrono que devolve e elimina as primeiras falhas de ingestão que ainda não foram eliminadas devido ao limite de mensagens pedidas
GetAndDiscardTopIngestionSuccesses	Método assíncrono que devolve e elimina os primeiros êxitos de ingestão que ainda não foram eliminados devido ao limite de mensagens pedidas. Este método só é relevante se estiver `IngestionReportLevel` definido como `FailuresAndSuccesses`

Falhas de ingestão obtidas a partir 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 Base de Dados	Os nomes da base de dados e das tabelas pretendidos
IngestionSourcePath	O caminho do blob ingerido. Irá conter o nome de ficheiro original se o ficheiro for ingerido. Será aleatório se o 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 rootActivity da ingestão (útil para resolução de problemas adicionais)
FailedOn	Hora UTC da falha. Será maior do que o tempo em que o método de ingestão foi chamado, uma vez que os dados são agregados antes de executar a ingestão
Detalhes	Outros detalhes relativos à falha (se existirem)
CódigoDoErro	`IngestionErrorCode` enumeração, representa o código de erro de ingestão, se tiver ocorrido uma falha