.NET Core ve ASP.NET Core'da günlük

  • Makale

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz . .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 8 sürümüne bakın.

Kirk Larkin, Juergen Gutsch ve Rick Anderson

Bu makalede, ASP.NET Core uygulamaları için geçerli olduğu için .NET'te günlüğe kaydetme işlemi açıklanmaktadır. .NET'te günlük hakkında ayrıntılı bilgi için bkz. .NET'te günlük.

Blazor Bu düğümdeki yönergeleri ekleyen veya bunların yerini alan günlüğe kaydetme kılavuzu için bkz. ASP.NET Çekirdek Blazor günlüğü.

Günlük sağlayıcıları

Günlükleri görüntüleyen Console sağlayıcısı dışında, günlük sağlayıcıları günlükleri depolar. Örneğin Azure Application Insights sağlayıcısı günlükleri Azure Application Insights'da depolar. Birden fazla sağlayıcı etkinleştirilebilir.

Varsayılan ASP.NET Core web uygulaması şablonları, aşağıdaki günlük sağlayıcılarını ekleyen öğesini çağırır WebApplication.CreateBuilder:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Yukarıdaki kod ASP.NET Core web uygulaması şablonlarıyla oluşturulan Program.cs dosyasını gösterir. Sonraki birkaç bölümde ASP.NET Core web uygulaması şablonlarına dayalı örnekler sağlanır.

Aşağıdaki kod WebApplication.CreateBuilder tarafından eklenen varsayılan günlük sağlayıcıları kümesini geçersiz kılar:

var builder = WebApplication.CreateBuilder(args);
builder.Logging.ClearProviders();
builder.Logging.AddConsole();

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Alternatif olarak, yukarıdaki günlük kodu şöyle de yazılabilir:

var builder = WebApplication.CreateBuilder();
builder.Host.ConfigureLogging(logging =>
{
    logging.ClearProviders();
    logging.AddConsole();
});

Ek sağlayıcılar için bkz:

Günlükleri oluşturma

Günlük oluşturmak için bağımlılık ekleme (DI) tasarım deseninden ILogger<TCategoryName> nesnesini kullanın.

Aşağıdaki örnek:

  • AboutModel türündeki tam adın günlük kategorisini kullanan ILogger<AboutModel> günlükçüsünü oluşturur. Günlük kategorisi, her günlükle ilişkilendirilen bir dizedir.
  • Information düzeyinde günlüğe kaydetmek için LogInformation yöntemini çağırır. Günlük düzeyi günlüğe kaydedilen olayın önem derecesini gösterir.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("About page visited at {DT}", 
            DateTime.UtcNow.ToLongTimeString());
    }
}

Düzeyler ve kategoriler bu belgenin devamında daha ayrıntılı olarak açıklanır.

Blazor hakkında bilgi için bkz. ASP.NET Core Blazor günlüğü.

Günlük kaydetmeyi yapılandırma

Günlük yapılandırması genellikle appsettings.{ENVIRONMENT}.json dosyalarının Logging bölümü tarafından sağlanır; burada {ENVIRONMENT} yer tutucusu ortamdır. Aşağıdaki appsettings.Development.json dosyası ASP.NET Core web uygulaması şablonları tarafından oluşturulur:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  }
}

Yukarıdaki JSON kodunda:

  • "Default" ve "Microsoft.AspNetCore" kategorileri belirtilir.
  • "Microsoft.AspNetCore" kategorisi "Microsoft.AspNetCore" ile başlayan tüm kategorilere uygulanır. Örneğin bu ayar "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorisine uygulanır.
  • "Microsoft.AspNetCore" kategorisi Warning veya daha yüksek günlük düzeyinde günlüğe kaydedilir.
  • Belirli bir günlük sağlayıcısı belirtilmez, dolayısıyla LogLevel Windows EventLog dışında tüm etkinleştirilmiş günlük sağlayıcılarına uygulanır.

Logging özelliğinin LogLevel ve günlük sağlayıcısı özellikleri olabilir. LogLevel, seçili kategorileri günlüğe kaydetmek için en düşük düzeyi belirtir. Önceki JSON'da Information ve Warning günlük düzeyleri belirtilir. LogLevel günlüğün önem derecesini gösterir ve 0 ile 6 arasında değişir:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 ve None = 6.

LogLevel belirtildiğinde, belirtilen ve daha yüksek düzeydeki iletiler için günlük etkinleştirilir. Önceki JSON'da, Default kategori ve üzeri için Information günlüğe kaydedilir. Örneğin Information, Warning, Error ve Critical iletileri günlüğe kaydedilir. LogLevel belirtilmezse günlüğe kaydetme için varsayılan Information düzeyi kullanılır. Daha fazla bilgi için bkz. Günlük düzeyleri.

Sağlayıcı özelliği bir LogLevel özelliği belirtebilir. Sağlayıcının altındaki LogLevel, söz konusu sağlayıcı için günlüğe alınacak düzeyleri belirtir ve sağlayıcı dışı günlük ayarlarını geçersiz kılar. Aşağıdaki appsettings.json dosyasını göz önünde bulundurun:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Logging.{PROVIDER NAME}.LogLevel sağlayıcısındaki ayarlar Logging.LogLevel ayarlarını geçersiz kılar; burada {PROVIDER NAME} yer tutucusu sağlayıcı adıdır. Yukarıdaki JSON'da sağlayıcının Debug varsayılan günlük düzeyi olarak Informationayarlanır:

Logging:Debug:LogLevel:Default:Information

Yukarıdaki ayar Microsoft.Hosting dışındaki tüm Logging:Debug: kategorileri için Information günlük düzeyini belirtir. Belirli bir kategori listelendiğinde, listelenen kategori varsayılan kategoriyi geçersiz kılar. Önceki JSON'da, Logging:Debug:LogLevel içindeki ayarları Logging:LogLevelkategoriler "Microsoft.Hosting" ve "Default" geçersiz kılar.

Aşağıdakiler için en düşük günlük düzeyi belirtilebilir:

  • Belirli sağlayıcılar: Örneğin Logging:EventSource:LogLevel:Default:Information
  • Belirli kategoriler: Örneğin Logging:LogLevel:Microsoft:Warning
  • Tüm sağlayıcılar ve tüm kategoriler: Logging:LogLevel:Default:Warning

En düşük düzeyin altındaki günlükler:

  • Sağlayıcıya geçirilmez.
  • Günlüğe kaydedilmez veya görüntülenmez.

Tüm günlükleri engellemek için LogLevel.None belirtin. LogLevel.None değeri 6'dır ve bu değer LogLevel.Critical (5) değerinden yüksektir.

Sağlayıcı günlük kapsamlarını destekliyorsa IncludeScopes bunların etkinleştirilip etkinleştirilmediğini gösterir. Daha fazla bilgi için bkz. Günlük kapsamları.

Aşağıdaki appsettings.json dosyası varsayılan olarak etkinleştirilen tüm sağlayıcıları içerir:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Yukarıdaki örnekte:

  • Kategoriler ve düzeyler önerilen değerler değildir. Örnek, tüm varsayılan sağlayıcıları göstermek için sağlanır.
  • Logging.{PROVIDER NAME}.LogLevel sağlayıcısındaki ayarlar Logging.LogLevel ayarlarını geçersiz kılar; burada {PROVIDER NAME} yer tutucusu sağlayıcı adıdır. Örneğin Debug.LogLevel.Default düzeyi LogLevel.Default düzeyini geçersiz kılar.
  • Her varsayılan sağlayıcı diğer adı kullanılır. Her sağlayıcı, yapılandırmada tam tür adı yerine kullanılacak bir diğer ad tanımlar. Yerleşik sağlayıcı diğer adları şunlardır:
    • Console
    • Debug
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Program.cs dosyasında günlüğe kaydetme

Aşağıdaki örnekte Program.cs dosyasında Builder.WebApplication.Logger yöntemi çağrılır ve bilgilendirme iletileri günlüğe kaydedilir:

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
app.Logger.LogInformation("Adding Routes");
app.MapGet("/", () => "Hello World!");
app.Logger.LogInformation("Starting the app");
app.Run();

Aşağıdaki örnekte Program.cs dosyasında AddConsole yöntemi çağrılır ve /Test uç noktası günlüğe kaydedilir:

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddConsole();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

Aşağıdaki örnekte Program.cs dosyasında AddSimpleConsole yöntemi çağrılır, renk çıkışı devre dışı bırakılır ve /Test uç noktası günlüğe kaydedilir:

using Microsoft.Extensions.Logging.Console;

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(i => i.ColorBehavior = LoggerColorBehavior.Disabled);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.MapGet("/Test", async (ILogger<Program> logger, HttpResponse response) =>
{
    logger.LogInformation("Testing logging in Program.cs");
    await response.WriteAsync("Testing");
});

app.Run();

Komut satırı, ortam değişkenleri ve başka bir yapılandırmayla günlük düzeyini ayarlama

Günlük düzeyi yapılandırma sağlayıcılarının herhangi biri tarafından ayarlanabilir.

: ayıracı, tüm platformlarda ortam değişkeni hiyerarşik anahtarlarıyla çalışmaz. Örneğin, : ayırıcı Bash tarafından desteklenmez. Çift alt çizgi olan , __şöyledir:

  • Tüm platformlar tarafından desteklenir.
  • otomatik olarak iki nokta üst üste ile :değiştirilir.

Aşağıdaki komutlar:

  • Windows'da Logging:LogLevel:Microsoft ortam anahtarını Information değerine ayarlar.
  • ASP.NET Core web uygulaması şablonlarıyla oluşturulan bir uygulamayı kullanırken ayarları test edin. set kullanıldıktan sonra proje dizininde dotnet run komutu çalıştırılmalıdır.
set Logging__LogLevel__Microsoft=Information
dotnet run

Önceki ortam ayarı:

  • Yalnızca ayarlandığı komut penceresinden başlatılan işlemlerde ayarlanır.
  • Visual Studio ile başlatılan tarayıcılar tarafından okunmaz.

Aşağıdaki setx komutu Windows'da ortam anahtarını ve değerini de ayarlar. set öğesinin aksine setx ayarları kalıcıdır. /M anahtarı, değişkeni sistem ortamında ayarlar. /M kullanılmazsa bir kullanıcı ortamı değişkeni ayarlanır.

setx Logging__LogLevel__Microsoft Information /M

Aşağıdaki appsettings.json dosyasını göz önünde bulundurun:

"Logging": {
  "Console": {
    "LogLevel": {
      "Microsoft.Hosting.Lifetime": "Trace"
    }
  }
}

Aşağıdaki komut ortamda önceki yapılandırmayı ayarlar:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Not

macOS ve Linux'ta (nokta) içeren . adlarla ortam değişkenlerini yapılandırırken, "Bir değişkeni nokta (.) ile dışarı aktarma" konusunu göz önünde bulundurun. "Stack Exchange'deki soru ve buna karşılık gelen kabul edilen yanıt.

Azure App Service üzerinde Ayarlar >Yapılandırması sayfasında Yeni uygulama ayarını seçin. Azure App Service uygulama ayarları şunlardır:

  • Şifrelenmiş bir kanalda rest şifrelenir ve bu kanal üzerinden iletilir.
  • Ortam değişkenleri olarak kullanıma sunulur.

Daha fazla bilgi için bkz. Azure Uygulaması s: Azure portalını kullanarak uygulama yapılandırmasını geçersiz kılma.

Ortam değişkenlerini kullanarak ASP.NET Core yapılandırma değerlerini ayarlama hakkında daha fazla bilgi için bkz. Ortam değişkenleri. Komut satırı, Azure Key Vault, Azure Uygulama Yapılandırması ve diğer dosya biçimleri de dahil olmak üzere diğer yapılandırma kaynaklarını kullanma hakkında bilgi için bkz. ASP.NET Core'da yapılandırma.

Filtreleme kuralları nasıl uygulanır?

