Communicate.Archeo.ILogger 0.1.0

Logging to Archeo

This library provides the components necessary to log to Archeo using the default ILogger implementation typically used in ASP.NET Core. This document will detail the steps necessary to set up and configure the logger for an application.

Registering the logger

The components needed to gain an ILogger that can log to Archeo consists of two main components: ArcheoLogger and ArcheoLoggerProvider, which implement the ILogger and ILoggerProvider interfaces respectively.

The first step is ensuring that these components have their dependencies registered in the service collection for the application. The library comes with a method with multiple overloads for how to do this. This is typically done in the ConfigureServices of Startup.cs in a ASP.NET Core application:

public void ConfigureServices(IServiceCollection services)
{
    services.AddArcheoLoggerConfig("ApiKey");
}

The simplest of the overloads for AddArcheoLoggerConfig only requires the Archeo API key, and all other settings will be the default settings. This will also register a standard HttpClient for the logger. There are other overloads for more configuration:

public void ConfigureServices(IServiceCollection services)
{
    var archeoConfiguration = new ArcheoConfiguration
    {
        ApiKey = "ApiKey",
        BatchSize = 50,
        MaxSavedSteps = 100
    };
    services.AddArcheoLoggerConfig(archeoConfiguration);
}

public void ConfigureServices(IServiceCollection services)
{
    var archeoConfiguration = new ArcheoConfiguration
    {
        ApiKey = "ApiKey",
        BatchSize = 50,
        MaxSavedSteps = 100
    };
    static void configureClient(HttpClient httpClient)
    {
        httpClient.Timeout = new TimeSpan(0, 0, 30);
    }
    services.AddArcheoLoggerConfig(archeoConfiguration, configureClient);
}

These two overloads provide more configuration options, the first allowing to change the default values specific for the Archeo logging, and the second overload allows you to provide how you want to configure the HttpClient that is used to send requests to Archeo.

Next is to add the ArcheoLoggerProvider to the ILoggerFactory this is typically done through the Configure method in Startup.cs.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env, ILoggerFactory loggerFactory)
    {
        loggerFactory.AddArcheoLoggerProvider(app);
    }

As long as there is a HttpClient and ArcheoConfiguration registered for Dependency Injection, which is most easily done through AddArcheoLoggerConfig as described above, the application can now log to Archeo using ILogger.

Using ArcheoLogger and LogScopes

Once the ArcheoLoggerProvider has been set up correctly as described in the previous section, then it's possible to log to Archeo by injecting an ILogger in the application. In order to ensure that only messages that are intended for Archeo are sent to Archeo, it is required to set up a LogScope:

var logScope = new LogScope
{
    // All these values should be changed according to how Archeo is configured for your use
    TransactionId = Guid.NewGuid().ToString(),
    MessageType = "MessageType",
    Reciever = "Receiver",
    Sender = "Sender",
    TransactionTag = "Tag",
    TransactionType = "Type"
};

Once you have a LogScope you can create a new scope for the logger and begin to log to Archeo:

using(logger.BeginScope(logScope))
{
    logger.LogInformation("Information log");
    logger.LogWarning("Something might be happening");
    logger.LogError("Something went wrong");
}

Note: If logging with the ILogger outside of a LogScope then these messages will not be sent to Archeo. Once you exit a scope, all messages logged will be sent in batches to Archeo. The messages can also be sent early if the amount of messages logged exceed the MaxSavedSteps based on your ArcheoConfiguration.

Configuring for Archeo

If you only provide an ApiKey when registering the Archeo configuration, then all other values will be the default values from the library. The standard class ArcheoConfiguration has the default values set, but it's also possible to create your own IArcheoConfiguration class and provide that.

public class ArcheoConfiguration : IArcheoConfiguration
{
    public string ArcheoEndpoint { get; set; } = "https://api.archeo.no/api/v1.1/Log";

    public string ApiKey { get; set; }

    public int BatchSize { get; set; } = 100;

    public int MaxSavedSteps { get; set; } = 500;

    public LogLevel MinimumLogLevel { get; set; } = LogLevel.Information;

    public ILogLevelMapper LogLevelMapper { get; set; } = new LogLevelMapper();
}

ArcheoEndpoint

This is the endpoint that log requests will be sent to. In most cases this should not require changing.

ApiKey

Your Archeo ApiKey, this is the only part of the configuration that is required to be configured in the application.

BatchSize

When the logger sends the log steps to Archeo, this describes how many should be sent per batch.

MaxSavedSteps

When logging inside a scope, this describes how many steps can be saved within a scope before the logger will start to send the logs to Archeo.

MinimumLogLevel

The logger will ignore any logs with a log level below this value.

LogLevelMapper

Used to configure how a LogLevel should be converted to an Archeo status based on the current Scope. The default implementation assumes that you use the standard statuses of "Ok", "Warning", "Error" and "Success".

LogLevelMapper and ending a scope

Since there is no LogLevel that is suitable for separating a normal log and a final log, which typically would be translated to the Archeo statuses "Ok" and "Success" respectively. The default LogLevelMapper has the possibility to take the state of the LogScope into consideration for this. If a log has the LogLevel Information and the scope's IsFinalStep is set to true then the Archeo status will be "Success" instead of "Ok".

using (logger.BeginScope(logScope))
{
    logger.LogInformation("Ok log");
    logScope.IsFinalStep = true;
    logger.LogInformation("Success log");
}