SeqProxy

Enables writing Seq logs by proxying requests through an ASP.NET Controller or Middleware.

See Milestones for release notes.

Why

Avoid exposing the Seq API to the internet.
Leverage Asp Authentication and Authorization to verify and control incoming requests.
Append extra data to log messages during server processing.

NuGet package

https://nuget.org/packages/SeqProxy/

HTTP Format/Protocol

Format: Serilog compact.

Protocol: Seq raw events.

Note that timestamp (@t) is optional when using this project. If it is not supplied the server timestamp will be used.

Extra data

For every log entry written the following information is appended:

The current application name (as Application) defined in code at startup.
The current application version (as ApplicationVersion) defined in code at startup.
The server name (as Server) using Environment.MachineName.
All claims for the current User from ControllerBase.User.Claims.
The user-agent header as UserAgent.
The referer header as Referrer.

SeqProxyId

SeqProxyId is a tick based timestamp to help correlating a front-end error with a Seq log entry.

It is appended to every Seq log entry and returned as a header to HTTP response.

The id is generated using the following:

var startOfYear = new DateTime(utcNow.Year, 1, 1, 0, 0, 0, 0, DateTimeKind.Utc);
var ticks = utcNow.Ticks - startOfYear.Ticks;
var id = ticks.ToString("x");

^{snippet source | anchor}

Which generates a string of the form 8e434f861302. The current year is trimmed to shorten the id and under the assumption that retention policy is not longer than 12 months. There is a small chance of collisions, but given the use-case (error correlation), this should not impact the ability to find the correct error. This string can then be given to a user as a error correlation id.

Then the log entry can be accessed using a Seq filter.

http://seqServer/#/events?filter=SeqProxyId%3D'39f616eeb2e3'

Usage

Enable in Startup

Enable in Startup.ConfigureServices

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvcCore(option => option.EnableEndpointRouting = false);
    services.AddSeqWriter(seqUrl: "http://localhost:5341");
}

^{snippet source | anchor}

There are several optional parameters:

public void ConfigureServices(IServiceCollection services)
{
    services.AddMvcCore();
    services.AddSeqWriter(
        seqUrl: "http://localhost:5341",
        apiKey: "TheApiKey",
        application: "MyAppName",
        appVersion: new(1, 2),
        scrubClaimType: claimType =>
        {
            var lastIndexOf = claimType.LastIndexOf('/');
            if (lastIndexOf == -1)
            {
                return claimType;
            }

            return claimType[(lastIndexOf + 1)..];
        });
}

^{snippet source | anchor}

application defaults to Assembly.GetCallingAssembly().GetName().Name.
applicationVersion defaults to Assembly.GetCallingAssembly().GetName().Version.
scrubClaimType is used to clean up claimtype strings. For example ClaimTypes.Email is http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, but when recording to Seq the value emailaddress is sufficient. Defaults to DefaultClaimTypeScrubber.Scrub to get the string after the last /.

namespace SeqProxy;

/// <summary>
/// Used for scrubbing claims when no other scrubber is defined.
/// </summary>
public static class DefaultClaimTypeScrubber
{
    /// <summary>
    /// Get the string after the last /.
    /// </summary>
    public static CharSpan Scrub(CharSpan claimType)
    {
        Guard.AgainstEmpty(claimType, nameof(claimType));
        var lastIndexOf = claimType.LastIndexOf('/');
        if (lastIndexOf == -1)
        {
            return claimType;
        }

        return claimType[(lastIndexOf + 1)..];
    }
}

^{snippet source | anchor}

Add HTTP handling

There are two approaches to handling the HTTP containing log events. Using a Middleware and using a Controller.

Using a Middleware

Using a Middleware is done by calling SeqWriterConfig.UseSeq in Startup.Configure(IApplicationBuilder builder):

