Seq integration rewrite (#2321)

* Initial mods. * Seq host integration info. * Seq integration rewrite complete. * Fixed a link to a method. * Fixed some issues raised by @IEvangelist * Apply suggestions from code review --------- Co-authored-by: David Pine <[email protected]>
dotnet · Dec 19, 2024 · a4be291 · a4be291
1 parent 2f2ec90
commit a4be291
Showing 1 changed file with 102 additions and 46 deletions.
diff --git a/docs/logging/seq-integration.md b/docs/logging/seq-integration.md
@@ -1,109 +1,157 @@
 ---
 title: .NET Aspire Seq integration
 description: Learn how to use the .NET Aspire Seq integration to add OpenTelemetry Protocol (OTLP) exporters that send logs and traces to a Seq Server.
-ms.topic: how-to
 ms.date: 08/12/2024
+uid: logging/seq-integration
 ---
 
 # .NET Aspire Seq integration
 
-In this article, you learn how to use the .NET Aspire Seq integration to add OpenTelemetry Protocol (OTLP) exporters that send logs and traces to a Seq Server. The integration supports persistent logs and traces across application restarts via configuration.
+[!INCLUDE [includes-hosting-and-client](../includes/includes-hosting-and-client.md)]
 
-## Get started
+[Seq](https://datalust.co/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.
 
-To get started with the .NET Aspire Seq integration, install the [📦 Aspire.Seq](https://www.nuget.org/packages/Aspire.Seq) NuGet package in the client-consuming project, i.e., the project for the application that uses the Seq client.
+During development, .NET Aspire runs and connects to the [`datalust/seq` container image](https://hub.docker.com/r/datalust/seq).
+
+## Hosting integration
+
+The Seq hosting integration models the server as the <xref:Aspire.Hosting.ApplicationModel.SeqResource> type. To access this type and the API, add the [📦 Aspire.Hosting.Seq](https://www.nuget.org/packages/Aspire.Hosting.Seq) NuGet package in the [app host](xref:dotnet/aspire/app-host) project.
 
 ### [.NET CLI](#tab/dotnet-cli)
 
 ```dotnetcli
-dotnet add package Aspire.Seq
+dotnet add package Aspire.Hosting.Seq
 ```
 
 ### [PackageReference](#tab/package-reference)
 
 ```xml
-<PackageReference Include="Aspire.Seq"
+<PackageReference Include="Aspire.Hosting.Seq"
                   Version="*" />
 ```
 
 ---
 
 For more information, see [dotnet add package](/dotnet/core/tools/dotnet-add-package) or [Manage package dependencies in .NET applications](/dotnet/core/tools/dependencies).
 
-## Example usage
+### Add a Seq resource
 
-<!-- TODO: <xref:Microsoft.Extensions.Hosting.AspireSeqExtensions.AddSeqEndpoint%2A> -->
-
-In the _:::no-loc text="Program.cs":::_ file of your projects, 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.
+In your app host project, call <xref:Aspire.Hosting.SeqBuilderExtensions.AddSeq*> to add and return a Seq resource builder.
 
 ```csharp
-builder.AddSeqEndpoint("seq");
+var builder = DistributedApplication.CreateBuilder(args);
+
+var seq = builder.AddSeq("seq")
+                 .ExcludeFromManifest()
+                 .WithLifetime(ContainerLifetime.Persistent);
+
+var myService = builder.AddProject<Projects.ExampleProject>()
+                       .WithReference(seq)
+                       .WaitFor(seq);
+
+// After adding all resources, run the app...
 ```
 
-## App host usage
+> [!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](../fundamentals/app-host-overview.md#container-resource-lifetime).
 
-To model the Seq resource in the app host, install the [📦 Aspire.Hosting.Seq](https://www.nuget.org/packages/Aspire.Hosting.Seq) NuGet package in the [app host](xref:dotnet/aspire/app-host) project.
+> [!IMPORTANT]
+> You must accept the [Seq End User Licence Agreement](https://datalust.co/doc/eula-current.pdf) for Seq to start.
 
-### [.NET CLI](#tab/dotnet-cli)
+#### Seq in the .NET Aspire manifest
 
-```dotnetcli
-dotnet add package Aspire.Hosting.Seq
-```
+Seq shouldn't be part of the .NET Aspire [deployment manifest](../deployment/manifest-format.md), hence the chained call to  <xref:Aspire.Hosting.ResourceBuilderExtensions.ExcludeFromManifest*>. It's recommended you set up a secure production Seq server outside of .NET Aspire for your production environment.
 
-### [PackageReference](#tab/package-reference)
+### Persistent logs and traces
 
-```xml
-<PackageReference Include="Aspire.Hosting.Seq"
-                  Version="*" />
+Register Seq with a data directory in your app host project to retain Seq's data and configuration across application restarts:
+
+```csharp
+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
 
-In your app host project, register a Seq database and consume the connection using the following methods:
+To add a data volume to the Seq resource, call the <xref:Aspire.Hosting.SeqBuilderExtensions.WithDataVolume*> method on the Seq resource:
 
 ```csharp
 var builder = DistributedApplication.CreateBuilder(args);
 
 var seq = builder.AddSeq("seq")
-                 .ExcludeFromManifest();
+                 .WithDataVolume()
+                 .ExcludeFromManifest()
+                 .WithLifetime(ContainerLifetime.Persistent);
 
-var myService = builder.AddProject<Projects.MyService>()
-                       .WithReference(seq);
+var myService = builder.AddProject<Projects.ExampleProject>()
+                       .WithReference(seq)
+                       .WaitFor(seq);
 ```
 
-The preceding code registers a Seq server and propagates its configuration.
+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](#add-seq-resource-with-data-bind-mount), see [Docker docs: Volumes](https://docs.docker.com/engine/storage/volumes).
 
-> [!IMPORTANT]
-> You must accept the [Seq End User Licence Agreement](https://datalust.co/doc/eula-current.pdf) for Seq to start):
+### Add Seq resource with data bind mount
 
-In the _:::no-loc text="Program.cs":::_ file of the **MyService** project, configure logging and tracing to Seq using the following code:
+To add a data bind mount to the Seq resource, call the <xref:Aspire.Hosting.SeqBuilderExtensions.WithDataBindMount*> method:
 
 ```csharp
-builder.AddSeqEndpoint("seq");
+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);
+
 ```
 
-### Seq in the .NET Aspire manifest
+[!INCLUDE [data-bind-mount-vs-volumes](../includes/data-bind-mount-vs-volumes.md)]
 
-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.
+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](https://docs.docker.com/engine/storage/bind-mounts).
 
-### Persistent logs and traces
+## Client integration
+
+To get started with the .NET Aspire Seq client integration, install the [📦 Aspire.Seq](https://www.nuget.org/packages/Aspire.Seq) NuGet package in the client-consuming project, that is, the project for the application that uses the Seq client.
+
+### [.NET CLI](#tab/dotnet-cli)
+
+```dotnetcli
+dotnet add package Aspire.Seq
+```
+
+### [PackageReference](#tab/package-reference)
+
+```xml
+<PackageReference Include="Aspire.Seq"
+                  Version="*" />
+```
+
+---
+
+### Add a Seq client
 
-Register Seq with a data directory in your AppHost project to retain Seq's data and configuration across application restarts.
+In the _:::no-loc text="Program.cs":::_ file of your client-consuming project, call the <xref:Microsoft.Extensions.Hosting.AspireSeqExtensions.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.
 
 ```csharp
-var seq = builder.AddSeq("seq", seqDataDirectory: "./seqdata")
-                 .ExcludeFromManifest();
+builder.AddSeqEndpoint(connectionName: "seq");
 ```
 
-The directory specified must already exist.
+> [!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](#add-a-seq-resource).
 
-## Configuration
+### Configuration
 
-The .NET Aspire Seq integration provides options to configure the connection to Seq.
+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
+#### Use configuration providers
 
-The .NET Aspire Seq integration supports <xref:Microsoft.Extensions.Configuration?displayProperty=fullName>. It loads the `SeqSettings` from configuration by using the `Aspire:Seq` key. Example _:::no-loc text="appsettings.json":::_ that configures some of the options:
+The .NET Aspire Seq integration supports <xref:Microsoft.Extensions.Configuration?displayProperty=fullName>. It loads the <xref:Aspire.Seq.SeqSettings> from configuration by using the `Aspire:Seq` key. The following snippet is an example of an _:::no-loc text="appsettings.json":::_ file that configures some of the options:
 
 ```json
 {
@@ -116,9 +164,11 @@ The .NET Aspire Seq integration supports <xref:Microsoft.Extensions.Configuratio
 }
 ```
 
-### Use inline delegates
+For the complete Seq client integration JSON schema, see [Aspire.Seq/ConfigurationSchema.json](https://github.com/dotnet/aspire/blob/v9.0.0/src/Components/Aspire.Microsoft.Data.SqlClient/ConfigurationSchema.json).
 
-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:
+#### 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:
 
 ```csharp
 builder.AddSeqEndpoint("seq", static settings => 
@@ -132,18 +182,24 @@ builder.AddSeqEndpoint("seq", static settings =>
 
 The .NET Aspire Seq integration handles the following:
 
+- Adds the health check when <xref:Aspire.Seq.SeqSettings.DisableHealthChecks?displayProperty=nameWithType> 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.
 
 [!INCLUDE [integration-observability-and-telemetry](../includes/integration-observability-and-telemetry.md)]
 
-### Logging
+#### 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
 
-- [SEQ Query Language](https://docs.datalust.co/docs/the-seq-query-language)
+- [Seq](https://datalust.co/)
+- [Seq Query Language](https://docs.datalust.co/docs/the-seq-query-language)
 - [.NET Aspire integrations](../fundamentals/integrations-overview.md)
 - [.NET Aspire GitHub repo](https://github.com/dotnet/aspire)