Registrazioni Application Insights con .NET

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.

Applicazioni ASP.NET Core

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

1. Installare Microsoft.Extensions.Logging.ApplicationInsights.

2. Aggiungere 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();

Dopo aver installato il pacchetto NuGet 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:

• Microsoft.Extensions.Logging.ApplicationInsights
• Microsoft.Extensions.DependencyInjection

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.

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

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 nei dati di telemetria di Application Insights. 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:

1. Passare alla portale di Azure e accedere alla risorsa di Application Insights.
2. Selezionare la sezione Log all'interno di Application Insights.
3. Usare Linguaggio di query Kusto (KQL) per eseguire query sui messaggi ILogger archiviati nella traces tabella. Query di esempio: traces | where message contains "YourSearchTerm".
4. 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):

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

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

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.

Passaggi successivi

• Registrazione in .NET
• Registrazione in ASP.NET Core
• Log di traccia .NET in Application Insights