Edit

Share via

.NET Aspire Seq integration

  • Article

Includes: Hosting integration and Client integration

Seq is a self-hosted search and analysis server that handles structured application logs and trace files. It includes a JSON event store and a simple query language that make it easy to use. You can use the .NET Aspire Seq integration to send OpenTelemetry Protocol (OTLP) data to Seq. The integration supports persistent logs and traces across application restarts.

During development, .NET Aspire runs and connects to the datalust/seq container image.

Hosting integration

The Seq hosting integration models the server as the SeqResource type. To access this type and the API, add the 📦 Aspire.Hosting.Seq NuGet package in the app host project.

dotnet add package Aspire.Hosting.Seq

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add a Seq resource

In your app host project, call AddSeq to add and return a Seq resource builder.

var builder = DistributedApplication.CreateBuilder(args);

var seq = builder.AddSeq("seq")
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent)
                 .WithEnvironment("ACCEPT_EULA", "Y");

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(seq)
                       .WaitFor(seq);

// After adding all resources, run the app...

Note

The Seq container may be slow to start, so it's best to use a persistent lifetime to avoid unnecessary restarts. For more information, see Container resource lifetime.

Accept the Seq End User License Agreement (EULA)

You must accept the Seq EULA for Seq to start. To accept the agreement in code, pass the environment variable ACCEPT_EULA to the Seq container, and set its value to Y. The above code passes this variable in the chained call to WithEnvironment.

Seq in the .NET Aspire manifest

Seq shouldn't be part of the .NET Aspire deployment manifest, hence the chained call to ExcludeFromManifest. It's recommended you set up a secure production Seq server outside of .NET Aspire for your production environment.

Persistent logs and traces

Register Seq with a data directory in your app host project to retain Seq's data and configuration across application restarts:

var seq = builder.AddSeq("seq", seqDataDirectory: "./seqdata")
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent);

The directory specified must already exist.

Add a Seq resource with a data volume

To add a data volume to the Seq resource, call the WithDataVolume method on the Seq resource:

var builder = DistributedApplication.CreateBuilder(args);

var seq = builder.AddSeq("seq")
                 .WithDataVolume()
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent);

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(seq)
                       .WaitFor(seq);

The data volume is used to persist the Seq data outside the lifecycle of its container. The data volume is mounted at the /data path in the Seq container and when a name parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see Docker docs: Volumes.

Add Seq resource with data bind mount

To add a data bind mount to the Seq resource, call the WithDataBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

var seq = builder.AddSeq("seq")
                 .WithDataBindMount(source: @"C:\Data")
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent);

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(seq)
                       .WaitFor(seq);

Important

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

Data bind mounts rely on the host machine's filesystem to persist the Seq data across container restarts. The data bind mount is mounted at the C:\Data on Windows (or /Data on Unix) path on the host machine in the Seq container. For more information on data bind mounts, see Docker docs: Bind mounts.

Client integration

To get started with the .NET Aspire Seq client integration, install the 📦 Aspire.Seq NuGet package in the client-consuming project, that is, the project for the application that uses the Seq client.

dotnet add package Aspire.Seq

Add a Seq client

In the Program.cs file of your client-consuming project, call the AddSeqEndpoint extension method to register OpenTelemetry Protocol exporters to send logs and traces to Seq and the .NET Aspire Dashboard. The method takes a connection name parameter.

builder.AddSeqEndpoint(connectionName: "seq");

Tip

The connectionName parameter must match the name used when adding the Seq resource in the app host project. In other words, when you call AddSeq and provide a name of seq that same name should be used when calling AddSeqEndpoint. For more information, see Add a Seq resource.

Configuration

The .NET Aspire Seq integration provides multiple options to configure the connection to Seq based on the requirements and conventions of your project.

Use configuration providers

The .NET Aspire Seq integration supports Microsoft.Extensions.Configuration. It loads the SeqSettings from configuration by using the Aspire:Seq key. The following snippet is an example of an appsettings.json file that configures some of the options:

{
  "Aspire": {
    "Seq": {
      "DisableHealthChecks": true,
      "ServerUrl": "http://localhost:5341"
    }
  }
}

For the complete Seq client integration JSON schema, see Aspire.Seq/ConfigurationSchema.json.

Use inline delegates

Also you can pass the Action<SeqSettings> configureSettings delegate to set up some or all the options inline, for example to disable health checks from code:

builder.AddSeqEndpoint("seq", static settings => 
{
    settings.DisableHealthChecks  = true;
    settings.ServerUrl = "http://localhost:5341"
});

Health checks

By default, .NET Aspire integrations enable health checks for all services. For more information, see .NET Aspire integrations overview.

The .NET Aspire Seq integration handles the following:

  • Adds the health check when SeqSettings.DisableHealthChecks is false, which attempts to connect to the Seq server's /health endpoint.
  • Integrates with the /health HTTP endpoint, which specifies all registered health checks must pass for app to be considered ready to accept traffic.

Observability and telemetry

.NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability. For more information about integration observability and telemetry, see .NET Aspire integrations overview. Depending on the backing service, some integrations may only support some of these features. For example, some integrations support logging and tracing, but not metrics. Telemetry features can also be disabled using the techniques presented in the Configuration section.

Logging

The .NET Aspire Seq integration uses the following log categories:

  • Seq

Tracing and Metrics

The .NET Aspire Seq integration doesn't emit tracing activities and or metrics because it's a telemetry sink, not a telemetry source.

See also