Protokolování Application Insights s využitím .NET

Článek
12/17/2024

V tomto článku se naučíte zaznamenávat protokoly pomocí Application Insights v aplikacích .NET pomocí Microsoft.Extensions.Logging.ApplicationInsights balíčku zprostředkovatele. Pokud použijete tohoto zprostředkovatele, můžete dotazovat a analyzovat protokoly pomocí nástrojů Application Insights.

Upozornění

Pro nové aplikace nebo zákazníky doporučujeme , aby služba Azure Monitor OpenTelemetry distro vysílala služby Azure Monitor Application Insights. Distribuce OpenTelemetry služby Azure Monitor poskytuje podobné funkce a prostředí jako sada Application Insights SDK. Ze sady Application Insights SDK je možné migrovat pomocí průvodců migrací pro .NET, Node.js a Python, ale stále pracujeme na přidání několika dalších funkcí pro zpětnou kompatibilitu.

Poznámka:

Pokud chcete implementovat celou řadu telemetrických dat Application Insights spolu s protokolováním, přečtěte si téma Konfigurace Application Insights pro vaše ASP.NET weby nebo Application Insights pro aplikace ASP.NET Core.

Tip

Balíček Microsoft.ApplicationInsights.WorkerService NuGet, který se používá k povolení Application Insights pro služby na pozadí, je mimo rozsah. Další informace najdete v tématu Application Insights pro aplikace pracovních služeb.

aplikace ASP.NET Core

Přidání protokolování Application Insights do ASP.NET základních aplikací:

Nainstalujte soubor Microsoft.Extensions.Logging.ApplicationInsights.
Přidat 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();

S nainstalovaným balíčkem NuGet a zaregistrovaným poskytovatelem injektáže závislostí je aplikace připravená k protokolování. Při injektáži ILogger konstruktoru je vyžadována alternativa ILogger<TCategoryName> obecného typu. Když jsou tyto implementace vyřešeny, ApplicationInsightsLoggerProvider poskytuje je. Protokolované zprávy nebo výjimky se odesílají do Application Insights.

Představte si následující příklad kontroleru:

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

Další informace najdete v tématu Protokolování v ASP.NET Core a jaký typ telemetrie Application Insights se vytváří z protokolů ILoggeru? Kde se v Application Insights zobrazují protokoly ILoggeru?

Konzolová aplikace

Pokud chcete přidat protokolování Application Insights do konzolových aplikací, nejprve nainstalujte následující balíčky NuGet:

Následující příklad používá balíček Microsoft.Extensions.Logging.ApplicationInsights a ukazuje výchozí chování konzolové aplikace. Balíček Microsoft.Extensions.Logging.ApplicationInsights by se měl používat v konzolové aplikaci nebo kdykoli chcete použít minimální implementaci Application Insights bez úplné sady funkcí, jako jsou metriky, distribuované trasování, vzorkování a inicializátory telemetrie.

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

Další informace najdete v tématu Jaký typ telemetrie Application Insights se vytváří z protokolů ILoggeru? Kde se v Application Insights zobrazují protokoly ILoggeru?

Obory protokolování

ApplicationInsightsLoggingProvider podporuje obory protokolů. Obory jsou ve výchozím nastavení povolené.

Pokud je obor typu IReadOnlyCollection<KeyValuePair<string,object>>, pak se každý pár klíč/hodnota v kolekci přidá do telemetrie Application Insights jako vlastní vlastnosti. V následujícím příkladu jsou protokoly zachyceny jako TraceTelemetry a mají ("MyKey", "MyValue") ve vlastnostech.

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

Pokud se jako obor použije jakýkoli jiný typ, uloží se pod vlastnost Scope v telemetrii Application Insights. V následujícím příkladu TraceTelemetry má vlastnost s názvem Scope , která obsahuje obor.

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

Nejčastější dotazy

Jaký typ telemetrie Application Insights se vytváří z protokolů ILoggeru? Kde se v Application Insights zobrazují protokoly ILoggeru?

ApplicationInsightsLoggerProvider zaznamenává protokoly ILogger a vytváří TraceTelemetry z nich. Exception Pokud je objekt předán metodě Log on ILogger, ExceptionTelemetry je vytvořen místo TraceTelemetry.

Zobrazení telemetrie ILoggeru

Na webu Azure Portal:

Přejděte na web Azure Portal a přejděte k prostředku Application Insights.
Vyberte oddíl Protokoly v Application Insights.
K dotazování zpráv ILogger uložených traces v tabulce použijte dotazovací jazyk Kusto (KQL). Příklad dotazu: traces | where message contains "YourSearchTerm".
Zpřesněte dotazy a vyfiltrujte data ILoggeru podle závažnosti, časového rozsahu nebo konkrétního obsahu zprávy.

V sadě Visual Studio (místní ladicí program):

Spusťte aplikaci v režimu ladění v sadě Visual Studio.
Při spuštění aplikace otevřete okno Diagnostické nástroje.
Na kartě Události se zobrazí protokoly ILogger spolu s dalšími telemetrickými daty.
Pokud chcete vyhledat konkrétní zprávy ILogger, použijte funkce vyhledávání a filtrování v okně Diagnostické nástroje .

Pokud chcete vždy odesílat TraceTelemetry, použijte tento fragment kódu:

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

Proč některé protokoly ILoggeru nemají stejné vlastnosti jako jiné?

Application Insights zaznamenává a odesílá protokoly ILogger pomocí stejných TelemetryConfiguration informací, které se používají pro každou jinou telemetrii. Ale je tu výjimka. Ve výchozím nastavení TelemetryConfiguration se při přihlašování z Program.cs nebo Startup.cs úplně nenastaví. Protokoly z těchto míst nemají výchozí konfiguraci, takže nespouštět všechny TelemetryInitializer instance a TelemetryProcessor instance.

Používám samostatný balíček Microsoft.Extensions.Logging.ApplicationInsights a chci ručně protokolovat další vlastní telemetrii. Jak to mám udělat?

Pokud použijete samostatný balíček, TelemetryClient nevkážou se do kontejneru injektáže závislostí (DI). Potřebujete vytvořit novou instanci TelemetryClient a použít stejnou konfiguraci, kterou používá zprostředkovatel loggeru, jak ukazuje následující kód. Tento požadavek zajišťuje, aby se stejná konfigurace používala pro veškerou vlastní telemetrii a telemetrii z 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;
   }  
}

Poznámka:

Pokud balíček použijete Microsoft.ApplicationInsights.AspNetCore k povolení Application Insights, upravte tento kód tak, aby se dostal TelemetryClient přímo do konstruktoru.

Nemám nainstalovanou sadu SDK a k povolení Application Insights pro aplikace ASP.NET Core používám rozšíření Azure Web Apps. Návody použít nového poskytovatele?

Rozšíření Application Insights ve službě Azure Web Apps používá nového poskytovatele. Pravidla filtrování můžete upravit v souboru appsettings.json pro vaši aplikaci.

Sdílet prostřednictvím