Bir ILogger<TCategoryName> nesnesi oluşturulduğunda ILoggerFactory nesnesi bu günlükçüye uygulamak üzere sağlayıcı başına tek bir kural seçer. ILogger örneği tarafından yazılan tüm iletiler seçilen kurallar temelinde filtrelenir. Kullanılabilir kurallar arasından her sağlayıcı ve kategori çifti için en belirgin kural seçilir.

Belirli bir kategori için ILogger oluşturulduğunda her sağlayıcı için aşağıdaki algoritma kullanılır:

  • Sağlayıcıyla veya sağlayıcının diğer adıyla eşleşen tüm kuralları seçin. Eşleşme bulunamazsa sağlayıcısı boş olan tüm kurallar seçilir.
  • Önceki adımın sonucundan, eşleşen kategori ön eki en uzun olan kuralları seçin. Eşleşme bulunamazsa bir kategori belirtmeyen tüm kuralları seçin.
  • Birden çok kural seçildiyse, sonuncusunu alın.
  • Hiçbir kural seçilmezse MinimumLevel kullanın.

Dotnet çalıştırması ve Visual Studio'dan gelen çıkışı günlüğe kaydetme

Varsayılan günlük sağlayıcılarıyla oluşturulan günlükler görüntülenir:

  • Visual Studio'da
    • Hata ayıklama sırasında Hata Ayıklama çıkışı penceresinde.
    • ASP.NET Core Web Sunucusu penceresinde.
  • Uygulama dotnet run ile çalıştırıldığında konsol penceresinde.

"Microsoft" kategorileriyle başlayan günlükler .NET'ten alınır. .NET ve uygulama kodu aynı günlük API'sini ve sağlayıcılarını kullanır.

Günlük kategorisi

ILogger nesnesi oluşturulduğunda bir kategori belirtilir. Söz konusu kategori bu ILogger örneğiyle oluşturulan her günlük iletisine eklenir. Kategori dizesi rastgeledir, ancak kural tam sınıf adını kullanmaktır. Örneğin bir denetleyicide "TodoApi.Controllers.TodoController" adı kullanılabilir. ASP.NET Core web uygulamaları, kategori olarak T tam tür adını kullanan bir ILogger örneğini otomatik olarak almak için ILogger<T> kullanır:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Daha fazla kategori isteniyorsa, kural tam sınıf adına bir alt kategori ekleyerek hiyerarşik bir ad kullanmak ve kullanarak ILoggerFactory.CreateLoggerkategoriyi açıkça belirtmektir:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Birden çok yöntemde kullanıldığında CreateLogger yöntemini sabit bir adla çağırmak yararlı olabilir çünkü olaylar kategoriye göre düzenlenebilir.

ILogger<T>, T tam tür adıyla CreateLogger yöntemini çağırmanın eşdeğeridir.

Günlük düzeyi

Aşağıdaki tabloda LogLevel değerleri, uygun Log{LogLevel} uzantısı yöntemi ve önerilen kullanım listelenir:

GünlükDüzeyi Değer Metot Açıklama
Trace 0 LogTrace En ayrıntılı iletileri içerir. Bu iletiler hassas uygulama verileri içerebilir. Bu iletiler varsayılan olarak devre dışı bırakılmıştır ve üretimde etkinleştirilmemesi gerekir.
Debug 1 LogDebug Hata ayıklama ve geliştirme için. Yüksek hacim nedeniyle üretimde dikkatli kullanın.
Information 2 LogInformation Uygulamanın genel akışını izler. Uzun süreli bir değeri olabilir.
Warning 3 LogWarning Anormal veya beklenmeyen olaylar için. Normalde uygulamanın başarısız olmasına neden olmayan hataları veya koşulları içerir.
Error 4 LogError İşlenemeyen hatalar ve özel durumlar için. Bu iletiler uygulama genelindeki bir hatayı değil geçerli işlem veya istekteki hatayı gösterir.
Critical 5 LogCritical Hemen ilgilenilmesi gereken hatalar için. Örnekler: veri kaybı senaryoları, yetersiz disk alanı.
None 6 Bir günlük kategorisinin ileti yazmaması gerektiğini belirtir.

Yukarıdaki tabloda LogLevel en düşük önem derecesinden en yükseğe doğru listelenmiştir.

Log yönteminin ilk parametresi olan LogLevel günlüğün önem derecesini gösterir. Log(LogLevel, ...) yöntemini çağırmak yerine, geliştiricilerin çoğu Log{LOG LEVEL} uzantı yöntemlerini çağırır; burada {LOG LEVEL} yer tutucusu günlük düzeyidir. Örneğin aşağıdaki iki günlük çağrısı işlevsel açıdan eşdeğerdir ve aynı günlüğü oluşturur:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem olay kimliğidir. MyLogEvents örnek uygulamanın bir parçasıdır ve Günlük olayı kimliği bölümünde görüntülenir.

MyDisplayRouteInfo ve ToCtxString, Rick.Docs.Samples.RouteInfo NuGet paketi tarafından sağlanır. Yöntemler Controller ve Razor Page yönlendirme bilgilerini görüntüler.

Aşağıdaki kod Information ve Warning günlüklerini oluşturur:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Yukarıdaki kodda ilk Log{LOG LEVEL} parametresi olan MyLogEvents.GetItem Günlük olayı kimliğidir. İkinci parametre, kalan yöntem parametreleri tarafından sağlanan bağımsız değişken değerleri için yer tutucular içeren bir ileti şablonudur. Yöntem parametreleri bu belgenin devamındaki ileti şablonu bölümünde açıklanır.

Belirli bir depolama ortamına ne kadar günlük çıkışı yazılacağını denetlemek için uygun Log{LOG LEVEL} yöntemini çağırın. Örneğin:

  • Üretimde:
    • , Debugveya Information düzeylerinde günlüğe Tracekaydetmek, yüksek hacimli ayrıntılı günlük iletileri oluşturur. Maliyetleri denetlemek ve veri depolama sınırlarını aşmamak için, iletileri yüksek hacimli, düşük maliyetli bir veri deposuna günlüğe kaydetme TraceDebugveya Information düzeylendirme. , veya DebugInformation öğesini Tracebelirli kategorilerle sınırlamayı göz önünde bulundurun.
    • Warning ile Critical düzeyleri arasını günlüğe kaydetmek az sayıda günlük iletisi oluşturmalıdır.
      • Maliyetler ve depolama sınırları genellikle sorun değildir.
      • Az sayıda günlük veri deposu seçimlerine daha fazla esneklik getirir.
  • Geliştirme aşamasında:
    • Warning olarak ayarlayın.
    • Sorun giderme sırasında , Debugveya Information iletileri ekleyinTrace. Çıkışı sınırlamak için, , Debugveya Information yalnızca araştırma altındaki kategoriler için ayarlayınTrace.

ASP.NET Core çerçeve olayları için günlük yazar. Örneğin aşağıdakiler için günlük çıkışını düşünün:

  • ASP.NET Core şablonlarıyla oluşturulan Razor Pages uygulaması.
  • Logging:Console:LogLevel:Microsoft:Information olarak ayarlanmış günlük.
  • Privacy sayfasına gezinti:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Aşağıdaki JSON kümeleri Logging:Console:LogLevel:Microsoft:Information:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

Günlük olayı kimliği

Her günlük bir olay kimliği belirtebilir. Örnek uygulama olay kimliklerini tanımlamak için MyLogEvents sınıfını kullanır:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Olay kimliği bir dizi olayı ilişkilendirir. Örneğin sayfadaki öğelerin listesini görüntülemeyle ilgili tüm günlükler 1001 olabilir.

Günlük sağlayıcısı olay kimliğini bir kimlik alanında veya günlüğe kaydetme iletisinde depolayabilir ya da hiç depolamaz. Hata ayıklama sağlayıcıları olay kimliklerini göstermez. Konsol sağlayıcısı olay kimliklerini kategorinin arkasında köşeli ayraç içinde gösterir:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Bazı günlük sağlayıcıları olay kimliğini bir alanda depolar ve bu sayede kimliğe göre filtre uygulanabilir.

Günlük iletisi şablonu

Her günlük API'si bir ileti şablonu kullanır. İleti şablonu bağımsız değişkenlerin sağlandığı yer tutucular içerebilir. Yer tutucular için sayı değil ad kullanın.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Günlük iletilerinde yer tutucu değerlerini sağlamak için hangi parametrelerin kullanılacağını yer tutucu adları değil parametrelerin sırası belirler. Aşağıdaki kodda, ileti şablonunun yer tutucularında parametre adları sıralı değildir:

var apples = 1;
var pears = 2;
var bananas = 3;

_logger.LogInformation("Parameters: {Pears}, {Bananas}, {Apples}", apples, pears, bananas);

Bununla birlikte parametreler yer tutuculara sırayla atanır: apples, pears, bananas. Günlük iletisi parametrelerin sırasını yansıtır:

Parameters: 1, 2, 3

Bu yaklaşım günlük sağlayıcılarının anlamsal veya yapılandırılmış günlük uygulamalarına olanak tanır. Bağımsız değişkenlerin kendileri yalnızca biçimlendirilmiş ileti şablonuna değil günlük sistemine geçirilir. Bu sayede günlük sağlayıcıları parametre değerlerini alanlar olarak depolayabilir. Örneğin, aşağıdaki günlükçü yöntemini ele alalım:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Örneğin Azure Tablo Depolama'da oturum açarken:

  • Her Azure Tablo varlığının ID ve RequestTime özellikleri olabilir.
  • Özellikleri olan tablolar, günlüğe kaydedilmiş veriler üzerinde çalıştırılan sorguları basitleştirir. Örneğin bir sorgu, metin iletisinden zamanı ayıklamak zorunda kalmadan belirli bir RequestTime aralığındaki tüm günlükleri bulabilir.

Günlük özel durumları

Günlükçü yöntemlerinde özel durum parametresi alan aşırı yüklemeler vardır:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo ve ToCtxString, Rick.Docs.Samples.RouteInfo NuGet paketi tarafından sağlanır. Yöntemler Controller ve Razor Page yönlendirme bilgilerini görüntüler.

Özel durum günlüğü sağlayıcıya özgüdür.

Varsayılan günlük düzeyi

Varsayılan günlük düzeyi ayarlanmazsa, varsayılan günlük değeri Information olur.

Örneğin aşağıdaki web uygulamasını ele alalım:

  • ASP.NET web uygulaması şablonlarıyla oluşturulmuştur.
  • appsettings.json ve appsettings.Development.json silinmiş veya yeniden adlandırılmıştır.

Önceki kurulumda, veya sayfasına gitmekprivacy, kategori adında ile Microsoft birçok Trace, Debugve Information iletisi oluşturur.home

Varsayılan günlük düzeyi yapılandırmada ayarlanmadığında, aşağıdaki kod varsayılan günlük düzeyini ayarlar:

var builder = WebApplication.CreateBuilder();
builder.Logging.SetMinimumLevel(LogLevel.Warning);

Genel olarak günlük düzeyleri kodda değil yapılandırmada belirtilmelidir.

Filter işlevi

Yapılandırma veya kod tarafından kendilerine atanmış kuralları olmayan tüm sağlayıcılar ve kategoriler için filtre işlevi çağrılır:

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter((provider, category, logLevel) =>
{
    if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Controller")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else if (provider.Contains("ConsoleLoggerProvider")
        && category.Contains("Microsoft")
        && logLevel >= LogLevel.Information)
    {
        return true;
    }
    else
    {
        return false;
    }
});

Yukarıdaki kod, kategori Controller veya Microsoft içerdiğinde ve günlük düzeyi Information veya daha yüksek olduğunda konsol günlüklerini görüntüler.

Genel olarak günlük düzeyleri kodda değil yapılandırmada belirtilmelidir.

ASP.NET Çekirdek kategorileri

Aşağıdaki tabloda ASP.NET Core tarafından kullanılan bazı kategoriler yer alır.

