Pacem.Extensions.Logging.SqlServer 0.10.13-abel

SqlServer Logging Extensions

⚗️ ==Experimental==

⚠️ Experimental libs are discouraged to use in production.

About

Pacem.Extensions.Logging.SqlServer provides extensions to store your logs into a Sql Server database.

Rows are written by a background consumer, so logging calls never block on the database.

The following paragraphs exemplify the library utilization given common use cases.

How to

Add the relevant logger provider to the logging builder (e.g. ILoggingBuilder).

First, define the target entity.
Exploit DataAnnotation like in attribute-based entity definitions (if you're familiar with EntityFramework Core).

ℹ️ Please notice:

• TableAttribute is recommended to correctly identify the target table.
  Fallback, in case of missing attribute, is dbo.<LogEntityTypeName>.
• ColumnAttribute is mandatory in case of name mismatch between property and column, but optional otherwise.

If you want to ignore a property, decorate it with a NotMappedAttribute.

// Structure of a log row in the [Logging].[Logs] table in the database
[Table("Logs", Schema = "Logging")]
public class MyLogEntity
{
    [DatabaseGenerated(DatabaseGeneratedOption.Identity), Key]
    public int Id { get; set; }

    [Required]
    public required string Source { get; set; }

    [Required]
    public required string Message { get; set; }

    [Column(TypeName = "tinyint")]
    public LogLevel LogLevel { get; set; }

    [Column(TypeName = "datetimeoffset(3)")]
    public DateTimeOffset Timestamp { get; set; }

    public string? ErrorMessage { get; set; }

    public string? ErrorStack { get; set; }

    public string? AllData { get; set; }

    /// <summary>
    /// Some relation to the business logic world "outside", if any.
    /// </summary>
    public Guid? RelationId { get; set; }
}

Then, configure the logger provider:

// Program.cs
builder.Logging.AddPacemSqlServerLogging<MyLogEntity>(
    "sql-server-connectionstring-here",
    // mapper: log line -> log entity
    log =>
    {
        Guid? relationId = default;
        if (log.Data?.TryGetValue("relation", out var relationObj) == true
        && Guid.TryParse(relationObj?.ToString(), out Guid result))
        {
            relationId = result;
        }
        return new MyLogEntity
        {
            Source = log.Name,
            Timestamp = log.Timestamp,
            Message = log.Message,
            ErrorMessage = log.Exception?.Message,
            ErrorStack = log.Exception?.StackTrace,
            LogLevel = log.LogLevel,
            AllData = JsonSerializer.Serialize(log.Data),
            RelationId = relationId
        };
    },
    // accumulate several rows into one INSERT (default: false)
    batch: true,
    // further options
    configure: options =>
    {
        // only persist our own categories
        options.Filter = log => log.Name.StartsWith("Pacem.");
    });

ℹ️ The mapper may also return null to skip an entry, but Filter is the preferred place for that decision: it runs earlier (on the caller's thread, before the row is queued) and keeps the mapper about mapping only.

The log payload

The SqlServerLogPayload handed to the mapper and the filter exposes:

Plans for version next

Multiple entities log.