Journalisation d’Application Insights avec .NET

  • Article

Dans cet article, vous allez apprendre à capturer des journaux avec Application Insights dans des applications .NET en utilisant le package du fournisseurMicrosoft.Extensions.Logging.ApplicationInsights. Si vous utilisez ce fournisseur, vous pouvez interroger et analyser vos journaux à l’aide des outils Application Insights.

Remarque

La documentation suivante s’appuie sur l’API classique d’Application Insights. Le plan à long terme pour Application Insights est de collecter des données en utilisant OpenTelemetry. Pour plus d’informations, consultez la section Activer Azure Monitor OpenTelemetry pour les applications .NET, Node.js, Python et Java.

Remarque

Si vous souhaitez implémenter la gamme complète des données de télémétrie ainsi que la journalisation d’Application Insights, consultez Configurer Application Insights pour vos sites web ASP.NET ou Application Insights pour applications ASP.NET Core.

Conseil

Le package NuGet Microsoft.ApplicationInsights.WorkerService, utilisé pour activer Application Insights pour les services en arrière-plan, est hors de portée. Pour plus d’informations, consultez Application Insights pour les applications Worker Service.

applications ASP.NET Core ;

Pour ajouter la journalisation Application Insights aux applications ASP.NET Core :

  1. Installez Microsoft.Extensions.Logging.ApplicationInsights.

  2. Ajoutez ApplicationInsightsLoggerProvider :

using Microsoft.Extensions.Logging.ApplicationInsights;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

builder.Logging.AddApplicationInsights(
        configureTelemetryConfiguration: (config) => 
            config.ConnectionString = builder.Configuration.GetConnectionString("APPLICATIONINSIGHTS_CONNECTION_STRING"),
            configureApplicationInsightsLoggerOptions: (options) => { }
    );

builder.Logging.AddFilter<ApplicationInsightsLoggerProvider>("your-category", LogLevel.Trace);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Lorsque le package NuGet est installé et que le fournisseur est inscrit avec l’injection de dépendances, l’application est prête à se connecter. Avec l’injection de constructeur, ILogger ou l’alternative de type générique ILogger<TCategoryName> est requis. Lorsque ces implémentations sont résolues, ApplicationInsightsLoggerProvider les fournit. Les exceptions et les messages journalisés sont envoyés à Application Insights.

Considérez l’exemple de contrôleur suivant :

public class ValuesController : ControllerBase
{
    private readonly ILogger _logger;

    public ValuesController(ILogger<ValuesController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public ActionResult<IEnumerable<string>> Get()
    {
        _logger.LogWarning("An example of a Warning trace..");
        _logger.LogError("An example of an Error level message");

        return new string[] { "value1", "value2" };
    }
}

Pour plus d’informations, consultez Journalisation dans ASP.NET Core et Quel type de télémétrie Application Insights est obtenu des journaux ILogger ? Où puis-je voir les journaux ILogger dans Application Insights ?.

Application de console

Pour ajouter la journalisation Application Insights aux applications console, installez d’abord les packages NuGet suivants :

L’exemple suivant utilise le package Microsoft.Extensions.Logging.ApplicationInsights et illustre le comportement par défaut d’une application console. Le package Microsoft.Extensions.Logging.ApplicationInsights doit être utilisé dans une application console ou chaque fois que vous souhaitez utiliser une implémentation minimale d’Application Insights sans l’ensemble complet des fonctionnalités (métriques, suivi distribué, échantillonnage, initialiseurs de télémétrie, etc.).

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

using var channel = new InMemoryChannel();

try
{
    IServiceCollection services = new ServiceCollection();
    services.Configure<TelemetryConfiguration>(config => config.TelemetryChannel = channel);
    services.AddLogging(builder =>
    {
        // Only Application Insights is registered as a logger provider
        builder.AddApplicationInsights(
            configureTelemetryConfiguration: (config) => config.ConnectionString = "<YourConnectionString>",
            configureApplicationInsightsLoggerOptions: (options) => { }
        );
    });

    IServiceProvider serviceProvider = services.BuildServiceProvider();
    ILogger<Program> logger = serviceProvider.GetRequiredService<ILogger<Program>>();

    logger.LogInformation("Logger is working...");
}
finally
{
    // Explicitly call Flush() followed by Delay, as required in console apps.
    // This ensures that even if the application terminates, telemetry is sent to the back end.
    channel.Flush();

    await Task.Delay(TimeSpan.FromMilliseconds(1000));
}

Pour plus d’informations, consultez Quel type de télémétrie Application Insights est obtenu des journaux ILogger ? Où puis-je voir les journaux ILogger dans Application Insights ?.

Étendues de journalisation

ApplicationInsightsLoggingProvider prend en charge les étendues de journal. Les étendues sont activées par défaut.

Si l’étendue est de type IReadOnlyCollection<KeyValuePair<string,object>>, chaque paire clé-valeur de la collection est ajoutée aux données de télémétrie Application Insights sous forme de propriétés personnalisées. Dans l’exemple suivant, les journaux sont capturés en tant que TraceTelemetry et comportent ("MyKey", "MyValue") dans les propriétés.

using (_logger.BeginScope(new Dictionary<string, object> { ["MyKey"] = "MyValue" }))
{
    _logger.LogError("An example of an Error level message");
}

Si un autre type est utilisé comme étendue, il est stocké sous la propriété Scope dans les données de télémétrie d’Application Insights. Dans l’exemple suivant, TraceTelemetry dispose d’une propriété appelée Scope contenant l’étendue.