Kategori Notlar
Microsoft.AspNetCore Genel ASP.NET Core tanılamaları.
Microsoft.AspNetCore.DataProtection Hangi anahtarların değerlendirildiği, bulunduğu ve kullanıldığı.
Microsoft.AspNetCore.HostFiltering İzin verilen konaklar.
Microsoft.AspNetCore.Hosting HTTP isteklerini tamamlamanın ne kadar sürdüğü ve bunların ne zaman başlatıldığı. Hangi barındırma başlangıç derlemelerinin yüklendiği.
Microsoft.AspNetCore.Mvc MVC ve Razor tanılamaları. Model bağlama, filtre yürütme, görünüm derleme, eylem seçimi.
Microsoft.AspNetCore.Routing Yönlendirmeyi eşleştirme bilgileri.
Microsoft.AspNetCore.Server Bağlantı başlatma, durdurma ve etkin tutma yanıtları. HTTPS sertifikası bilgileri.
Microsoft.AspNetCore.StaticFiles Sunulan dosyalar.

Konsol penceresinde daha fazla kategori görüntülemek için appsettings.Development.json dosyasını aşağıdaki gibi ayarlayın:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Entity Framework kategorilerinin listesi için bkz . EF İleti kategorileri.

Günlük kapsamları

Kapsam, bir dizi mantıksal işleci gruplandırabilir. Bu gruplandırma bir kümenin parçası olarak oluşturulan her günlüğe aynı verileri eklemek için kullanılabilir. Örneğin bir işlemi gerçekleştirmenin parçası olarak oluşturulan her günlük işlem kimliğini içerebilir.

Kapsam:

Aşağıdaki sağlayıcılar kapsamları destekler:

Bir kapsamı, günlükçü çağrılarını using bloğunda sarmalayarak kullanın:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();
    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Yerleşik günlük sağlayıcıları

ASP.NET Core, paylaşılan çerçevenin bir parçası olarak aşağıdaki günlük sağlayıcılarını içerir:

Aşağıdaki günlük sağlayıcıları Microsoft tarafından gönderilir ama paylaşılan çerçevenin parçası olarak gönderilmez. Ek nuget olarak yüklenmeleri gerekir.

ASP.NET Core günlükleri dosyalara yazmaya yönelik bir günlük sağlayıcısı içermez. ASP.NET Core uygulamasından günlükleri dosyalara yazmak için üçüncü taraf bir günlük sağlayıcısı kullanmayı göz önünde bulundurun.

stdout ve ASP.NET Core Modülü ile hata ayıklama günlüğü hakkında bilgi için bkz. Azure App Service ve IIS'de ASP.NET Core sorunlarını giderme ve IIS için ASP.NET Core Modülü (ANCM).

Konsol

Console sağlayıcısı günlüklerin çıkışını konsola yönlendirir. Geliştirmedeki Console günlüklerini görüntüleme hakkında daha fazla bilgi için bkz. Dotnet çalıştırması ve Visual Studio'dan gelen çıkışı günlüğe kaydetme.

Hata Ayıklama

Debug sağlayıcısı günlük çıkışını yazarken System.Diagnostics.Debug sınıfını kullanır. System.Diagnostics.Debug.WriteLine çağrıları Debug sağlayıcısına yazar.

Linux'ta Debug sağlayıcısının günlük konumu dağıtıma bağımlıdır ve aşağıdakilerden biri olabilir:

  • /var/log/message
  • /var/log/syslog

Olay Kaynağı

EventSource sağlayıcısı Microsoft-Extensions-Logging adıyla bir platformlar arası olay kaynağına yazar. Windows'da sağlayıcı ETW kullanır.

dotnet-trace araçları

dotnet-trace aracı, çalışan işlemin .NET Core izlemelerini toplamaya olanak tanıyan, platformlar arası bir CLI genel aracıdır. Araç bir LoggingEventSource kullanarak Microsoft.Extensions.Logging.EventSource sağlayıcı verilerini toplar.

Yükleme yönergeleri için bkz. dotnet-trace.

Uygulamadan izleme toplamak için dotnet-trace aracını kullanın:

  1. Uygulamayı dotnet run komutuyla çalıştırın.

  2. .NET Core uygulamasının işlem tanımlayıcısını (PID) belirleyin:

    dotnet-trace ps

    Uygulamanın derlemesiyle aynı adı taşıyan işlemin PID değerini bulun.

  3. dotnet-trace komutunu yürütün.

    Genel komut söz dizimi:

    dotnet-trace collect -p {PID} 
    --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"

    PowerShell komut kabuğu kullanıldığında --providers değerini tek tırnak içine alın ('):

    dotnet-trace collect -p {PID} 
    --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"'

    Windows dışındaki platformlarda çıkış izleme dosyasının biçimini speedscope olarak değiştirmek için -f speedscope seçeneğini ekleyin.

    Aşağıdaki tabloda Anahtar Sözcükler tanımlanır:

    Anahtar sözcük Açıklama
    1 LoggingEventSource hakkındaki meta olaylarını günlüğe kaydeder. ILogger kaynaklı olayları günlüğe kaydetmez.
    2 ILogger.Log() çağrıldığında bile Message olayını açar. Bilgileri programlama yoluyla (biçimlendirilmemiş olarak) sağlar.
    4 ILogger.Log() çağrıldığında bile FormatMessage olayını açar. Bilgilerin biçimlendirilmiş dize sürümünü sağlar.
    8 ILogger.Log() çağrıldığında bile MessageJson olayını açar. Bağımsız değişkenlerin JSON gösterimini sağlar.

    Aşağıdaki tabloda sağlayıcı düzeyleri listelenir:

    Sağlayıcı Düzeyi Açıklama
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    Kategori düzeyi için ayrıştırma bir dize veya sayı olabilir:

    Kategori adlandırılmış değeri Sayısal değer
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    Sağlayıcı düzeyi ve kategori düzeyi:

    • Ters sıradadır.
    • Dize sabitlerinin tümü aynı değildir.

    Hiçbir FilterSpecs belirtilmezse EventSourceLogger uygulaması sağlayıcı düzeyini bir kategori düzeyine dönüştürmeyi dener ve tüm kategorilere uygular.

    Sağlayıcı Düzeyi Kategori Düzeyi
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    FilterSpecs sağlanırsa, listeye eklenen her kategori burada kodlanan kategori düzeyini kullanır; diğer tüm kategoriler filtrelenir.

    Aşağıdaki örneklerde şunlar varsayılır:

    • Bir uygulama çalışıyor ve logger.LogDebug("12345") çağrısı yapıyor.
    • İşlem kimliği (PID) set PID=12345 yoluyla ayarlandı ve burada 12345 gerçek PID'yi gösteriyor.

    Aşağıdaki komutu inceleyin:

    dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5

    Yukarıdaki komut:

    • Hata ayıklama iletilerini yakalar.
    • FilterSpecs uygulamaz.
    • Hata Ayıklama kategorisine eşlenen 5. düzeyi belirtir.

    Aşağıdaki komutu inceleyin:

    dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"

    Yukarıdaki komut:

    • 5. kategori düzeyi Critical olduğundan hata ayıklama iletilerini yakalamaz.
    • Bir FilterSpecs sağlar.

    1. kategori düzeyi Debug olduğundan aşağıdaki komut hata ayıklama iletilerini yakalar.

    dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"

    Kategori olarak Debug belirtildiğinden aşağıdaki komut hata ayıklama iletilerini yakalar.

    dotnet-trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"

    {Logger Category} ve {Category Level} için FilterSpecs girdileri, ek günlük filtreleme koşullarını temsil eder. FilterSpecs girdilerini ; noktalı virgül karakteriyle ayırın.

    Windows komut kabuğunun kullanıldığı örnek:

    dotnet-trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"

    Yukarıdaki komut:

    • Hatalar (2) için biçimlendirilmiş dizeler (4) oluşturmak üzere Olay Kaynağı günlükçüsünü etkinleştirir.
    • Informational günlük düzeyinde (4) Microsoft.AspNetCore.Hosting günlüğünü etkinleştirir.

  4. Enter tuşuna dotnet-trace veya Ctrl+C tuşuna basarak aracı durdurun.

    İzleme, dotnet-trace komutunun yürütüldüğü klasörde trace.nettrace adıyla kaydedilir.

  5. İzlemeyi Perfview ile açın. trace.nettrace dosyasını açın ve izleme olaylarını inceleyin.

Uygulama WebApplication.CreateBuilder ile konağı oluşturmuyorsa, Olay Kaynağı sağlayıcısını uygulamanın günlük yapılandırmasına ekleyin.

Daha fazla bilgi için bkz.

Perfview

Günlükleri toplamak ve görüntülemek için PerfView yardımcı programını kullanın. ETW günlüklerini görüntülemeye yönelik başka araçlar vardır ama PerfView, ASP.NET Core tarafından yayılan ETW olaylarıyla çalışmak için en iyi deneyimi sağlar.

PerfView'u bu sağlayıcı tarafından günlüğe kaydedilen olayları toplayacak şekilde yapılandırmak için Ek Sağlayıcılar listesine *Microsoft-Extensions-Logging dizesini ekleyin. Dizenin başındaki * işaretini unutmayın.

Windows EventLog

EventLog sağlayıcısı günlük çıkışını Windows Olay Günlüğü'ne gönderir. Diğer sağlayıcılardan farklı olarak, EventLog sağlayıcısı varsayılan sağlayıcı dışı ayarları devralmaz. EventLog günlük ayarları belirtilmezse, varsayılan olarak LogLevel.Warning kullanılır.

LogLevel.Warning düzeyinden daha düşük düzeyli olayları günlüğe kaydetmek için günlük düzeyini açıkça ayarlayın. Aşağıdaki örnek Olay Günlüğü varsayılan günlük düzeyini LogLevel.Information olarak ayarlar:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog aşırı yüklemeleri EventLogSettings sınıfında geçirilebilir. null belirtilirse veya hiç belirtilmezse aşağıdaki varsayılan ayarlar kullanılır:

  • LogName: "Uygulama"
  • SourceName: ".NET Çalışma Zamanı"
  • MachineName: Yerel makine adı kullanılır.

Aşağıdaki kod varsayılan değeri ".NET Runtime" olan SourceName ayarını MyLogs olarak değiştirir:


var builder = WebApplication.CreateBuilder();
builder.Logging.AddEventLog(eventLogSettings =>
{
    eventLogSettings.SourceName = "MyLogs";
});

Azure App Service

Microsoft.Extensions.Logging.AzureAppServices sağlayıcı paketi günlükleri Azure App Service uygulamasının dosya sistemindeki metin dosyalarına ve bir Azure Depolama hesabındaki blob depolamasına yazar.

Sağlayıcı paketi paylaşılan çerçeveye dahil değildir. Sağlayıcıyı kullanmak için sağlayıcı paketini projeye ekleyin.

Sağlayıcı ayarlarını yapılandırmak için, aşağıdaki örnekte gösterildiği gibi AzureFileLoggerOptions ve AzureBlobLoggerOptions kullanın:

using Microsoft.Extensions.Logging.AzureAppServices;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddAzureWebAppDiagnostics();
builder.Services.Configure<AzureFileLoggerOptions>(options =>
{
    options.FileName = "azure-diagnostics-";
    options.FileSizeLimit = 50 * 1024;
    options.RetainedFileCountLimit = 5;
});
builder.Services.Configure<AzureBlobLoggerOptions>(options =>
{
    options.BlobName = "log.txt";
});

Azure App Service'e dağıtıldığında, uygulama bu ayarları Azure portaldaki App Service sayfasının App Service günlükleri bölümünde kullanır. Aşağıdaki ayarlar güncelleştirildiğinde, uygulamanın yeniden başlatılması veya yeniden dağıtılması gerekmeden değişiklikler hemen geçerlilik kazanır.

  • Application Logging (Dosya Sistemi)
  • Application Logging (Blob)

Günlük dosyalarının varsayılan konumu D:\\home\\LogFiles\\Application klasörü içindedir ve varsayılan dosya adı diagnostics-yyyymmdd.txt şeklindedir. Varsayılan dosya boyutu sınırı 10 MB'tır ve varsayılan saklanan dosya sayısı üst sınırı 2'dir. Varsayılan blob adı {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt şeklindedir.

Bu sağlayıcı yalnızca proje Azure ortamında çalıştırıldığında günlüğe kaydeder.

Azure günlük akışı

Azure günlük akışı, günlük etkinliğini şu konumlardan gerçek zamanlı olarak görüntülemeyi destekler:

  • Uygulama sunucusu
  • Web sunucusu
  • Başarısız istek izlemesi

Azure günlük akışını yapılandırmak için:

  • Uygulamanın portal sayfasından App Service günlükleri sayfasına gidin.
  • Application Logging (Dosya Sistemi) seçeneğini Açık olarak ayarlayın.
  • Günlük Düzeyini seçin. Bu ayar yalnızca Azure günlük akışı için geçerlidir.

Günlükleri görüntülemek için Günlük Akışı sayfasına gidin. Günlüğe kaydedilen iletiler ILogger arabirimiyle günlüğe kaydedilir.

Azure Application Insights

Microsoft.Extensions.Logging.ApplicationInsights sağlayıcı paketi günlükleri Azure Application Insights'a yazar. Application Insights, web uygulamasını izleyen ve telemetri verilerini sorgulamak ve analiz etmek için araçlar sağlayan bir hizmettir. Bu sağlayıcıyı kullanıyorsanız Application Insights araçlarını kullanarak günlüklerinizi sorgulayabilir ve analiz edebilirsiniz.

Günlük sağlayıcısı, ASP.NET Core için tam kullanılabilir telemetri verilerini sağlayan Microsoft.ApplicationInsights.AspNetCore paketinin bağımlılığı olarak eklenir. Bu paketi kullanıyorsanız sağlayıcı paketini yüklemeniz gerekmez.

Microsoft.ApplicationInsights.Web paketi ASP.NET Core'a değil ASP.NET 4.x'e yöneliktir.

Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

Üçüncü taraf günlük sağlayıcıları

ASP.NET Core ile çalışan üçüncü taraf günlük çerçeveleri:

Bazı üçüncü taraf çerçeveler yapılandırılmış günlük olarak da bilinen anlamsal günlük gerçekleştirebilir.

Üçüncü taraf bir çerçeveyi kullanmak, yerleşik sağlayıcılardan birini kullanmaya benzer:

  1. Projenize bir NuGet paketi ekleyin.
  2. Günlük altyapısı tarafından sağlanan bir ILoggerFactory uzantı yöntemi kullanın.

Daha fazla bilgi için her sağlayıcının belgelerine bakın. Üçüncü taraf günlük sağlayıcıları Microsoft tarafından desteklenmez.

Zaman uyumsuz günlükçü yöntemleri yok

Günlüğe kaydetme işleminin çok hızlı gerçekleşmesi gerektiğinden zaman uyumsuz kodun performans maliyetine değmez. Günlük veri deposu yavaşsa, doğrudan bu depoya yazmayın. Günlük iletilerini ilk olarak hızlı bir depoya yazmayı, daha sonra da yavaş depoya taşımayı göz önünde bulundurun. Örneğin SQL Server'da günlüğe kaydederken, bu işlemi doğrudan Log yöntemiyle yapmayın çünkü Log yöntemleri zaman uyumsuzdur. Bunun yerine günlük iletilerini zaman uyumlu olarak bir bellek içi kuyruğuna ekleyin ve bir arka plan çalışanının zaman uyumsuz çalışmayı yapıp verileri SQL Server'a göndermek için iletileri kuyruktan çekmesini sağlayın. Daha fazla bilgi için bkz. Yavaş veri depoları için günlüğü ileti kuyruğuna kaydetme rehberi (dotnet/AspNetCore.Docs #11801).

Çalışan uygulamada günlük düzeylerini değiştirme

Günlük API'si uygulama çalışırken günlük düzeylerini değiştirmeye yönelik bir senaryo içermez. Bununla birlikte bazı yapılandırma sağlayıcıları yapılandırmayı yeniden yükleyebilir ve bu işlem günlük yapılandırmasını hemen etkiler. Örneğin Dosya Yapılandırma Sağlayıcısı günlük yapılandırmasını varsayılan olarak yeniden yükler. Uygulama çalışırken kodda yapılandırma değiştirilirse, uygulamanın günlük yapılandırmasını güncelleştirmek için uygulama IConfigurationRoot.Reload çağrısı yapabilir.

ILogger ve ILoggerFactory

ILogger<TCategoryName> ve ILoggerFactory arabirimleri ve uygulamaları .NET Core SDK'sına eklenmiştir. Bunlar aşağıdaki NuGet paketlerinde de sağlanır:

Kodda günlük filtresi kurallarını uygulama

Günlük filtresi kuralları uygulamak için tercih edilen yaklaşım Yapılandırma'nın kullanılmasıdır.

Aşağıdaki örnek, kodda filtre kurallarının nasıl kaydedileceğini gösterir:

using Microsoft.Extensions.Logging.Console;
using Microsoft.Extensions.Logging.Debug;

var builder = WebApplication.CreateBuilder();
builder.Logging.AddFilter("System", LogLevel.Debug);
builder.Logging.AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information);
builder.Logging.AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace);

logging.AddFilter("System", LogLevel.Debug), System kategorisini ve Debug günlük düzeyini belirtir. Filtre tüm sağlayıcılara uygulanır çünkü belirli bir sağlayıcı yapılandırılmamıştır.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) şunları belirtir:

  • Debug günlük sağlayıcısı.
  • Information ve daha yüksek günlük düzeyi.
  • "Microsoft" ile başlayan tüm kategoriler.

