Udostępnij za pośrednictwem

Rejestrowanie usługi Application Insights za pomocą platformy .NET

  • Artykuł

Z tego artykułu dowiesz się, jak przechwytywać dzienniki za pomocą usługi Application Insights w aplikacjach platformy .NET przy użyciu pakietu dostawcy Microsoft.Extensions.Logging.ApplicationInsights . Jeśli używasz tego dostawcy, możesz wykonywać zapytania i analizować dzienniki przy użyciu narzędzi usługi Application Insights.

Uwaga

Poniższa dokumentacja opiera się na klasycznym interfejsie API usługi Application Insights. Długoterminowy plan usługi Application Insights polega na zbieraniu danych przy użyciu technologii OpenTelemetry. Aby uzyskać więcej informacji, zobacz Enable Azure Monitor OpenTelemetry for .NET, Node.js, Python and Java applications and our OpenTelemetry Roadmap (Włączanie usługi Azure Monitor OpenTelemetry dla platformy .NET, Node.js, python i Java) oraz our OpenTelemetry Roadmap (Harmonogram działania openTelemetry). Wskazówki dotyczące migracji są dostępne dla platformy .NET, Node.js i języka Python.

Uwaga

Jeśli chcesz zaimplementować pełny zakres danych telemetrycznych usługi Application Insights wraz z rejestrowaniem, zobacz Konfigurowanie usługi Application Insights dla witryn internetowych ASP.NET lub usługi Application Insights dla aplikacji ASP.NET Core.

Napiwek

Microsoft.ApplicationInsights.WorkerService Pakiet NuGet używany do włączania usługi Application Insights dla usług w tle jest poza zakresem. Aby uzyskać więcej informacji, zobacz Application Insights for Worker Service apps (Aplikacje usługi Application Insights dla usługi Worker Service).

aplikacje ASP.NET Core

Aby dodać rejestrowanie usługi Application Insights do aplikacji ASP.NET Core:

  1. Zainstaluj program Microsoft.Extensions.Logging.ApplicationInsights.

  2. Dodaj ApplicationInsightsLoggerProviderpolecenie :

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

Po zainstalowaniu pakietu NuGet i zarejestrowaniu dostawcy za pomocą wstrzykiwania zależności aplikacja jest gotowa do rejestrowania. W przypadku iniekcji ILogger konstruktora wymagana jest alternatywa ILogger<TCategoryName> typu ogólnego lub ogólnego. Po rozwiązaniu ApplicationInsightsLoggerProvider tych implementacji udostępnia je. Zarejestrowane komunikaty lub wyjątki są wysyłane do usługi Application Insights.

Rozważmy następujący przykładowy kontroler:

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

Aby uzyskać więcej informacji, zobacz Rejestrowanie w usłudze ASP.NET Core i Jaki typ telemetrii usługi Application Insights jest generowany na podstawie dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w usłudze Application Insights?.

Aplikacja konsolowa

Aby dodać rejestrowanie usługi Application Insights do aplikacji konsoli, najpierw zainstaluj następujące pakiety NuGet:

W poniższym przykładzie użyto pakietu Microsoft.Extensions.Logging.ApplicationInsights i pokazano domyślne zachowanie aplikacji konsolowej. Pakiet Microsoft.Extensions.Logging.ApplicationInsights powinien być używany w aplikacji konsolowej lub zawsze, gdy potrzebujesz minimalnej implementacji usługi Application Insights bez pełnego zestawu funkcji, takiego jak metryki, śledzenie rozproszone, próbkowanie i inicjatory telemetrii.

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

