README.md

Seq HTTP API Client

This library includes:

• C# representations of the entities exposed by the Seq HTTP API
• Helper classes for interacting with the API

It's useful for querying events and working with configuration data - everything you can do using the Seq web UI, you can do programmatically via the API.

If you want to write events to Seq, use one of the logging framework clients, such as Serilog.Sinks.Seq or NLog.Targets.Seq instead.

Getting started

Install from NuGet:

dotnet add package Seq.Api

Create a SeqConnection with your server URL:

var connection = new SeqConnection("http://localhost:5341");

Navigate the "resource groups" exposed as properties of the connnection:

var installedApps = await connection.Apps.ListAsync();

To authenticate, the SeqConnection constructor accepts an apiKey parameter (make sure the API key permits user-level access) or, if you want to log in with personal credentials you can await connection.Users.LoginAsync(username, password).

For a more complete example, see the seq-tail app included in the source.

Creating entities

The Seq API provides a /template resource for each resource group that provides a new instance of the resource with defaults populated. The API client uses this pattern when creating new entities:

var signal = await connection.Signals.TemplateAsync();
signal.Title = "Signal 123";
await connection.Signals.AddAsync(signal);

See the signal-copy app for an example of this pattern in action.

Reading events

Seq internally limits the resources a query is allowed to consume. The query methods on SeqConnection.Events include a status with each result set - a Partial status indicates that further results must be retrieved.

The snippet below demonstrates paging through results to retrieve the complete set.

string lastReadEventId = null;

while(true)
{
  var resultSet = await connection.Events.InSignalAsync(
      filter: "Environment = 'Test'",
      render: true,
      afterId: lastReadEventId);
      
  foreach (var evt in resultSet.Events)
    Console.WriteLine(evt.RenderedMessage);

  if (resultSet.Statistics.Status != ResultSetStatus.Partial)
    break;
    
  lastReadEventId = resultSet.Statistics.LastReadEventId;
}

If the result set is expected to be small, ListAsync() will buffer results and return a complete list:

var resultSet = await connection.Events.ListAsync(
    filter: "Environment = 'Test'",
    render: true,
    count: 1000);
  
foreach (var evt in resultSet)
  Console.WriteLine(evt.RenderedMessage);

All methods that retrieve events require a count. The API client defaults this value to 30 if not specified.

Streaming events

Seq 3.4 provides live streaming of events matching a filter and/or set of signals.

var filter = "@Level = 'Error'";

using (var stream = await connection.Events.StreamAsync<JObject>(filter: filter))
using (stream.Select(jObject => LogEventReader.ReadFromJObject(jObject))
             .Subscribe(evt => Log.Write(evt)))
{
    await stream;
}

The Events.StreamAsync() method returns a hot IObservable<T> over a WebSocket. The observable will keep producing events until either it's disposed, or the server is shut down.

Seq streams the events in compact JSON format, which the Seq API client library can deserialize into JSON.NET JObjects for consumption.

Serilog.Formatting.Compact.Reader provides the LogEventReader class used above to turn these documents back into Serilog LogEvents. Having the events represented in Serilog’s object model means they can be passed back into a logging pipeline, as performed above using Log.Write().

Working with the basic client

The SeqApiClient class implements the low level interactions with the API's entities and links. It's one step up from System.Net.HttpClient - you may be able to use it in cases not supported by the high-level wrapper.

Create a SeqApiClient with your server URL:

var client = new SeqApiClient("http://localhost:5341");

Get the root resource and use it to retrieve one or more of the resource groups:

var root = await client.GetRootAsync();
var events = await client.GetAsync<ResourceGroup>(root, "EventsResources");

(Available resource groups, like Events, Users and so-on, can be seen in the root document's Links collection.)

Use the client to navigate links from entity to entity:

var matched = await client.ListAsync<EventEntity>(
  events,
  "Items",
  new Dictionary<string, object>{{"count", 10}, {"render", true}});

foreach (var match in matched)
  Console.WriteLine(match.RenderedMessage);

Package versioning

This package does not follow the SemVer rule of major version increments for breaking changes. Instead, the package version tracks the Seq version it supports.