SpanId, TraceId, ParentId, Baggage ve Tags ile kapsamı otomatik olarak günlüğe kaydedin.

Günlük kitaplıkları SpanId, TraceId, ParentId,Baggage ve Tags ile örtük olarak bir kapsam nesnesi oluşturur. Bu davranış ActivityTrackingOptions yoluyla yapılandırılır.

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddSimpleConsole(options =>
{
    options.IncludeScopes = true;
});

builder.Logging.Configure(options =>
{
    options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                       | ActivityTrackingOptions.TraceId
                                       | ActivityTrackingOptions.ParentId
                                       | ActivityTrackingOptions.Baggage
                                       | ActivityTrackingOptions.Tags;
});
var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

traceparent http istek üst bilgisi ayarlanırsa, günlük kapsamındaki ParentId gelen traceparent üst bilgisinden W3C parent-id öğesini gösterir ve günlük kapsamındaki SpanId sonraki giden adım/yayılma için güncelleştirilmiş parent-id öğesini gösterir. Daha fazla bilgi için bkz. traceparent alanını değiştirme.

Özel günlükçü oluşturma

Özel günlükçü oluşturmak için bkz. .NET'te özel günlük sağlayıcısı uygulama.

Ek kaynaklar

Kirk Larkin, Juergen Gutsch ve Rick Anderson

Bu konuda, ASP.NET Core uygulamalarında geçerli olduğu şekilde .NET'te günlük açıklanır. .NET'te günlük hakkında ayrıntılı bilgi için bkz. .NET'te günlük. Blazor uygulamalarında günlük hakkında daha fazla bilgi için bkz. ASP.NET Core Blazor günlüğü.

Örnek kodu görüntüleme veya indirme (indirme).

Günlük sağlayıcıları

Günlükleri görüntüleyen Console sağlayıcısı dışında, günlük sağlayıcıları günlükleri depolar. Örneğin Azure Application Insights sağlayıcısı günlükleri Azure Application Insights'da depolar. Birden fazla sağlayıcı etkinleştirilebilir.

Varsayılan ASP.NET Core web uygulaması şablonları:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Yukarıdaki kod ASP.NET Core web uygulaması şablonlarıyla oluşturulan Program sınıfını gösterir. Sonraki birkaç bölümde, Genel Konak kullanan ASP.NET Core web uygulaması şablonlarını temel alan örnekler sağlanır. Konak olmayan konsol uygulamaları bu belgenin ilerleyen bölümlerinde açıklanır.

Host.CreateDefaultBuilder tarafından eklenen varsayılan günlük sağlayıcıları kümesini geçersiz kılmak için ClearProviders yöntemini çağırın ve gerekli günlük sağlayıcılarını ekleyin. Örneğin aşağıdaki kod:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        })
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Ek sağlayıcılar için bkz:

Günlükleri oluşturma

Günlük oluşturmak için bağımlılık ekleme (DI) tasarım deseninden ILogger<TCategoryName> nesnesini kullanın.

Aşağıdaki örnek:

  • AboutModel türündeki tam adın günlük kategorisini kullanan ILogger<AboutModel> günlükçüsünü oluşturur. Günlük kategorisi, her günlükle ilişkilendirilen bir dizedir.
  • Information düzeyinde günlüğe kaydetmek için LogInformation yöntemini çağırır. Günlük düzeyi günlüğe kaydedilen olayın önem derecesini gösterir.
public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
    public string Message { get; set; }

    public void OnGet()
    {
        Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
        _logger.LogInformation(Message);
    }
}

Düzeyler ve kategoriler bu belgenin devamında daha ayrıntılı olarak açıklanır.

Blazor hakkında bilgi için bkz. ASP.NET Core Blazor günlüğü.

Main ve Startup içinde günlük oluşturma bölümünde Main ve Startup içinde günlüklerin nasıl oluşturulacağı gösterilir.

Günlük kaydetmeyi yapılandırma

Günlük yapılandırması genellikle appsettings.{Environment}.json dosyalarının Logging bölümü tarafından sağlanır. Aşağıdaki appsettings.Development.json dosyası ASP.NET Core web uygulaması şablonları tarafından oluşturulur:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Yukarıdaki JSON kodunda:

  • "Default", "Microsoft" ve "Microsoft.Hosting.Lifetime" kategorileri belirtilir.
  • "Microsoft" kategorisi "Microsoft" ile başlayan tüm kategorilere uygulanır. Örneğin bu ayar "Microsoft.AspNetCore.Routing.EndpointMiddleware" kategorisine uygulanır.
  • "Microsoft" kategorisi Warning veya daha yüksek günlük düzeyinde günlüğe kaydedilir.
  • "Microsoft.Hosting.Lifetime" kategorisi "Microsoft" kategorisinden daha belirgin olduğundan, "Microsoft.Hosting.Lifetime" kategorisi "Information" ve daha yüksek günlük düzeyinde günlüğe kaydeder.
  • Belirli bir günlük sağlayıcısı belirtilmez, dolayısıyla LogLevel Windows EventLog dışında tüm etkinleştirilmiş günlük sağlayıcılarına uygulanır.

Logging özelliğinin LogLevel ve günlük sağlayıcısı özellikleri olabilir. LogLevel, seçili kategorileri günlüğe kaydetmek için en düşük düzeyi belirtir. Önceki JSON'da Information ve Warning günlük düzeyleri belirtilir. LogLevel günlüğün önem derecesini gösterir ve 0 ile 6 arasında değişir:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 ve None = 6.

LogLevel belirtildiğinde, belirtilen ve daha yüksek düzeydeki iletiler için günlük etkinleştirilir. Önceki JSON'da, Default kategori ve üzeri için Information günlüğe kaydedilir. Örneğin Information, Warning, Error ve Critical iletileri günlüğe kaydedilir. LogLevel belirtilmezse günlüğe kaydetme için varsayılan Information düzeyi kullanılır. Daha fazla bilgi için bkz. Günlük düzeyleri.

Sağlayıcı özelliği bir LogLevel özelliği belirtebilir. Sağlayıcının altındaki LogLevel, söz konusu sağlayıcı için günlüğe alınacak düzeyleri belirtir ve sağlayıcı dışı günlük ayarlarını geçersiz kılar. Aşağıdaki appsettings.json dosyasını göz önünde bulundurun:

