Registrazioni Application Insights con .NET

Articolo
10/15/2024

Questo articolo illustra come acquisire i log con Application Insights nelle app .NET usando il pacchetto del provider Microsoft.Extensions.Logging.ApplicationInsights. Se si usa questo provider, è possibile eseguire query sui log e analizzarli usando gli strumenti di Application Insights.

Nota

La documentazione seguente si basa sull'API classica di Application Insights. Il piano a lungo termine per Application Insights prevede la raccolta di dati con OpenTelemetry. Per altre informazioni, vedere Abilitare OpenTelemetry di Monitoraggio di Azure per le applicazioni .NET, Node.js, Python e Java oltre che la Roadmap OpenTelemetry. Le indicazioni sulla migrazione sono disponibili per .NET, Node.js e Python.

Nota

Se si vuole implementare l'intera gamma di dati di telemetria di Application Insights insieme alla registrazione, vedere Configurare Application Insights per i siti Web ASP.NET o Application Insights per le applicazioni ASP.NET Core.

Suggerimento

Il pacchetto NuGet Microsoft.ApplicationInsights.WorkerService, usato per abilitare Application Insights per i servizi in background, non rientra nell'ambito. Per altre informazioni, vedere Application Insights per le app del servizio di lavoro.

Applicazioni ASP.NET Core

Per aggiungere la registrazione di Application Insights alle applicazioni ASP.NET Core:

Installare Microsoft.Extensions.Logging.ApplicationInsights.
Aggiungere ApplicationInsightsLoggerProvider:

.NET 6.0+
.NET 5.0

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

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;

namespace WebApplication
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = CreateHostBuilder(args).Build();

            var logger = host.Services.GetRequiredService<ILogger<Program>>();
            logger.LogInformation("From Program, running the host now.");

            host.Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                })
                .ConfigureLogging((context, builder) =>
                {
                    builder.AddApplicationInsights(
                        configureTelemetryConfiguration: (config) => config.ConnectionString = context.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"],
                        configureApplicationInsightsLoggerOptions: (options) => { }
                    );

                    // Capture all log-level entries from Startup
                    builder.AddFilter<ApplicationInsightsLoggerProvider>(
                        typeof(Startup).FullName, LogLevel.Trace);
                });
    }
}

Con il pacchetto NuGet installato e il provider registrato con l'inserimento delle dipendenze, l'app è pronta per la registrazione. Con l'inserimento del costruttore, ILogger o l'alternativa di tipo generico ILogger<TCategoryName> è necessaria. Quando queste implementazioni vengono risolte, ApplicationInsightsLoggerProvider fornisce tali implementazioni. I messaggi o le eccezioni registrati vengono inviati ad Application Insights.

Si consideri il controller di esempio seguente:

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

Per altre informazioni, vedere Registrazione in ASP.NET Core e Quale tipo di telemetria di Application Insights viene generato dai log ILogger? Dove è possibile visualizzare i log ILogger in Application Insights?.

Applicazione console

Per aggiungere la registrazione di Application Insights alle applicazioni console, installare prima di tutto i pacchetti NuGet seguenti:

Nell'esempio seguente viene usato il pacchetto Microsoft.Extensions.Logging.ApplicationInsights e viene illustrato il comportamento predefinito per un'applicazione console. Il pacchetto Microsoft.Extensions.Logging.ApplicationInsights deve essere usato in un'applicazione console o ogni volta che si desidera un'implementazione minima di Application Insights senza il set di funzionalità completo, ad esempio metriche, traccia distribuita, campionamento e inizializzatori di telemetria.

.NET 6.0+
.NET 5.0

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

using Microsoft.ApplicationInsights.Channel;
using Microsoft.ApplicationInsights.Extensibility;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.ApplicationInsights;
using System;
using System.Threading.Tasks;

namespace ConsoleApp
{
    class Program
    {
        static async Task Main(string[] args)
        {
            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));
            }
        }
    }
}

Per altre informazioni, vedere Che tipo di dati di telemetria di Application Insights viene prodotto dai log ILogger? Dove è possibile visualizzare i log ILogger in Application Insights?.

Ambiti di registrazione

ApplicationInsightsLoggingProvider supporta gli ambiti di log. Gli ambiti sono abilitati per impostazione predefinita.

