Logging

When an application is running, especially in a complex production environment, it’s like a black box. Requests come in, work gets done, and responses go out. But what happens when something goes wrong? How do you trace a specific user’s journey through your system? How do you find the root cause of a slow response?

The answer is logging. Good logging is like turning on the lights inside that black box. It’s the detailed journal that your application keeps, recording every important event, decision, and error, giving you the visibility you need to understand what’s truly happening.

SliceFlow is built with production-readiness in mind, and that means providing a powerful, structured, and centralized logging system right out of the box.

Beyond Plain Text: The Power of Structured Logging

In the past, logs were often just simple lines of text. While better than nothing, they are difficult to search and analyze, especially when you have thousands of them. SliceFlow uses Serilog, a modern logging framework for .NET, to embrace a much more powerful approach: structured logging.

Instead of writing a flat message like "User 123 failed to update profile.", structured logging captures the data as key-value pairs:

{
  "Timestamp": "2023-10-27T10:00:00.123Z",
  "Level": "Warning",
  "MessageTemplate": "User {UserId} failed to update profile",
  "Properties": {
    "UserId": 123,
    "ApplicationName": "Company.Api"
  }
}

This approach transforms your logs from simple text into a rich, queryable dataset. You can now easily search for all logs related to a specific UserId, filter by Level, or analyze events from a particular ApplicationName.

Logging in Your Endpoints: Effortless and Consistent

Because logging is so fundamental, SliceFlow makes it incredibly easy to do right. Every endpoint has a pre-configured Logger property available, ready to use. There’s no setup required; you can start logging immediately.

internal sealed class MyEndpoint : Endpoint<MyRequest>
{
    public override async Task HandleAsync(MyRequest req, CancellationToken ct)
    {
        // Informational log with structured properties
        Logger.LogInformation("Processing request for CustomerId: {CustomerId}", req.CustomerId);

        try
        {
            // ... your business logic ...
        }
        catch (Exception ex)
        {
            // Error log that captures the full exception details
            Logger.LogError(ex, "An unexpected error occurred for CustomerId: {CustomerId}", req.CustomerId);
        }
    }
}

The Central Hub: Configuration in appsettings.json

All aspects of logging in SliceFlow are controlled from your appsettings.json file. This is where you define what to log and where it should go.

A key concept in Serilog is sinks. A sink is simply a destination for your log events. SliceFlow comes pre-configured with two essential sinks:

1. Console: During local development, your logs are written directly to your terminal or console window. This provides immediate, real-time feedback as you write and test your code.
2. GrafanaLoki: For development and production, logs are also sent to Loki, a powerful log aggregation system. This is the centralized “bookshelf” where all your application’s journals are stored.

The Observability Stack: From Log to Insight

This Loki sink is where the logging system truly integrates with SliceFlow’s Docker environment. The docker-compose.yml file doesn’t just run your application; it runs a complete observability stack.

1. Your application, running in a container, generates structured logs.
2. The Serilog GrafanaLoki sink sends these logs to the loki container.
3. The grafana container is pre-configured to use Loki as a data source.

This means you have a professional-grade log analysis tool at your fingertips. By navigating to http://localhost:3001, you can access Grafana, explore your logs, build dashboards, and set up alerts. You can instantly search across all logs from all parts of your system using Loki’s powerful query language (LogQL).

For example, to find all warning-level logs for a specific user, your query could be as simple as:

{app="api"} |= "Warning" |= "UserId=123"

By combining Serilog’s structured logging with a powerful, pre-configured observability stack, SliceFlow takes the guesswork out of application monitoring. You get a solution that is simple to use during development but scales to provide the deep insights you need to run your application reliably in production.