{
  "Logging": {
    "LogLevel": { // All providers, LogLevel applies to all the enabled providers.
      "Default": "Error", // Default logging, Error and higher.
      "Microsoft": "Warning" // All Microsoft* categories, Warning and higher.
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information", // Overrides preceding LogLevel:Default setting.
        "Microsoft.Hosting": "Trace" // Debug:Microsoft.Hosting category.
      }
    },
    "EventSource": { // EventSource provider
      "LogLevel": {
        "Default": "Warning" // All categories of EventSource provider.
      }
    }
  }
}

Logging.{providername}.LogLevel sınıfındaki ayarlar Logging.LogLevel ayarlarını geçersiz kılar. Yukarıdaki JSON'da sağlayıcının Debug varsayılan günlük düzeyi olarak Informationayarlanır:

Logging:Debug:LogLevel:Default:Information

Yukarıdaki ayar Microsoft.Hosting dışındaki tüm Logging:Debug: kategorileri için Information günlük düzeyini belirtir. Belirli bir kategori listelendiğinde, listelenen kategori varsayılan kategoriyi geçersiz kılar. Yukarıdaki JSON'da,Logging:Debug:LogLevel "Microsoft.Hosting" "Default"Logging:LogLevel

Aşağıdakiler için en düşük günlük düzeyi belirtilebilir:

  • Belirli sağlayıcılar: Örneğin Logging:EventSource:LogLevel:Default:Information
  • Belirli kategoriler: Örneğin Logging:LogLevel:Microsoft:Warning
  • Tüm sağlayıcılar ve tüm kategoriler: Logging:LogLevel:Default:Warning

En düşük düzeyin altındaki günlükler:

  • Sağlayıcıya geçirilmez.
  • Günlüğe kaydedilmez veya görüntülenmez.

Tüm günlükleri engellemek için LogLevel.None değerini belirtin. LogLevel.None değeri 6'dır ve bu değer LogLevel.Critical (5) değerinden yüksektir.

Sağlayıcı günlük kapsamlarını destekliyorsa IncludeScopes bunların etkinleştirilip etkinleştirilmediğini gösterir. Daha fazla bilgi için bkz. Günlük kapsamları

Aşağıdaki appsettings.json dosyası varsayılan olarak etkinleştirilen tüm sağlayıcıları içerir:

{
  "Logging": {
    "LogLevel": { // No provider, LogLevel applies to all the enabled providers.
      "Default": "Error",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Warning"
    },
    "Debug": { // Debug provider.
      "LogLevel": {
        "Default": "Information" // Overrides preceding LogLevel:Default setting.
      }
    },
    "Console": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "EventSource": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "EventLog": {
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "AzureAppServicesFile": {
      "IncludeScopes": true,
      "LogLevel": {
        "Default": "Warning"
      }
    },
    "AzureAppServicesBlob": {
      "IncludeScopes": true,
      "LogLevel": {
        "Microsoft": "Information"
      }
    },
    "ApplicationInsights": {
      "LogLevel": {
        "Default": "Information"
      }
    }
  }
}

Yukarıdaki örnekte:

  • Kategoriler ve düzeyler önerilen değerler değildir. Örnek, tüm varsayılan sağlayıcıları göstermek amacıyla sağlanmıştır.
  • Logging.{providername}.LogLevel sınıfındaki ayarlar Logging.LogLevel ayarlarını geçersiz kılar. Örneğin Debug.LogLevel.Default düzeyi LogLevel.Default düzeyini geçersiz kılar.
  • Her varsayılan sağlayıcı diğer adı kullanılır. Her sağlayıcı, yapılandırmada tam tür adı yerine kullanılacak bir diğer ad tanımlar. Yerleşik sağlayıcı diğer adları şunlardır:
    • Konsol
    • Hata Ayıklama
    • EventSource
    • EventLog
    • AzureAppServicesFile
    • AzureAppServicesBlob
    • ApplicationInsights

Komut satırı, ortam değişkenleri ve başka bir yapılandırmayla günlük düzeyini ayarlama

Günlük düzeyi yapılandırma sağlayıcılarının herhangi biri tarafından ayarlanabilir.

: ayıracı, tüm platformlarda ortam değişkeni hiyerarşik anahtarlarıyla çalışmaz. Örneğin, : ayırıcı Bash tarafından desteklenmez. Çift alt çizgi olan , __şöyledir:

  • Tüm platformlar tarafından desteklenir.
  • otomatik olarak iki nokta üst üste ile :değiştirilir.

Aşağıdaki komutlar:

  • Windows'da Logging:LogLevel:Microsoft ortam anahtarını Information değerine ayarlar.
  • ASP.NET Core web uygulaması şablonlarıyla oluşturulan bir uygulamayı kullanırken ayarları test edin. set kullanıldıktan sonra proje dizininde dotnet run komutu çalıştırılmalıdır.
set Logging__LogLevel__Microsoft=Information
dotnet run

Önceki ortam ayarı:

  • Yalnızca ayarlandığı komut penceresinden başlatılan işlemlerde ayarlanır.
  • Visual Studio ile başlatılan tarayıcılar tarafından okunmaz.

Aşağıdaki setx komutu Windows'da ortam anahtarını ve değerini de ayarlar. set öğesinin aksine setx ayarları kalıcıdır. /M anahtarı, değişkeni sistem ortamında ayarlar. /M kullanılmazsa bir kullanıcı ortamı değişkeni ayarlanır.

setx Logging__LogLevel__Microsoft Information /M

Aşağıdaki appsettings.json dosyasını göz önünde bulundurun:

"Logging": {
    "Console": {
      "LogLevel": {
        "Microsoft.Hosting.Lifetime": "Trace"
      }
    }
}

Aşağıdaki komut ortamda önceki yapılandırmayı ayarlar:

setx Logging__Console__LogLevel__Microsoft.Hosting.Lifetime Trace /M

Azure App Service üzerinde Ayarlar >Yapılandırması sayfasında Yeni uygulama ayarını seçin. Azure App Service uygulama ayarları şunlardır:

  • Şifrelenmiş bir kanalda rest şifrelenir ve bu kanal üzerinden iletilir.
  • Ortam değişkenleri olarak kullanıma sunulur.

Daha fazla bilgi için, bkz. Azure Apps: Azure Portal'ı kullanarak uygulama yapılandırmasını geçersiz kılma.

Ortam değişkenlerini kullanarak ASP.NET Core yapılandırma değerlerini ayarlama hakkında daha fazla bilgi için bkz. Ortam değişkenleri. Komut satırı, Azure Key Vault, Azure Uygulama Yapılandırması ve diğer dosya biçimleri de dahil olmak üzere diğer yapılandırma kaynaklarını kullanma hakkında bilgi için bkz. ASP.NET Core'da yapılandırma.

Filtreleme kuralları nasıl uygulanır?

Bir ILogger<TCategoryName> nesnesi oluşturulduğunda ILoggerFactory nesnesi bu günlükçüye uygulamak üzere sağlayıcı başına tek bir kural seçer. ILogger örneği tarafından yazılan tüm iletiler seçilen kurallar temelinde filtrelenir. Kullanılabilir kurallar arasından her sağlayıcı ve kategori çifti için en belirgin kural seçilir.

Belirli bir kategori için ILogger oluşturulduğunda her sağlayıcı için aşağıdaki algoritma kullanılır:

  • Sağlayıcıyla veya sağlayıcının diğer adıyla eşleşen tüm kuralları seçin. Eşleşme bulunamazsa sağlayıcısı boş olan tüm kurallar seçilir.
  • Önceki adımın sonucundan, eşleşen kategori ön eki en uzun olan kuralları seçin. Eşleşme bulunamazsa bir kategori belirtmeyen tüm kuralları seçin.
  • Birden çok kural seçildiyse, sonuncusunu alın.
  • Hiçbir kural seçilmezse MinimumLevel kullanın.

Dotnet çalıştırması ve Visual Studio'dan gelen çıkışı günlüğe kaydetme

Varsayılan günlük sağlayıcılarıyla oluşturulan günlükler görüntülenir:

  • Visual Studio'da
    • Hata ayıklama sırasında Hata Ayıklama çıkışı penceresinde.
    • ASP.NET Core Web Sunucusu penceresinde.
  • Uygulama dotnet run ile çalıştırıldığında konsol penceresinde.

"Microsoft" kategorileriyle başlayan günlükler ASP.NET Core çerçevesi kodundan gelir. ASP.NET Core ve uygulama kodu aynı günlük API'sini ve sağlayıcılarını kullanır.

Günlük kategorisi

ILogger nesnesi oluşturulduğunda bir kategori belirtilir. Söz konusu kategori bu ILogger örneğiyle oluşturulan her günlük iletisine eklenir. Kategori dizesi rastgeledir ama kural, sınıf adının kullanılmasıdır. Örneğin bir denetleyicide "TodoApi.Controllers.TodoController" adı kullanılabilir. ASP.NET Core web uygulamaları, kategori olarak T tam tür adını kullanan bir ILogger örneğini otomatik olarak almak için ILogger<T> kullanır:

public class PrivacyModel : PageModel
{
    private readonly ILogger<PrivacyModel> _logger;

    public PrivacyModel(ILogger<PrivacyModel> logger)
    {
        _logger = logger;
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.PrivacyModel called.");
    }
}

Kategoriyi açıkça belirtmek için ILoggerFactory.CreateLogger yöntemini çağırın:

public class ContactModel : PageModel
{
    private readonly ILogger _logger;

    public ContactModel(ILoggerFactory logger)
    {
        _logger = logger.CreateLogger("TodoApi.Pages.ContactModel.MyCategory");
    }

    public void OnGet()
    {
        _logger.LogInformation("GET Pages.ContactModel called.");
    }

Birden çok yöntemde kullanıldığında CreateLogger yöntemini sabit bir adla çağırmak yararlı olabilir çünkü olaylar kategoriye göre düzenlenebilir.

ILogger<T>, T tam tür adıyla CreateLogger yöntemini çağırmanın eşdeğeridir.

Günlük düzeyi

Aşağıdaki tabloda LogLevel değerleri, uygun Log{LogLevel} uzantısı yöntemi ve önerilen kullanım listelenir:

GünlükDüzeyi Değer Metot Açıklama
İzleme 0 LogTrace En ayrıntılı iletileri içerir. Bu iletiler hassas uygulama verileri içerebilir. Bu iletiler varsayılan olarak devre dışı bırakılmıştır ve üretimde etkinleştirilmemesi gerekir.
Hata Ayıklama 1 LogDebug Hata ayıklama ve geliştirme için. Yüksek hacim nedeniyle üretimde dikkatli kullanın.
Bilgi 2 LogInformation Uygulamanın genel akışını izler. Uzun süreli bir değeri olabilir.
Uyarı 3 LogWarning Anormal veya beklenmeyen olaylar için. Normalde uygulamanın başarısız olmasına neden olmayan hataları veya koşulları içerir.
Hata 4 LogError İşlenemeyen hatalar ve özel durumlar için. Bu iletiler uygulama genelindeki bir hatayı değil geçerli işlem veya istekteki hatayı gösterir.
Kritik 5 LogCritical Hemen ilgilenilmesi gereken hatalar için. Örnekler: veri kaybı senaryoları, yetersiz disk alanı.
Hiçbiri 6 Bir günlük kategorisinin hiçbir ileti yazmayacağını belirtir.

Yukarıdaki tabloda LogLevel en düşük önem derecesinden en yükseğe doğru listelenmiştir.

Log yönteminin ilk parametresi olan LogLevel günlüğün önem derecesini gösterir. Geliştiricilerin çoğu Log(LogLevel, ...) yöntemini çağırmak yerine Log{LogLevel} uzantı yöntemlerini çağırır. Log{LogLevel} uzantı yöntemleri Log yöntemini çağırır ve LogLevel ayarını belirtir. Örneğin aşağıdaki iki günlük çağrısı işlevsel açıdan eşdeğerdir ve aynı günlüğü oluşturur:

[HttpGet]
public IActionResult Test1(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);

    _logger.Log(LogLevel.Information, MyLogEvents.TestItem, routeInfo);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    return ControllerContext.MyDisplayRouteInfo();
}

MyLogEvents.TestItem olay kimliğidir. MyLogEvents örnek uygulamanın bir parçasıdır ve Günlük olayı kimliği bölümünde görüntülenir.

MyDisplayRouteInfo ve ToCtxString, Rick.Docs.Samples.RouteInfo NuGet paketi tarafından sağlanır. Yöntemler Controller ve Razor Page yönlendirme bilgilerini görüntüler.

Aşağıdaki kod Information ve Warning günlüklerini oluşturur:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Yukarıdaki kodda ilk Log{LogLevel} parametresi olan MyLogEvents.GetItem Günlük olayı kimliğidir. İkinci parametre, kalan yöntem parametreleri tarafından sağlanan bağımsız değişken değerleri için yer tutucular içeren bir ileti şablonudur. Yöntem parametreleri bu belgenin devamındaki ileti şablonu bölümünde açıklanır.

Belirli bir depolama ortamına ne kadar günlük çıkışı yazılacağını denetlemek için uygun Log{LogLevel} yöntemini çağırın. Örneğin:

  • Üretimde:
    • Trace veya Information düzeylerinde günlüğe kaydetme, yüksek hacimli ve ayrıntılı günlük iletileri oluşturur. Maliyetleri denetlemek ve veri depolama sınırlarını aşmamak için Trace ve Information düzeyindeki iletileri yüksek hacimli ve düşük maliyetli bir veri deposunda günlüğe kaydedin. Trace ve Information düzeylerini belirli kategorilerle sınırlamayı göz önünde bulundurun.
    • Warning ile Critical düzeyleri arasını günlüğe kaydetmek az sayıda günlük iletisi oluşturmalıdır.
      • Maliyetler ve depolama sınırları genellikle sorun değildir.
      • Az sayıda günlük veri deposu seçimlerine daha fazla esneklik getirir.
  • Geliştirme aşamasında:
    • Warning olarak ayarlayın.
    • Sorun giderme sırasında Trace veya Information iletilerini ekleyin. Çıkışı sınırlamak için Trace veya Information düzeyini yalnızca araştırma kapsamındaki kategoriler için ayarlayın.

ASP.NET Core çerçeve olayları için günlük yazar. Örneğin aşağıdakiler için günlük çıkışını düşünün:

  • ASP.NET Core şablonlarıyla oluşturulan Razor Pages uygulaması.
  • Logging:Console:LogLevel:Microsoft:Information olarak ayarlanmış günlük
  • Privacy sayfasına gezinti:
info: Microsoft.AspNetCore.Hosting.Diagnostics[1]
      Request starting HTTP/2 GET https://localhost:5001/Privacy
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[0]
      Executing endpoint '/Privacy'
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[3]
      Route matched with {page = "/Privacy"}. Executing page /Privacy
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[101]
      Executing handler method DefaultRP.Pages.PrivacyModel.OnGet - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[102]
      Executed handler method OnGet, returned result .
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[103]
      Executing an implicit handler method - ModelState is Valid
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[104]
      Executed an implicit handler method, returned result Microsoft.AspNetCore.Mvc.RazorPages.PageResult.
info: Microsoft.AspNetCore.Mvc.RazorPages.Infrastructure.PageActionInvoker[4]
      Executed page /Privacy in 74.5188ms
info: Microsoft.AspNetCore.Routing.EndpointMiddleware[1]
      Executed endpoint '/Privacy'
info: Microsoft.AspNetCore.Hosting.Diagnostics[2]
      Request finished in 149.3023ms 200 text/html; charset=utf-8

Aşağıdaki JSON kümeleri Logging:Console:LogLevel:Microsoft:Information:

{
  "Logging": {      // Default, all providers.
    "LogLevel": {
      "Microsoft": "Warning"
    },
    "Console": { // Console provider.
      "LogLevel": {
        "Microsoft": "Information"
      }
    }
  }
}

Günlük olayı kimliği

Her günlük bir olay kimliği belirtebilir. Örnek uygulama olay kimliklerini tanımlamak için MyLogEvents sınıfını kullanır:

public class MyLogEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems     = 1001;
    public const int GetItem       = 1002;
    public const int InsertItem    = 1003;
    public const int UpdateItem    = 1004;
    public const int DeleteItem    = 1005;

    public const int TestItem      = 3000;

    public const int GetItemNotFound    = 4000;
    public const int UpdateItemNotFound = 4001;
}

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Olay kimliği bir dizi olayı ilişkilendirir. Örneğin sayfadaki öğelerin listesini görüntülemeyle ilgili tüm günlükler 1001 olabilir.

