Biblioteca de clientes de ingestão do Azure Monitor para .NET – versão 1.1.1

  • Artigo

A biblioteca de clientes de Ingestão do Azure Monitor é usada para enviar logs personalizados para o Azure Monitor.

Essa biblioteca permite que você envie dados de praticamente qualquer fonte para tabelas internas com suporte ou para tabelas personalizadas criadas no workspace do Log Analytics. Você pode até mesmo estender o esquema de tabelas internas com colunas personalizadas.

Recursos:

Introdução

Pré-requisitos

Instalar o pacote

Instale a biblioteca de clientes de Ingestão do Azure Monitor para .NET com o NuGet:

dotnet add package Azure.Monitor.Ingestion

Autenticar o cliente

Um cliente autenticado é necessário para ingerir dados. Para autenticar, crie uma instância de uma TokenCredential classe . Passe-o para o construtor da LogsIngestionClient classe .

Para autenticar, o exemplo a seguir usa DefaultAzureCredential do Azure.Identity pacote:

var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var client = new LogsIngestionClient(endpoint, credential);

Configurar o cliente para a nuvem soberana do Azure

Por padrão, LogsIngestionClient é configurado para se conectar à nuvem pública do Azure. Para se conectar a uma nuvem soberana, defina a LogsIngestionClientOptions.Audience propriedade . Por exemplo:

var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var clientOptions = new LogsIngestionClientOptions
{
    Audience = LogsIngestionAudience.AzureChina
};
var client = new LogsIngestionClient(endpoint, credential, clientOptions);

Carregar os logs

Para obter exemplos de ingestão de logs, consulte a seção Exemplos .

Principais conceitos

Ponto de extremidade da coleta de dados

Os DCEs (pontos de extremidade de coleta de dados) permitem definir exclusivamente as configurações de ingestão para o Azure Monitor. Este artigo fornece uma visão geral dos DCEs, incluindo seu conteúdo, estrutura e como você pode criar e trabalhar com eles.

Regra de coleta de dados

As DCRs (regras de coleta de dados) definem os dados coletados pelo Azure Monitor e especificam como e onde esses dados devem ser enviados ou armazenados. A chamada à API REST deve especificar uma DCR a ser usada. Um único DCE pode dar suporte a várias DCRs, para que você possa especificar uma DCR diferente para fontes diferentes e tabelas de destino.

A DCR deve entender a estrutura dos dados de entrada e a estrutura da tabela de destino. Se as duas não forem correspondentes, ela poderá usar uma transformação para converter os dados de origem a fim de fazer uma correspondência à tabela de destino. Você também pode usar a transformação para filtrar os dados de origem e executar quaisquer outros cálculos ou conversões.

Para obter mais informações, consulte Regras de coleta de dados no Azure Monitor.

Tabelas do workspace do Log Analytics

Os logs personalizados podem enviar dados para qualquer tabela personalizada que você criar e para determinadas tabelas internas no workspace do Log Analytics. A tabela de destino deve existir para que você possa enviar dados a ela. As seguintes tabelas internas têm suporte no momento:

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Esse design garante que a recomendação de reutilizações de instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | clienteAcessando a resposta | Operações de execução longa | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

Você pode se familiarizar com diferentes APIs usando exemplos.

Registrar o cliente com injeção de dependência

Para registrar-se LogsIngestionClient com o contêiner de DI (injeção de dependência), invoque o AddLogsIngestionClient método . Para obter mais informações, consulte Registrar cliente.

Carregar logs personalizados

Você pode carregar logs usando o LogsIngestionClient.Upload método ou LogsIngestionClient.UploadAsync . Observe os limites de ingestão de dados. Esse método tem um parâmetro opcional: string contentEncoding. Isso se refere à codificação do RequestContent que está sendo passado. Se você estiver passando conteúdo que já foi manipulado, defina o parâmetro contentEncoding. Por exemplo, se o conteúdo for gzipped, defina contentEncoding como "gzip". Se esse parâmetro não estiver definido, o comportamento padrão será gzip de todas as entradas.