public void Configure(IApplicationBuilder builder)
{
    builder.UseSeq();

^{snippet source | anchor}

Authorization

Authorization in the middleware can bu done by using useAuthorizationService = true in UseSeq.

public void Configure(IApplicationBuilder builder)
{
    builder.UseSeq(useAuthorizationService: true);

^{snippet source | anchor}

This then uses IAuthorizationService to verify the request:

async Task HandleWithAuth(HttpContext context)
{
    var user = context.User;
    var authResult = await authService.AuthorizeAsync(user, null, "SeqLog");

    if (!authResult.Succeeded)
    {
        await context.ChallengeAsync();
        return;
    }

    await writer.Handle(
        user,
        context.Request,
        context.Response,
        context.RequestAborted);
}

^{snippet source | anchor}

Using a Controller

BaseSeqController is an implementation of ControllerBase that provides a HTTP post and some basic routing.

namespace SeqProxy;

/// <summary>
/// An implementation of <see cref="ControllerBase"/> that provides a http post and some basic routing.
/// </summary>
[Route("/api/events/raw")]
[Route("/seq")]
[ApiController]
public abstract class BaseSeqController :
    ControllerBase
{
    SeqWriter writer;

    /// <summary>
    /// Initializes a new instance of <see cref="BaseSeqController"/>
    /// </summary>
    protected BaseSeqController(SeqWriter writer) =>
        this.writer = writer;

    /// <summary>
    /// Handles log events via a HTTP post.
    /// </summary>
    [HttpPost]
    public virtual Task Post() =>
        writer.Handle(User, Request, Response, HttpContext.RequestAborted);
}

^{snippet source | anchor}

Add a new controller that overrides BaseSeqController.

public class SeqController(SeqWriter writer) :
    BaseSeqController(writer);

^{snippet source | anchor}

Authorization/Authentication

Adding authorization and authentication can be done with an AuthorizeAttribute.

[Authorize]
public class SeqController(SeqWriter writer) :
    BaseSeqController(writer)

^{snippet source | anchor}

Method level attributes

Method level Asp attributes can by applied by overriding BaseSeqController.Post.

For example adding an exception filter .

public class SeqController(SeqWriter writer) :
    BaseSeqController(writer)
{
    [CustomExceptionFilter]
    public override Task Post() =>
        base.Post();

^{snippet source | anchor}

Client Side Usage

Using raw JavaScript

Writing to Seq can be done using a HTTP post:

function LogRawJs(text) {
    const postSettings = {
        method: 'POST',
        credentials: 'include',
        body: `{'@mt':'RawJs input: {Text}','Text':'${text}'}`
    };

    return fetch('/api/events/raw', postSettings);
}

^{snippet source | anchor}

Using Structured-Log

structured-log is a structured logging framework for JavaScript, inspired by Serilog.

In combination with structured-log-seq-sink it can be used to write to Seq

To use this approach:

Include the libraries

Install both structured-log npm and structured-log-seq-sink npm. Or include them from jsDelivr:

<script src='https://cdn.jsdelivr.net/npm/structured-log/dist/structured-log.js'>
</script>
<script src='https://cdn.jsdelivr.net/npm/structured-log-seq-sink/dist/structured-log-seq-sink.js'>
</script>

^{snippet source | anchor}

Configure the log

var levelSwitch = new structuredLog.DynamicLevelSwitch('info');
const log = structuredLog.configure()
    .writeTo(new structuredLog.ConsoleSink())
    .minLevel(levelSwitch)
    .writeTo(SeqSink({
        url: `${location.protocol}//${location.host}`,
        compact: true,
        levelSwitch: levelSwitch
    }))
    .create();

^{snippet source | anchor}

Write a log message

function LogStructured(text) {
    log.info('StructuredLog input: {Text}', text);
}

^{snippet source | anchor}

Including data but omitting from the message template

When using structured-log, data not included in the message template will be named with a convention of a+counter. So for example if the following is logged:

log.info('The text: {Text}', text, "OtherData");

Then OtherData would be written to Seq with the property name a1.

To work around this:

Include a filter that replaces a known token name (in this case {@Properties}):

const logWithExtraProps = structuredLog.configure()
    .filter(logEvent => {
        const template = logEvent.messageTemplate;
        template.raw = template.raw.replace('{@Properties}','');
        return true;
    })
    .writeTo(SeqSink({
        url: `${location.protocol}//${location.host}`,
        compact: true,
        levelSwitch: levelSwitch
    }))
    .create();

^{snippet source | anchor}

Include that token name in the message template, and then include an object at the same position in the log parameters:

function LogStructuredWithExtraProps(text) {
    logWithExtraProps.info(
        'StructuredLog input: {Text} {@Properties}',
        text,
        {
            Timezone: new Date().getTimezoneOffset(),
            Language: navigator.language
        });
}

^{snippet source | anchor}

Then a destructured property will be written to Seq.

Icon

Robot designed by Maxim Kulikov from The Noun Project.

SimonCropp/SeqProxy

SeqProxy

Why

NuGet package

HTTP Format/Protocol

Extra data

SeqProxyId

Usage

Enable in Startup

Add HTTP handling

Using a Middleware

Authorization

Using a Controller

Authorization/Authentication

Method level attributes

Client Side Usage

Using raw JavaScript

Using Structured-Log

Include the libraries

Configure the log

Write a log message

Including data but omitting from the message template

Icon