Günlük sağlayıcısı olay kimliğini bir kimlik alanında veya günlüğe kaydetme iletisinde depolayabilir ya da hiç depolamaz. Hata ayıklama sağlayıcıları olay kimliklerini göstermez. Konsol sağlayıcısı olay kimliklerini kategorinin arkasında köşeli ayraç içinde gösterir:

info: TodoApi.Controllers.TodoItemsController[1002]
      Getting item 1
warn: TodoApi.Controllers.TodoItemsController[4000]
      Get(1) NOT FOUND

Bazı günlük sağlayıcıları olay kimliğini bir alanda depolar ve bu sayede kimliğe göre filtre uygulanabilir.

Günlük iletisi şablonu

Her günlük API'si bir ileti şablonu kullanır. İleti şablonu bağımsız değişkenlerin sağlandığı yer tutucular içerebilir. Yer tutucular için sayı değil ad kullanın.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

    var todoItem = await _context.TodoItems.FindAsync(id);

    if (todoItem == null)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, "Get({Id}) NOT FOUND", id);
        return NotFound();
    }

    return ItemToDTO(todoItem);
}

Günlük iletilerinde yer tutucu değerlerini sağlamak için hangi parametrelerin kullanılacağını yer tutucu adları değil parametrelerin sırası belirler. Aşağıdaki kodda, ileti şablonunun yer tutucularında parametre adları sıralı değildir:

var apples = 1;
var pears = 2;
var bananas = 3;

_logger.LogInformation("Parameters: {pears}, {bananas}, {apples}", apples, pears, bananas);

Bununla birlikte parametreler yer tutuculara sırayla atanır: apples, pears, bananas. Günlük iletisi parametrelerin sırasını yansıtır:

Parameters: 1, 2, 3

Bu yaklaşım günlük sağlayıcılarının anlamsal veya yapılandırılmış günlük uygulamalarına olanak tanır. Bağımsız değişkenlerin kendileri yalnızca biçimlendirilmiş ileti şablonuna değil günlük sistemine geçirilir. Bu sayede günlük sağlayıcıları parametre değerlerini alanlar olarak depolayabilir. Örneğin, aşağıdaki günlükçü yöntemini ele alalım:

_logger.LogInformation("Getting item {Id} at {RequestTime}", id, DateTime.Now);

Örneğin Azure Tablo Depolama'da oturum açarken:

  • Her Azure Tablo varlığının ID ve RequestTime özellikleri olabilir.
  • Özellikleri olan tablolar, günlüğe kaydedilmiş veriler üzerinde çalıştırılan sorguları basitleştirir. Örneğin bir sorgu, metin iletisinden zamanı ayıklamak zorunda kalmadan belirli bir RequestTime aralığındaki tüm günlükleri bulabilir.

Günlük özel durumları

Günlükçü yöntemlerinde özel durum parametresi alan aşırı yüklemeler vardır:

[HttpGet("{id}")]
public IActionResult TestExp(int id)
{
    var routeInfo = ControllerContext.ToCtxString(id);
    _logger.LogInformation(MyLogEvents.TestItem, routeInfo);

    try
    {
        if (id == 3)
        {
            throw new Exception("Test exception");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(MyLogEvents.GetItemNotFound, ex, "TestExp({Id})", id);
        return NotFound();
    }

    return ControllerContext.MyDisplayRouteInfo();
}

MyDisplayRouteInfo ve ToCtxString, Rick.Docs.Samples.RouteInfo NuGet paketi tarafından sağlanır. Yöntemler Controller ve Razor Page yönlendirme bilgilerini görüntüler.

Özel durum günlüğü sağlayıcıya özgüdür.

Varsayılan günlük düzeyi

Varsayılan günlük düzeyi ayarlanmazsa, varsayılan günlük değeri Information olur.

Örneğin aşağıdaki web uygulamasını ele alalım:

  • ASP.NET web uygulaması şablonlarıyla oluşturulmuştur.
  • appsettings.json ve appsettings.Development.json silinmiş veya yeniden adlandırılmıştır.

Önceki kurulumda, veya sayfasına gitmekprivacy, kategori adında ile Microsoft birçok Trace, Debugve Information iletisi oluşturur.home

Varsayılan günlük düzeyi yapılandırmada ayarlanmadığında, aşağıdaki kod varsayılan günlük düzeyini ayarlar:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Genel olarak günlük düzeyleri kodda değil yapılandırmada belirtilmelidir.

Filter işlevi

Yapılandırma veya kod tarafından kendilerine atanmış kuralları olmayan tüm sağlayıcılar ve kategoriler için filtre işlevi çağrılır:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddFilter((provider, category, logLevel) =>
                {
                    if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Controller")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else if (provider.Contains("ConsoleLoggerProvider")
                        && category.Contains("Microsoft")
                        && logLevel >= LogLevel.Information)
                    {
                        return true;
                    }
                    else
                    {
                        return false;
                    }
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Yukarıdaki kod, kategori Controller veya Microsoft içerdiğinde ve günlük düzeyi Information veya daha yüksek olduğunda konsol günlüklerini görüntüler.

Genel olarak günlük düzeyleri kodda değil yapılandırmada belirtilmelidir.

ASP.NET Çekirdek ve EF Core kategoriler

Aşağıdaki tabloda ASP.NET Core ve Entity Framework Core tarafından kullanılan bazı kategoriler ve günlükler hakkındaki notlar yer alır:

Kategori Notlar
Microsoft.AspNetCore Genel ASP.NET Core tanılamaları.
Microsoft.AspNetCore.DataProtection Hangi anahtarların değerlendirildiği, bulunduğu ve kullanıldığı.
Microsoft.AspNetCore.HostFiltering İzin verilen konaklar.
Microsoft.AspNetCore.Hosting HTTP isteklerini tamamlamanın ne kadar sürdüğü ve bunların ne zaman başlatıldığı. Hangi barındırma başlangıç derlemelerinin yüklendiği.
Microsoft.AspNetCore.Mvc MVC ve Razor tanılamaları. Model bağlama, filtre yürütme, görünüm derleme, eylem seçimi.
Microsoft.AspNetCore.Routing Yönlendirmeyi eşleştirme bilgileri.
Microsoft.AspNetCore.Server Bağlantı başlatma, durdurma ve etkin tutma yanıtları. HTTPS sertifikası bilgileri.
Microsoft.AspNetCore.StaticFiles Sunulan dosyalar.
Microsoft.EntityFrameworkCore Genel Entity Framework Core tanılamaları. Veritabanı etkinliği ve yapılandırması, değişiklik algılama, geçişler.

Konsol penceresinde daha fazla kategori görüntülemek için appsettings.Development.json dosyasını aşağıdaki gibi ayarlayın:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Trace",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

Günlük kapsamları

Kapsam, bir dizi mantıksal işleci gruplandırabilir. Bu gruplandırma bir kümenin parçası olarak oluşturulan her günlüğe aynı verileri eklemek için kullanılabilir. Örneğin bir işlemi gerçekleştirmenin parçası olarak oluşturulan her günlük işlem kimliğini içerebilir.

Kapsam:

Aşağıdaki sağlayıcılar kapsamları destekler:

Bir kapsamı, günlükçü çağrılarını using bloğunda sarmalayarak kullanın:

[HttpGet("{id}")]
public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
{
    TodoItem todoItem;
    var transactionId = Guid.NewGuid().ToString();
    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(MyLogEvents.GetItem, "Getting item {Id}", id);

        todoItem = await _context.TodoItems.FindAsync(id);

        if (todoItem == null)
        {
            _logger.LogWarning(MyLogEvents.GetItemNotFound, 
                "Get({Id}) NOT FOUND", id);
            return NotFound();
        }
    }

    return ItemToDTO(todoItem);
}

Yerleşik günlük sağlayıcıları

ASP.NET Core, paylaşılan çerçevenin bir parçası olarak aşağıdaki günlük sağlayıcılarını içerir:

Aşağıdaki günlük sağlayıcıları Microsoft tarafından gönderilir ama paylaşılan çerçevenin parçası olarak gönderilmez. Ek nuget olarak yüklenmeleri gerekir.

ASP.NET Core günlükleri dosyalara yazmaya yönelik bir günlük sağlayıcısı içermez. ASP.NET Core uygulamasından günlükleri dosyalara yazmak için üçüncü taraf bir günlük sağlayıcısı kullanmayı göz önünde bulundurun.

stdout ve ASP.NET Core Modülü ile hata ayıklama günlüğü hakkında bilgi için bkz. Azure App Service ve IIS'de ASP.NET Core sorunlarını giderme ve IIS için ASP.NET Core Modülü (ANCM).

Konsol

Console sağlayıcısı günlüklerin çıkışını konsola yönlendirir. Geliştirmedeki Console günlüklerini görüntüleme hakkında daha fazla bilgi için bkz. Dotnet çalıştırması ve Visual Studio'dan gelen çıkışı günlüğe kaydetme.

Hata Ayıklama

Debug sağlayıcısı günlük çıkışını yazarken System.Diagnostics.Debug sınıfını kullanır. System.Diagnostics.Debug.WriteLine çağrıları Debug sağlayıcısına yazar.

Linux'ta Debug sağlayıcısının günlük konumu dağıtıma bağımlıdır ve aşağıdakilerden biri olabilir:

  • /var/log/message
  • /var/log/syslog

Olay Kaynağı

EventSource sağlayıcısı Microsoft-Extensions-Logging adıyla bir platformlar arası olay kaynağına yazar. Windows'da sağlayıcı ETW kullanır.

dotnet trace aracı

dotnet-trace aracı, çalışan işlemin .NET Core izlemelerini toplamaya olanak tanıyan, platformlar arası bir CLI genel aracıdır. Araç bir LoggingEventSource kullanarak Microsoft.Extensions.Logging.EventSource sağlayıcı verilerini toplar.

Yükleme yönergeleri için bkz. dotnet-trace.

Uygulamadan izleme toplamak için dotnet trace aracını kullanın:

  1. Uygulamayı dotnet run komutuyla çalıştırın.

  2. .NET Core uygulamasının işlem tanımlayıcısını (PID) belirleyin:

    dotnet trace ps

    Uygulamanın derlemesiyle aynı adı taşıyan işlemin PID değerini bulun.

  3. dotnet trace komutunu yürütün.

    Genel komut söz dizimi:

    dotnet trace collect -p {PID} 
    --providers Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"

    PowerShell komut kabuğu kullanıldığında --providers değerini tek tırnak içine alın ('):

    dotnet trace collect -p {PID} 
    --providers 'Microsoft-Extensions-Logging:{Keyword}:{Provider Level}
        :FilterSpecs=\"
            {Logger Category 1}:{Category Level 1};
            {Logger Category 2}:{Category Level 2};
            ...
            {Logger Category N}:{Category Level N}\"'

    Windows dışındaki platformlarda çıkış izleme dosyasının biçimini speedscope olarak değiştirmek için -f speedscope seçeneğini ekleyin.

    Aşağıdaki tabloda Anahtar Sözcükler tanımlanır:

    Anahtar sözcük Açıklama
    1 LoggingEventSource hakkındaki meta olaylarını günlüğe kaydeder. ILogger kaynaklı olayları günlüğe kaydetmez.
    2 ILogger.Log() çağrıldığında bile Message olayını açar. Bilgileri programlama yoluyla (biçimlendirilmemiş olarak) sağlar.
    4 ILogger.Log() çağrıldığında bile FormatMessage olayını açar. Bilgilerin biçimlendirilmiş dize sürümünü sağlar.
    8 ILogger.Log() çağrıldığında bile MessageJson olayını açar. Bağımsız değişkenlerin JSON gösterimini sağlar.

    Aşağıdaki tabloda sağlayıcı düzeyleri listelenir:

    Sağlayıcı Düzeyi Açıklama
    0 LogAlways
    1 Critical
    2 Error
    3 Warning
    4 Informational
    5 Verbose

    Kategori düzeyi için ayrıştırma bir dize veya sayı olabilir:

    Kategori adlandırılmış değeri Sayısal değer
    Trace 0
    Debug 1
    Information 2
    Warning 3
    Error 4
    Critical 5

    Sağlayıcı düzeyi ve kategori düzeyi:

    • Ters sıradadır.
    • Dize sabitlerinin tümü aynı değildir.

    Hiçbir FilterSpecs belirtilmezse EventSourceLogger uygulaması sağlayıcı düzeyini bir kategori düzeyine dönüştürmeyi dener ve tüm kategorilere uygular.

    Sağlayıcı Düzeyi Kategori Düzeyi
    Verbose(5) Debug(1)
    Informational(4) Information(2)
    Warning(3) Warning(3)
    Error(2) Error(4)
    Critical(1) Critical(5)

    FilterSpecs sağlanırsa, listeye eklenen her kategori burada kodlanan kategori düzeyini kullanır; diğer tüm kategoriler filtrelenir.

    Aşağıdaki örneklerde şunlar varsayılır:

    • Bir uygulama çalışıyor ve logger.LogDebug("12345") çağrısı yapıyor.
    • İşlem kimliği (PID) set PID=12345 yoluyla ayarlandı ve burada 12345 gerçek PID'yi gösteriyor.

    Aşağıdaki komutu inceleyin:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:5

    Yukarıdaki komut:

    • Hata ayıklama iletilerini yakalar.
    • FilterSpecs uygulamaz.
    • Hata Ayıklama kategorisine eşlenen 5. düzeyi belirtir.

    Aşağıdaki komutu inceleyin:

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:5\"

    Yukarıdaki komut:

    • 5. kategori düzeyi Critical olduğundan hata ayıklama iletilerini yakalamaz.
    • Bir FilterSpecs sağlar.

    1. kategori düzeyi Debug olduğundan aşağıdaki komut hata ayıklama iletilerini yakalar.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:1\"

    Kategori olarak Debug belirtildiğinden aşağıdaki komut hata ayıklama iletilerini yakalar.

    dotnet trace collect -p %PID%  --providers Microsoft-Extensions-Logging:4:5:\"FilterSpecs=*:Debug\"

    {Logger Category} ve {Category Level} için FilterSpecs girdileri, ek günlük filtreleme koşullarını temsil eder. FilterSpecs girdilerini ; noktalı virgül karakteriyle ayırın.

    Windows komut kabuğunun kullanıldığı örnek:

    dotnet trace collect -p %PID% --providers Microsoft-Extensions-Logging:4:2:FilterSpecs=\"Microsoft.AspNetCore.Hosting*:4\"

    Yukarıdaki komut:

    • Hatalar (2) için biçimlendirilmiş dizeler (4) oluşturmak üzere Olay Kaynağı günlükçüsünü etkinleştirir.
    • Informational günlük düzeyinde (4) Microsoft.AspNetCore.Hosting günlüğünü etkinleştirir.

  4. Enter tuşuna veya Ctrl+C tuşlarına basarak dotnet trace aracını durdurun.

    İzleme, dotnet trace komutunun yürütüldüğü klasörde trace.nettrace adıyla kaydedilir.

  5. İzlemeyi Perfview ile açın. trace.nettrace dosyasını açın ve izleme olaylarını inceleyin.

Uygulama CreateDefaultBuilder ile konağı oluşturmuyorsa, Olay Kaynağı sağlayıcısını uygulamanın günlük yapılandırmasına ekleyin.

Daha fazla bilgi için bkz.

Perfview

Günlükleri toplamak ve görüntülemek için PerfView yardımcı programını kullanın. ETW günlüklerini görüntülemeye yönelik başka araçlar vardır ama PerfView, ASP.NET Core tarafından yayılan ETW olaylarıyla çalışmak için en iyi deneyimi sağlar.

PerfView'u bu sağlayıcı tarafından günlüğe kaydedilen olayları toplayacak şekilde yapılandırmak için Ek Sağlayıcılar listesine *Microsoft-Extensions-Logging dizesini ekleyin. Dizenin başındaki * işaretini unutmayın.

Windows EventLog

EventLog sağlayıcısı günlük çıkışını Windows Olay Günlüğü'ne gönderir. Diğer sağlayıcılardan farklı olarak, EventLog sağlayıcısı varsayılan sağlayıcı dışı ayarları devralmaz. EventLog günlük ayarları belirtilmezse, varsayılan olarak LogLevel.Warning kullanılır.

LogLevel.Warning düzeyinden daha düşük düzeyli olayları günlüğe kaydetmek için günlük düzeyini açıkça ayarlayın. Aşağıdaki örnek Olay Günlüğü varsayılan günlük düzeyini LogLevel.Information olarak ayarlar:

"Logging": {
  "EventLog": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

AddEventLog aşırı yüklemeleri EventLogSettings içinde geçirilebilir. null belirtilirse veya hiç belirtilmezse aşağıdaki varsayılan ayarlar kullanılır:

  • LogName: "Uygulama"
  • SourceName: ".NET Çalışma Zamanı"
  • MachineName: Yerel makine adı kullanılır.

Aşağıdaki kod varsayılan değeri ".NET Runtime" olan SourceName ayarını MyLogs olarak değiştirir:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
            {
                logging.AddEventLog(eventLogSettings =>
                {
                    eventLogSettings.SourceName = "MyLogs"; 
                });
            })
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

Azure App Service

Microsoft.Extensions.Logging.AzureAppServices sağlayıcı paketi günlükleri Azure App Service uygulamasının dosya sistemindeki metin dosyalarına ve bir Azure Depolama hesabındaki blob depolamasına yazar.

Sağlayıcı paketi paylaşılan çerçeveye dahil değildir. Sağlayıcıyı kullanmak için sağlayıcı paketini projeye ekleyin.

Sağlayıcı ayarlarını yapılandırmak için, aşağıdaki örnekte gösterildiği gibi AzureFileLoggerOptions ve AzureBlobLoggerOptions kullanın:

public class Scopes
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateHostBuilder(args).Build().Run();
        }

        public static IHostBuilder CreateHostBuilder(string[] args) =>
            Host.CreateDefaultBuilder(args)
                .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
                .ConfigureServices(serviceCollection => serviceCollection
                    .Configure<AzureFileLoggerOptions>(options =>
                    {
                        options.FileName = "azure-diagnostics-";
                        options.FileSizeLimit = 50 * 1024;
                        options.RetainedFileCountLimit = 5;
                    })
                    .Configure<AzureBlobLoggerOptions>(options =>
                    {
                        options.BlobName = "log.txt";
                    }))
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
    }
}

Azure App Service'e dağıtıldığında, uygulama bu ayarları Azure portaldaki App Service sayfasının App Service günlükleri bölümünde kullanır. Aşağıdaki ayarlar güncelleştirildiğinde, uygulamanın yeniden başlatılması veya yeniden dağıtılması gerekmeden değişiklikler hemen geçerlilik kazanır.

  • Application Logging (Dosya Sistemi)
  • Application Logging (Blob)