Se l'ambito è di tipo IReadOnlyCollection<KeyValuePair<string,object>>, ogni coppia chiave/valore nella raccolta viene aggiunta ai dati di telemetria di Application Insights come proprietà personalizzate. Nell'esempio seguente i log vengono acquisiti come TraceTelemetry e hanno ("MyKey", "MyValue") in proprietà.

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

Se un altro tipo viene usato come ambito, viene archiviato nella proprietà Scope in Application Insights Telemetry. Nell'esempio seguente TraceTelemetry ha una proprietà denominata Scope che contiene l'ambito.

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

Domande frequenti

Quale tipo di dati di telemetria di Application Insights viene generato dai log ILogger? Dove è possibile visualizzare i log di ILogger in Application Insights?

ApplicationInsightsLoggerProvider acquisisce i log ILogger e crea TraceTelemetry da questi. Se un oggetto Exception viene passato al metodo Log in ILogger, ExceptionTelemetry viene creato anziché TraceTelemetry.

Visualizzazione dei dati di telemetria di ILogger

Nel portale di Azure:

Recarsi al portale di Azure e accedere alla risorsa di Application Insights.
Fare clic sulla sezione "Log" all'interno di Application Insights.
Usare il Linguaggio di query Kusto (KQL) per eseguire query sui messaggi ILogger, in genere archiviati nella tabella traces.
- Query di esempio: traces | where message contains "YourSearchTerm".
Perfezionare le query per filtrare i dati ILogger in base alla gravità, all'intervallo di tempo o al contenuto specifico del messaggio.

In Visual Studio (debugger locale):

Avviare l'applicazione in modalità di debug in Visual Studio.
Aprire la finestra "Strumenti di diagnostica" durante l'esecuzione dell'applicazione.
Nella scheda "Eventi" i log ILogger vengono visualizzati insieme ad altri dati di telemetria.
Usare le funzionalità di ricerca e filtro nella finestra "Strumenti di diagnostica" per individuare messaggi ILogger specifici.

Se si preferisce inviare TraceTelemetry sempre, usare questo frammento di codice:

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

Perché alcuni log ILogger non hanno le stesse proprietà di altre?

Application Insights acquisisce e invia i log ILogger usando le stesse informazioni TelemetryConfiguration usate per tutti gli altri dati di telemetria. Ma c'è un'eccezione. Per impostazione predefinita, TelemetryConfiguration non è completamente configurato quando si accede da Program.cs o Startup.cs. I log da queste posizioni non hanno la configurazione predefinita, quindi non eseguono tutte le istanze TelemetryInitializer e le istanze TelemetryProcessor.

Si usa il pacchetto autonomo Microsoft.Extensions.Logging.ApplicationInsights e si vuole registrare manualmente altri dati di telemetria personalizzati. Come si esegue questa operazione?

Quando si usa il pacchetto autonomo, TelemetryClient non viene inserito nel contenitore di inserimento delle dipendenze. È necessario creare una nuova istanza di TelemetryClient e usare la stessa configurazione usata dal provider di logger, come illustrato nel codice seguente. Questo requisito garantisce che la stessa configurazione venga usata per tutti i dati di telemetria e i dati di telemetria personalizzati da 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;
   }  
}

Nota

Se si usa il pacchetto Microsoft.ApplicationInsights.AspNetCore per abilitare Application Insights, modificare questo codice per ottenere TelemetryClient direttamente nel costruttore.

Non è installato l'SDK e si usa l'estensione App Web di Azure per abilitare Application Insights per le applicazioni ASP.NET Core. Come si usa il nuovo provider?

L'estensione Application Insights in App Web di Azure usa il nuovo provider. È possibile modificare le regole di filtro nel file appsettings.json per l'applicazione.

Condividi tramite

Registrazioni Application Insights con .NET

Applicazioni ASP.NET Core

Applicazione console

Ambiti di registrazione

Domande frequenti

Quale tipo di dati di telemetria di Application Insights viene generato dai log ILogger? Dove è possibile visualizzare i log di ILogger in Application Insights?

Perché alcuni log ILogger non hanno le stesse proprietà di altre?

Si usa il pacchetto autonomo Microsoft.Extensions.Logging.ApplicationInsights e si vuole registrare manualmente altri dati di telemetria personalizzati. Come si esegue questa operazione?

Non è installato l'SDK e si usa l'estensione App Web di Azure per abilitare Application Insights per le applicazioni ASP.NET Core. Come si usa il nuovo provider?

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive