Logging

A log is read at the worst possible moment: after something has already gone wrong, usually by someone who cannot reproduce it, in a system handling many operations at once. Everything useful about a log line follows from that.

Console.WriteLine produces a string. It has no level, so you cannot filter it. It has no source, so you cannot tell which class wrote it. It has no fields, so you cannot search for one employee's records among a million lines. And it goes to standard output and nowhere else, so it cannot be sent to a log service without changing code.

ILogger<T> fixes each of those. The type parameter becomes the category, so every line carries the class that wrote it. Every line has a level you can filter on, per category, from configuration. And the values in a line stay separate from the sentence around them, which is the part that changes how a log is used.

public sealed class EmployeeService(
    IEmployeeStore store,
    ILogger<EmployeeService> logger)
{
    public async Task<bool> PromoteAsync(int employeeId, string newTitle)
    {
        // Wrong: one interpolated string, no fields, nothing to search on
        // logger.LogInformation($"Promoting employee {employeeId} to {newTitle}");

        // Right: a template plus values the logging system keeps separate
        logger.LogInformation(
            "Promoting employee {EmployeeId} to {JobTitle}", employeeId, newTitle);

        using (logger.BeginScope("Promotion for {EmployeeId}", employeeId))
        {
            Employee? employee = await store.GetAsync(employeeId);
            if (employee is null)
            {
                logger.LogWarning("Employee {EmployeeId} not found", employeeId);
                return false;
            }

            try
            {
                await store.UpdateTitleAsync(employeeId, newTitle);
                return true;
            }
            catch (DbUpdateException ex)
            {
                logger.LogError(ex, "Failed to promote employee {EmployeeId}", employeeId);
                return false;
            }
        }
    }
}

• The commented line and the line below it produce the same sentence on a console. They are not the same log entry. The interpolated version hands the logging system a finished string, and the employee id exists only as characters inside it.
• The template version keeps EmployeeId and JobTitle as named fields. In any log store that understands structure, you can query for one employee's entries, count promotions by title, or alert on a rate — none of which is possible against a sentence without resorting to substring matching.
• Values are matched to placeholders by position, not by name. The first argument fills the first placeholder whatever it is called, so a mismatched order produces a confidently wrong log entry.
• Placeholder names are part of the contract. Keep them stable, because dashboards and alerts are written against them. Renaming EmployeeId to Id later breaks queries silently.
• BeginScope attaches its values to every entry written inside the block, including entries from code further down the call chain. That is how several lines are tied back to one operation without every method taking an identifier for logging purposes.
• The exception goes in as the first argument to LogError, not into the message. That preserves the type, the message and the stack trace as structure. Pasting ex.Message into the template loses the stack trace, which is the part you wanted.
• Not found is a Warning here, and Information would also be defensible — a caller asking about a deleted employee is an ordinary outcome. It is not an Error: nothing failed, and an error-rate alert that counts it will cry wolf.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Warning",
      "Anvi.Employees.Core.Leave": "Debug"
    }
  }
}

• Each key is a category prefix and each value is the minimum level that gets written for it. Categories come from the type parameter on ILogger<T>, which is why they read as namespaces.
• The longest matching prefix wins. A logger in Anvi.Employees.Core.Leave gets Debug; everything else under Anvi gets the Default of Information.
• Turning framework categories down to Warning is the usual first move on a noisy service. Framework components log a great deal at Information, and most of it is not about your application.
• Raising one namespace to Debug in production is a legitimate, temporary diagnostic tool. Set it, capture what you need, and put it back — Debug at volume is expensive and buries the lines you actually watch.
• Because this is configuration, none of it needs a code change or a rebuild. On a running service it can be changed by a deployment of settings alone.

The trade-off worth stating: logging is not free. Every entry costs processing time, network transfer to wherever logs are collected, storage for as long as you retain it, and indexing in whatever queries it. On a busy service, logging is a measurable share of the work.

That cost is the argument for levels rather than for logging less. Write Debug lines generously and leave them off in production, where you can turn one category up for an hour when you need it. Keep Information for the events that describe what the application did, and be strict about what qualifies.

One more thing worth knowing before you go looking for it. A message template with named placeholders is not specific to one log destination. The same code writes to the console locally and to a log service in production, and the fields survive into both, because the provider is configuration rather than a code decision. That is why the effort of writing templates pays off later rather than immediately.