Günlük dosyalarının varsayılan konumu D:\\homeLogFiles\Application klasöründedir ve varsayılan dosya adı diagnostics-yyyymmdd.txt. Varsayılan dosya boyutu sınırı 10 MB'tır ve varsayılan saklanan dosya sayısı üst sınırı 2'dir. Varsayılan blob adı {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt olur.

Bu sağlayıcı yalnızca proje Azure ortamında çalıştırıldığında günlüğe kaydeder.

Azure günlük akışı

Azure günlük akışı, günlük etkinliğini şu konumlardan gerçek zamanlı olarak görüntülemeyi destekler:

  • Uygulama sunucusu
  • Web sunucusu
  • Başarısız istek izlemesi

Azure günlük akışını yapılandırmak için:

  • Uygulamanın portal sayfasından App Service günlükleri sayfasına gidin.
  • Application Logging (Dosya Sistemi) seçeneğini Açık olarak ayarlayın.
  • Günlük Düzeyini seçin. Bu ayar yalnızca Azure günlük akışı için geçerlidir.

Günlükleri görüntülemek için Günlük Akışı sayfasına gidin. Günlüğe kaydedilen iletiler ILogger arabirimiyle günlüğe kaydedilir.

Azure Application Insights

Microsoft.Extensions.Logging.ApplicationInsights sağlayıcı paketi günlükleri Azure Application Insights'a yazar. Application Insights, web uygulamasını izleyen ve telemetri verilerini sorgulamak ve analiz etmek için araçlar sağlayan bir hizmettir. Bu sağlayıcıyı kullanıyorsanız Application Insights araçlarını kullanarak günlüklerinizi sorgulayabilir ve analiz edebilirsiniz.

Günlük sağlayıcısı, ASP.NET Core için tam kullanılabilir telemetri verilerini sağlayan Microsoft.ApplicationInsights.AspNetCore paketinin bağımlılığı olarak eklenir. Bu paketi kullanıyorsanız sağlayıcı paketini yüklemeniz gerekmez.

The Microsoft.ApplicationInsights.Web paketi ASP.NET Core'a değil ASP.NET 4.x'e yöneliktir.

Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

Üçüncü taraf günlük sağlayıcıları

ASP.NET Core ile çalışan üçüncü taraf günlük çerçeveleri:

Bazı üçüncü taraf çerçeveler yapılandırılmış günlük olarak da bilinen anlamsal günlük gerçekleştirebilir.

Üçüncü taraf bir çerçeveyi kullanmak, yerleşik sağlayıcılardan birini kullanmaya benzer:

  1. Projenize bir NuGet paketi ekleyin.
  2. Günlük altyapısı tarafından sağlanan bir ILoggerFactory uzantı yöntemi kullanın.

Daha fazla bilgi için her sağlayıcının belgelerine bakın. Üçüncü taraf günlük sağlayıcıları Microsoft tarafından desteklenmez.

Konak olmayan konsol uygulaması

Web olmayan konsol uygulamasında bir Genel Konak kullanımı örneği için Arka Plan Görevleri örnek uygulamasının Program.cs dosyasına bakın (ASP.NET Core'da barındırılan hizmetlerle arka plan görevleri).

Genel Konak içermeyen uygulamalara yönelik günlük kodu, sağlayıcıların eklenmesi ve günlükçülerin oluşturulması açısından farklıdır.

Günlük sağlayıcıları

Konak olmayan bir konsol uygulamasında LoggerFactory oluştururken sağlayıcının Add{provider name} uzantı yöntemini çağırın:

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Günlükleri oluşturma

Günlükleri oluşturmak için ILogger<TCategoryName> nesnesini kullanın. LoggerFactory kullanarak bir ILogger oluşturun.

Aşağıdaki örnek, LoggingConsoleApp.Program kategorisiyle bir günlükçü oluşturur.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Aşağıdaki örnekte günlükçü Information düzeyiyle günlükler oluşturmak için kullanılır. Günlük düzeyi günlüğe kaydedilen olayın önem derecesini gösterir.

class Program
{
    static void Main(string[] args)
    {
        using var loggerFactory = LoggerFactory.Create(builder =>
        {
            builder
                .AddFilter("Microsoft", LogLevel.Warning)
                .AddFilter("System", LogLevel.Warning)
                .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
                .AddConsole()
                .AddEventLog();
        });
        ILogger logger = loggerFactory.CreateLogger<Program>();
        logger.LogInformation("Example log message");
    }
}

Düzeyler ve kategoriler bu belgede daha ayrıntılı olarak açıklanır.

Konak oluşturma sırasında günlüğe kaydetme

Konak oluşturma sırasında günlüğe kaydetme işlemi doğrudan desteklenmez. Öte yandan ayrı bir günlükçü kullanılabilir. Aşağıdaki örnekte CreateHostBuilder'da günlüğe kaydetmek için Serilog günlükçüsü kullanılır. AddSerilog, Log.Logger içinde belirtilen statik yapılandırmayı kullanır:

using System;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args)
    {
        var builtConfig = new ConfigurationBuilder()
            .AddJsonFile("appsettings.json")
            .AddCommandLine(args)
            .Build();

        Log.Logger = new LoggerConfiguration()
            .WriteTo.Console()
            .WriteTo.File(builtConfig["Logging:FilePath"])
            .CreateLogger();

        try
        {
            return Host.CreateDefaultBuilder(args)
                .ConfigureServices((context, services) =>
                {
                    services.AddRazorPages();
                })
                .ConfigureAppConfiguration((hostingContext, config) =>
                {
                    config.AddConfiguration(builtConfig);
                })
                .ConfigureLogging(logging =>
                {   
                    logging.AddSerilog();
                })
                .ConfigureWebHostDefaults(webBuilder =>
                {
                    webBuilder.UseStartup<Startup>();
                });
        }
        catch (Exception ex)
        {
            Log.Fatal(ex, "Host builder error");

            throw;
        }
        finally
        {
            Log.CloseAndFlush();
        }
    }
}

ILogger'a bağımlı bir hizmet yapılandırma

Günlükçünün Startup içine oluşturucu ekleme işlemi ASP.NET Core'un önceki sürümlerinde çalışır çünkü Web Konağı için ayrı bir DI kapsayıcısı oluşturulur. Genel Konak için neden tek bir kapsayıcı oluşturulduğu konusunda bilgi için hataya neden olan değişiklik duyurusuna bakın.

ILogger<T> bağımlılığı olan bir hizmet yapılandırmak için oluşturucu eklemeyi kullanın veya bir fabrika yöntemi sağlayın. Fabrika yöntemi yaklaşımı ancak başka seçenek olmadığında önerilir. Örneğin DI tarafından sağlanmış bir ILogger<T> örneği gerektiren bir hizmet düşünün:

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddRazorPages();

    services.AddSingleton<IMyService>((container) =>
    {
        var logger = container.GetRequiredService<ILogger<MyService>>();
        return new MyService() { Logger = logger };
    });
}

Yukarıda vurgulanan kod, DI kapsayıcısının ilk kez bir MyService örneği oluşturması gerektiğinde çalıştırılan Func<T,TResult> kodudur. Kayıtlar hizmetlerin herhangi birine bu yolla erişebilirsiniz.

Main'de günlük oluşturma

Aşağıdaki kod, konağı oluşturduktan sonra DI'den bir ILogger örneği alarak Main'de günlükleri yazar:

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

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Host created.");

    host.Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.UseStartup<Startup>();
        });

Startup'ta günlük oluşturma

Aşağıdaki kod, Startup.Configure içine günlükleri yazar:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env,
                      ILogger<Startup> logger)
{
    if (env.IsDevelopment())
    {
        logger.LogInformation("In Development.");
        app.UseDeveloperExceptionPage();
    }
    else
    {
        logger.LogInformation("Not Development.");
        app.UseExceptionHandler("/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
        endpoints.MapRazorPages();
    });
}

Startup.ConfigureServices yönteminde DI kapsayıcısı kurulumu tamamlanmadan önce günlükleri yazmak desteklenmez:

  • Startup oluşturucusuna günlükçü eklemek desteklenmez.
  • Startup.ConfigureServices yöntem imzasına günlükçü eklemek desteklenmez

Bu kısıtlamanın nedeni günlüğün DI'ye ve yapılandırmaya (bu da DI'ye bağlıdır) bağlı olmasıdır. ConfigureServices tamamlanana kadar DI kapsayıcısı ayarlanmaz.

ILogger<T> bağımlılığı olan bir hizmet yapılandırma hakkında bilgi edinmek veya Startup oluşturucusuna günlükçü ekleme işleminin neden önceki sürümlerde çalıştığını öğrenmek için bkz. ILogger'a bağımlı bir hizmet yapılandırma

Zaman uyumsuz günlükçü yöntemleri yok

Günlüğe kaydetme işleminin çok hızlı gerçekleşmesi gerektiğinden zaman uyumsuz kodun performans maliyetine değmez. Günlük veri deposu yavaşsa, doğrudan bu depoya yazmayın. Günlük iletilerini ilk olarak hızlı bir depoya yazmayı, daha sonra da yavaş depoya taşımayı göz önünde bulundurun. Örneğin SQL Server'da günlüğe kaydederken, bu işlemi doğrudan Log yöntemiyle yapmayın çünkü Log yöntemleri zaman uyumsuzdur. Bunun yerine günlük iletilerini zaman uyumlu olarak bir bellek içi kuyruğuna ekleyin ve bir arka plan çalışanının zaman uyumsuz çalışmayı yapıp verileri SQL Server'a göndermek için iletileri kuyruktan çekmesini sağlayın. Daha fazla bilgi için bu GitHub konusuna bakın.

Çalışan uygulamada günlük düzeylerini değiştirme

Günlük API'si uygulama çalışırken günlük düzeylerini değiştirmeye yönelik bir senaryo içermez. Bununla birlikte bazı yapılandırma sağlayıcıları yapılandırmayı yeniden yükleyebilir ve bu işlem günlük yapılandırmasını hemen etkiler. Örneğin Dosya Yapılandırma Sağlayıcısı günlük yapılandırmasını varsayılan olarak yeniden yükler. Uygulama çalışırken kodda yapılandırma değiştirilirse, uygulamanın günlük yapılandırmasını güncelleştirmek için uygulama IConfigurationRoot.Reload çağrısı yapabilir.

ILogger ve ILoggerFactory

ILogger<TCategoryName> ve ILoggerFactory arabirimleri ve uygulamaları .NET Core SDK'sına eklenmiştir. Bunlar aşağıdaki NuGet paketlerinde de sağlanır:

Kodda günlük filtresi kurallarını uygulama

Günlük filtresi kuralları uygulamak için tercih edilen yaklaşım Yapılandırma'nın kullanılmasıdır.

Aşağıdaki örnek, kodda filtre kurallarının nasıl kaydedileceğini gösterir:

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureLogging(logging =>
               logging.AddFilter("System", LogLevel.Debug)
                  .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information)
                  .AddFilter<ConsoleLoggerProvider>("Microsoft", LogLevel.Trace))
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

logging.AddFilter("System", LogLevel.Debug), System kategorisini ve Debug günlük düzeyini belirtir. Filtre tüm sağlayıcılara uygulanır çünkü belirli bir sağlayıcı yapılandırılmamıştır.

AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Information) şunları belirtir:

  • Debug günlük sağlayıcısı.
  • Information ve daha yüksek günlük düzeyi.
  • "Microsoft" ile başlayan tüm kategoriler.

SpanId, TraceId ve ParentId ile kapsamı otomatik olarak günlüğe kaydetme

Günlük kitaplıkları SpanId, TraceId ve ParentId ile örtük olarak bir kapsam nesnesi oluşturur. Bu davranış ActivityTrackingOptions yoluyla yapılandırılır.

  var loggerFactory = LoggerFactory.Create(logging =>
  {
      logging.Configure(options =>
      {
          options.ActivityTrackingOptions = ActivityTrackingOptions.SpanId
                                              | ActivityTrackingOptions.TraceId
                                              | ActivityTrackingOptions.ParentId;
      }).AddSimpleConsole(options =>
      {
          options.IncludeScopes = true;
      });
  });

traceparent http istek üst bilgisi ayarlanırsa, günlük kapsamındaki ParentId gelen traceparent üst bilgisinden W3C parent-id öğesini gösterir ve günlük kapsamındaki SpanId sonraki giden adım/yayılma için güncelleştirilmiş parent-id öğesini gösterir. Daha fazla bilgi için bkz. traceparent alanını değiştirme.

Özel günlükçü oluşturma

Özel günlükçü oluşturmak için bkz. .NET'te özel günlük sağlayıcısı uygulama.

Ek kaynaklar