Bibliothèque de client d’ingestion Azure Monitor pour .NET - version 1.1.1

Article
10/17/2023

La bibliothèque cliente d’ingestion Azure Monitor est utilisée pour envoyer des journaux personnalisés à Azure Monitor.

Cette bibliothèque vous permet d’envoyer des données à partir de pratiquement n’importe quelle source aux tables intégrées prises en charge ou aux tables personnalisées que vous créez dans l’espace de travail Log Analytics. Vous pouvez même étendre le schéma des tables intégrées avec des colonnes personnalisées.

Ressources :

Prise en main

Prérequis

Un abonnement Azure
Une implémentation TokenCredential, par exemple un type d’informations d'identification de la bibliothèque d’identités Azure.
Un point de terminaison de collecte de données
Règle de collecte de données
Un espace de travail Log Analytics

Installer le package

Installez la bibliothèque de client d’ingestion Azure Monitor pour .NET avec NuGet :

dotnet add package Azure.Monitor.Ingestion

Authentifier le client

Un client authentifié est nécessaire pour ingérer des données. Pour vous authentifier, créez une instance d’une TokenCredential classe. Passez-le au constructeur de la LogsIngestionClient classe .

Pour l’authentification, l’exemple suivant utilise DefaultAzureCredential à partir du Azure.Identity package :

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

Configurer le client pour le cloud souverain Azure

Par défaut, LogsIngestionClient est configuré pour se connecter au cloud public Azure. Pour vous connecter à un cloud souverain à la place, définissez la LogsIngestionClientOptions.Audience propriété . Par exemple :

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

Charger les journaux

Pour obtenir des exemples d’ingestion de journaux, consultez la section Exemples .

Concepts clés

Point de terminaison de collecte de données

Les points de terminaison de collecte de données vous permettent de configurer de manière unique les paramètres d’ingestion pour Azure Monitor. Cet article fournit une vue d’ensemble des DDE, y compris leur contenu, leur structure et la façon dont vous pouvez les créer et les utiliser.

Règle de collecte de données

Les règles de collecte de données (DCR) définissent les données collectées par Azure Monitor et spécifient comment et où ces données doivent être envoyées ou stockées. L’appel de l’API REST doit spécifier une règle de collecte de données à utiliser. Un seul point de terminaison de collecte de données peut prendre en charge plusieurs règles de collecte de données. Vous pouvez donc spécifier une règle de collecte de données différente pour chaque source et chaque table cible.

La règle de collecte de données doit comprendre la structure des données d’entrée et celle de la table cible. Si les deux ne correspondent pas, elle peut utiliser une transformation pour convertir les données sources en fonction de la table cible. Vous pouvez également utiliser la transformation pour filtrer les données sources et effectuer d’autres calculs et conversions.

Pour plus d’informations, consultez Règles de collecte de données dans Azure Monitor.

Tables d’espace de travail Log Analytics

Les journaux personnalisés peuvent envoyer des données à n’importe quelle table personnalisée créée par vos soins et à certaines tables intégrées de votre espace de travail Log Analytics. La table cible doit déjà exister pour que vous puissiez lui envoyer des données. Les tables intégrées actuellement prises en charge sont les suivantes :

Sécurité des threads

Nous garantissons que toutes les méthodes de instance client sont sécurisées pour les threads et indépendantes les unes des autres (recommandations). Cette conception garantit que la recommandation de réutilisation des instances clientes est toujours sécurisée, même entre les threads.

Concepts supplémentaires

Exemples

Inscrire le client avec l’injection de dépendances
Charger des journaux personnalisés
Charger des journaux personnalisés en tant que IEnumerable
Charger des journaux personnalisés en tant que IEnumerable avec EventHandler
Vérifier les journaux

Vous pouvez vous familiariser avec différentes API à l’aide d’exemples.

Inscrire le client avec l’injection de dépendances

Pour vous inscrire LogsIngestionClient auprès du conteneur d’injection de dépendances (DI), appelez la AddLogsIngestionClient méthode . Pour plus d’informations, consultez Inscrire un client.

Charger des journaux personnalisés

Vous pouvez charger des journaux à l’aide de la LogsIngestionClient.UploadLogsIngestionClient.UploadAsync méthode ou . Notez les limites d’ingestion des données. Cette méthode a un paramètre facultatif : string contentEncoding. Cela fait référence à l’encodage du RequestContent en cours de transmission. Si vous transmettez du contenu déjà manipulé, définissez le paramètre contentEncoding. Par exemple, si votre contenu est gzipped, définissez contentEncoding sur « gzip ». Si ce paramètre n’est pas défini, le comportement par défaut consiste à gzipr toutes les entrées.

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

Charger des journaux personnalisés en tant que IEnumerable

Vous pouvez également charger des journaux à l’aide de la LogsIngestionClient.UploadLogsIngestionClient.UploadAsync méthode ou dans laquelle les journaux sont transmis dans un type générique IEnumerable avec un paramètre facultatif LogsUploadOptions . Le LogsUploadOptions paramètre inclut un sérialiseur, une concurrence et un gestionnaire d’événements.

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

Charger des journaux personnalisés en tant que IEnumerable avec EventHandler

Vous pouvez charger des journaux à l’aide de la LogsIngestionClient.UploadLogsIngestionClient.UploadAsync méthode ou . Dans ces deux méthodes, les journaux sont passés dans un type générique IEnumerable . En outre, il existe un LogsUploadOptionsparamètre -typed dans lequel un sérialiseur, une concurrence et un gestionnaire d’événements peuvent être définis. Le sérialiseur par défaut est défini sur System.Text.Json, mais vous pouvez passer le sérialiseur que vous souhaitez utiliser. La MaxConcurrency propriété définit le nombre de threads qui seront utilisés dans la UploadAsync méthode . La valeur par défaut est 5, et ce paramètre n’est pas utilisé dans la Upload méthode. Le gestionnaire d’événements est utilisé pour la gestion des erreurs. Il donne à l’utilisateur la possibilité d’abandonner le chargement en cas d’échec d’un lot et d’accéder aux journaux d’activité ayant échoué et à l’exception correspondante. Sans le gestionnaire d’événements, si un chargement échoue, un AggregateException sera levée.

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

Vérifier les journaux

Vous pouvez vérifier que vos données ont été chargées correctement à l’aide de la bibliothèque de requêtes Azure Monitor . Exécutez d’abord l’exemple Charger les journaux personnalisés avant de vérifier les journaux.

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

Dépannage

Pour plus d’informations sur le diagnostic des différents scénarios d’échec, consultez notre guide de résolution des problèmes.

Étapes suivantes

Pour en savoir plus sur Azure Monitor, consultez la documentation du service Azure Monitor.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée. Par exemple, les étiquettes et les commentaires. Suivez les instructions fournies par le bot. Vous ne devez signer l’accord CLA qu’une seule fois sur tous les dépôts à l’aide de notre CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez la FAQ sur le code de conduite ou contactez opencode@microsoft.com les questions ou commentaires.

Impressions

Partager via