Registrazione di Application Insights con .NET

  • Articolo

Questo articolo illustra come acquisire i log con Application Insights nelle app .NET usando il pacchetto del Microsoft.Extensions.Logging.ApplicationInsights provider. 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 consiste nel raccogliere dati usando OpenTelemetry. Per altre informazioni, vedere Abilitare OpenTelemetry di Monitoraggio di Azure per le applicazioni .NET, Node.js, Python e Java.

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 core ASP.NET.

Suggerimento

Il Microsoft.ApplicationInsights.WorkerService pacchetto NuGet, 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 core ASP.NET

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

  1. Installare Microsoft.Extensions.Logging.ApplicationInsights.

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

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 è necessaria o l'alternativa ILogger<TCategoryName> di tipo generico. 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 vuole 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") 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 presente 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 ILogger log e li crea TraceTelemetry . Se un Exception oggetto viene passato al Log metodo in ILogger, ExceptionTelemetry viene creato anziché TraceTelemetry.

Visualizzazione dei dati di telemetria di ILogger

Nel portale di Azure:

  1. Passare al portale di Azure e accedere alla risorsa di Application Insights.
  2. Fare clic sulla sezione "Log" all'interno di Application Insights.
  3. Usare Linguaggio di query Kusto (KQL) per eseguire query sui messaggi ILogger, in genere 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. Usare le funzionalità di ricerca e filtro nella finestra "Strumenti di diagnostica" per individuare messaggi ILogger specifici.

Se si preferisce inviare TraceTelemetrysempre , 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 ILogger i log usando le stesse TelemetryConfiguration informazioni 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 e TelemetryProcessor le TelemetryInitializer istanze.

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

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 Microsoft.ApplicationInsights.AspNetCore pacchetto per abilitare Application Insights, modificare questo codice per ottenere TelemetryClient direttamente nel costruttore.

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

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

Passaggi successivi