Aby uzyskać więcej informacji, zobacz What Application Insights telemetry type is produced from ILogger logs? (Jaki typ telemetrii usługi Application Insights jest generowany na podstawie dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w usłudze Application Insights?.

Zakresy rejestrowania

ApplicationInsightsLoggingProvider obsługuje zakresy dzienników. Zakresy są domyślnie włączone.

Jeśli zakres ma typ IReadOnlyCollection<KeyValuePair<string,object>>, każda para klucz/wartość w kolekcji zostanie dodana do telemetrii usługi Application Insights jako właściwości niestandardowych. W poniższym przykładzie dzienniki są przechwytywane jako TraceTelemetry i mają ("MyKey", "MyValue") właściwości .

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

Jeśli jakikolwiek inny typ jest używany jako zakres, jest przechowywany w ramach właściwości Scope w telemetrii usługi Application Insights. W poniższym przykładzie TraceTelemetry ma właściwość o nazwie Scope , która zawiera zakres.

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

Często zadawane pytania

Jaki typ telemetrii usługi Application Insights jest generowany z dzienników ILogger? Gdzie można wyświetlić dzienniki ILogger w usłudze Application Insights?

ApplicationInsightsLoggerProvider przechwytuje ILogger dzienniki i tworzy TraceTelemetry je na ich podstawie. Exception Jeśli obiekt zostanie przekazany do metody w metodzie w ILoggermetodzie Log , ExceptionTelemetry zostanie utworzony zamiast TraceTelemetry.

Wyświetlanie telemetrii ILogger

W witrynie Azure Portal:

  1. Przejdź do witryny Azure Portal i uzyskaj dostęp do zasobu usługi Application Insights.
  2. Wybierz sekcję Dzienniki w usłudze Application Insights.
  3. Użyj język zapytań Kusto (KQL), aby wysyłać zapytania dotyczące komunikatów ILogger przechowywanych w traces tabeli. Przykładowe zapytanie: traces | where message contains "YourSearchTerm".
  4. Uściślij zapytania, aby filtrować dane ILogger według ważności, zakresu czasu lub określonej zawartości wiadomości.

W programie Visual Studio (debuger lokalny):

  1. Uruchom aplikację w trybie debugowania w programie Visual Studio.
  2. Otwórz okno Narzędzia diagnostyczne, gdy aplikacja jest uruchomiona.
  3. Na karcie Zdarzenia dzienniki ILogger są wyświetlane wraz z innymi danymi telemetrycznymi.
  4. Aby zlokalizować określone komunikaty ILogger, użyj funkcji wyszukiwania i filtrowania w oknie Narzędzia diagnostyczne.

Jeśli wolisz zawsze wysyłać TraceTelemetry, użyj tego fragmentu kodu:

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

Dlaczego niektóre dzienniki ILogger nie mają tych samych właściwości co inne?

Usługa Application Insights przechwytuje i wysyła ILogger dzienniki przy użyciu tych samych TelemetryConfiguration informacji, które są używane dla każdej innego telemetrii. Ale jest wyjątek. Domyślnie TelemetryConfiguration nie jest w pełni konfigurowany podczas logowania z Program.cs lub Startup.cs. Dzienniki z tych miejsc nie mają konfiguracji domyślnej, więc nie są uruchomione wszystkie TelemetryInitializer wystąpienia i TelemetryProcessor wystąpienia.

Używam autonomicznego pakietu Microsoft.Extensions.Logging.ApplicationInsights i chcę ręcznie rejestrować więcej niestandardowych danych telemetrycznych. Jak to zrobić?

W przypadku korzystania z pakietu TelemetryClient autonomicznego nie jest wstrzykiwany do kontenera wstrzykiwania zależności (DI). Musisz utworzyć nowe wystąpienie i TelemetryClient użyć tej samej konfiguracji, której używa dostawca rejestratora, jak pokazano w poniższym kodzie. To wymaganie gwarantuje, że ta sama konfiguracja jest używana dla wszystkich niestandardowych danych telemetrycznych i telemetrii z programu 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;
   }  
}

Uwaga

Jeśli używasz pakietu do włączenia Microsoft.ApplicationInsights.AspNetCore usługi Application Insights, zmodyfikuj ten kod, aby uzyskać TelemetryClient bezpośredni dostęp do konstruktora.

Nie mam zainstalowanego zestawu SDK i używam rozszerzenia Azure Web Apps, aby włączyć usługę Application Insights dla aplikacji ASP.NET Core. Jak mogę użyć nowego dostawcy?

Rozszerzenie Application Insights w usłudze Azure Web Apps używa nowego dostawcy. Reguły filtrowania można zmodyfikować w pliku appsettings.json dla aplikacji.

Następne kroki