Journalisation d’Application Insights avec .NET

Article
12/17/2024

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.

Attention

Nous recommandons la Distribution OpenTelemetry Azure Monitor pour les nouvelles applications ou les nouveaux clients afin d’alimenter Azure Monitor Application Insights. La distribution OpenTelemetry Azure Monitor offre une expérience et des fonctionnalités similaires à celles du Kit de développement logiciel (SDK) Application Insights. Il est possible de migrer depuis le Kit de développement logiciel (SDK) Application Insights en utilisant les guides de migration pour .NET, Node.js et Python, mais nous travaillons encore à l’ajout de quelques fonctionnalités supplémentaires pour la compatibilité descendante.

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 :

Installez Microsoft.Extensions.Logging.ApplicationInsights.
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 pour la journalisation. 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é en tant qu’étendue, il est stocké sous la propriété Scope dans Application Insights Telemetry. 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

Dans le portail Azure:

Accédez au portail Azure, puis accédez à votre ressource Application Insights.
Sélectionnez la section Journaux d’activité dans Application Insights.
Utilisez KQL (Langage de requête Kusto) pour interroger les messages ILogger stockés dans la table traces. Exemple de requête : traces | where message contains "YourSearchTerm".
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) :

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

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.

Partager via