    using (_logger.BeginScope("hello scope"))
    {
        _logger.LogError("An example of an Error level message");
    }

Forum aux questions

Quel type de télémétrie Application Insights est produit à partir des journaux d’activité ILogger ? Où se trouvent les journaux ILogger dans Application Insights ?

ApplicationInsightsLoggerProvider capture les journaux ILogger et crée TraceTelemetry à partir de ceux-ci. Si un objet Exception est transmis à la méthode Log sur ILogger, ExceptionTelemetry est créé à la place de TraceTelemetry.

Affichage de la télémétrie ILogger

Sur le portail Azure :

  1. Accédez au portail Azure et accédez à votre ressource Application Insights.
  2. Cliquez sur la section « Journaux » dans Application Insights.
  3. Utilisez le Langage de requête Kusto (KQL) pour interroger les messages ILogger, généralement stockés dans la table traces.
    • Exemple de requête : traces | where message contains "YourSearchTerm".
  4. Affinez vos requêtes pour filtrer les données ILogger par gravité, intervalle de temps ou contenu de message spécifique.

Dans Visual Studio (débogueur local) :

  1. Démarrez votre application en mode débogage dans Visual Studio.
  2. Ouvrez la fenêtre « Outils de diagnostic » pendant l’exécution de l’application.
  3. Sous l’onglet « Événements », les journaux ILogger s’affichent avec d’autres données de télémétrie.
  4. Utilisez les fonctionnalités de recherche et de filtre dans la fenêtre « Outils de diagnostic » pour localiser des messages ILogger spécifiques.

Si vous préférez envoyer TraceTelemetry systématiquement, utilisez cet extrait de code :

builder.AddApplicationInsights(
    options => options.TrackExceptionsAsExceptionTelemetry = false);

Pourquoi certains journaux ILogger n’ont-ils pas les mêmes propriétés que d’autres ?

Application Insights capture et envoie les journaux ILogger en utilisant les même informations TelemetryConfiguration qui sont utilisées pour toutes les autres données de télémétrie. Il existe cependant une exception. Par défaut, TelemetryConfiguration n’est pas entièrement configuré lorsque vous vous connectez à partir de Program.cs ou de Startup.cs. Les journaux provenant de ces emplacements ne sont pas soumis à la configuration par défaut et n’exécutent donc pas toutes les instances TelemetryInitializer et TelemetryProcessor.

J’utilise le package autonome Microsoft.Extensions.Logging.Logging.ApplicationInsights et je veux enregistrer manuellement d’autres données de télémétrie personnalisées. Comment dois-je procéder ?

Lorsque vous utilisez le package autonome, TelemetryClient n’est pas injecté dans le conteneur d’injection de dépendances (DI). Vous devez créer une nouvelle instance de TelemetryClient et utiliser la même configuration que celle utilisée par le fournisseur d’enregistreur, comme le montre le code suivant. Cette condition garantit que la même configuration est utilisée pour toutes les données de télémétrie personnalisées ainsi que pour les données de télémétrie de la fonctionnalité ILogger.

public class MyController : ApiController
{
   // This TelemetryClient instance can be used to track additional telemetry through the TrackXXX() API.
   private readonly TelemetryClient _telemetryClient;
   private readonly ILogger _logger;

   public MyController(IOptions<TelemetryConfiguration> options, ILogger<MyController> logger)
   {
        _telemetryClient = new TelemetryClient(options.Value);
        _logger = logger;
   }  
}

Notes

Si vous utilisez le package Microsoft.ApplicationInsights.AspNetCore pour activer Application Insights, modifiez ce code pour obtenir TelemetryClient directement dans le constructeur.

Le SDK n’est pas installé mais j’utilise l’extension Azure Web Apps pour activer Application Insights pour mes applications ASP.NET Core. Comment utiliser Personalizer ?

L’extension Application Insights d’Azure Web Apps utilise le nouveau fournisseur. Vous pouvez modifier les règles de filtrage dans le fichier appsettings.json de votre application.

Étapes suivantes