var endpoint = new Uri("<data_collection_endpoint>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);
DateTimeOffset currentTime = DateTimeOffset.UtcNow;

// Use BinaryData to serialize instances of an anonymous type into JSON
BinaryData data = BinaryData.FromObjectAsJson(
    new[] {
        new
        {
            Time = currentTime,
            Computer = "Computer1",
            AdditionalContext = new
            {
                InstanceName = "user1",
                TimeZone = "Pacific Time",
                Level = 4,
                CounterName = "AppMetric1",
                CounterValue = 15.3
            }
        },
        new
        {
            Time = currentTime,
            Computer = "Computer2",
            AdditionalContext = new
            {
                InstanceName = "user2",
                TimeZone = "Central Time",
                Level = 3,
                CounterName = "AppMetric1",
                CounterValue = 23.5
            }
        },
    });

// Upload our logs
Response response = await client.UploadAsync(
    ruleId,
    streamName,
    RequestContent.Create(data)).ConfigureAwait(false);

Carregar logs personalizados como IEnumerable

Você também pode carregar logs usando o LogsIngestionClient.Upload ou o método no qual os LogsIngestionClient.UploadAsync logs são passados em um tipo genérico IEnumerable junto com um parâmetro opcional LogsUploadOptions . O LogsUploadOptions parâmetro inclui um serializador, simultaneidade e um EventHandler.

var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);

DateTimeOffset currentTime = DateTimeOffset.UtcNow;

var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
    entries.Add(
        new {
            Time = currentTime,
            Computer = "Computer" + i.ToString(),
            AdditionalContext = i
        }
    );
}

// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries).ConfigureAwait(false);

Carregar logs personalizados como IEnumerable com EventHandler

Você pode carregar logs usando o LogsIngestionClient.Upload método ou LogsIngestionClient.UploadAsync . Nesses dois métodos, os logs são passados em um tipo genérico IEnumerable . Além disso, há um LogsUploadOptionsparâmetro com tipo em que um serializador, simultaneidade e EventHandler podem ser definidos. O serializador padrão é definido System.Text.Jsoncomo , mas você pode passar o serializador que deseja usar. A MaxConcurrency propriedade define o número de threads que serão usados no UploadAsync método . O valor padrão é 5 e esse parâmetro não é usado no Upload método . O EventHandler é usado para tratamento de erros. Ele dá ao usuário a opção de anular o upload se um lote falhar e acessar os logs com falha e a exceção correspondente. Sem o EventHandler, se um upload falhar, um AggregateException será lançado.

var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);

DateTimeOffset currentTime = DateTimeOffset.UtcNow;

var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
    entries.Add(
        new {
            Time = currentTime,
            Computer = "Computer" + i.ToString(),
            AdditionalContext = i
        }
    );
}
// Set concurrency and EventHandler in LogsUploadOptions
LogsUploadOptions options = new LogsUploadOptions();
options.MaxConcurrency = 10;
options.UploadFailed += Options_UploadFailed;

// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries, options).ConfigureAwait(false);

Task Options_UploadFailed(LogsUploadFailedEventArgs e)
{
    // Throw exception from EventHandler to stop Upload if there is a failure
    IReadOnlyList<object> failedLogs = e.FailedLogs;
    // 413 status is RequestTooLarge - don't throw here because other batches can successfully upload
    if ((e.Exception is RequestFailedException) && (((RequestFailedException)e.Exception).Status != 413))
        throw e.Exception;
    else
        return Task.CompletedTask;
}

Verificar logs

Você pode verificar se os dados foram carregados corretamente usando a biblioteca de Consultas do Azure Monitor . Execute o exemplo Carregar logs personalizados primeiro antes de verificar os logs.

var workspaceId = "<log_analytics_workspace_id>";
var tableName = "<table_name>";

var credential = new DefaultAzureCredential();
LogsQueryClient logsQueryClient = new(credential);

LogsBatchQuery batch = new();
string query = tableName + " | Count;";
string countQueryId = batch.AddWorkspaceQuery(
    workspaceId,
    query,
    new QueryTimeRange(TimeSpan.FromDays(1)));

Response<LogsBatchQueryResultCollection> queryResponse =
    await logsQueryClient.QueryBatchAsync(batch).ConfigureAwait(false);

Console.WriteLine("Table entry count: " +
    queryResponse.Value.GetResult<int>(countQueryId).Single());

Solução de problemas

Para obter detalhes sobre como diagnosticar vários cenários de falha, consulte nosso guia de solução de problemas.

Próximas etapas

Para saber mais sobre o Azure Monitor, confira a documentação do serviço Azure Monitor.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot CLA determina automaticamente se você precisa fornecer um CLA e decorar o PR adequadamente. Por exemplo, rótulos e comentários. Basta seguir as instruções fornecidas pelo bot. Você só precisa assinar o CLA uma vez em todos os repositórios usando nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, consulte as Perguntas frequentes sobre o Código de Conduta ou entre em contato opencode@microsoft.com com perguntas ou comentários.

Impressões