.NET Aspire Seq 集成

项目
12/21/2024

Seq 是一种自承载搜索和分析 server，用于处理结构化应用程序日志和跟踪文件。它包括 JSON 事件存储和简单的查询语言，使它易于使用。可以使用 .NET AspireSeq 集成将 OpenTelemetry 协议（OTLP）数据发送到 Seq。集成支持在应用程序多次重启过程中保持日志和跟踪持久性。

在开发期间，.NET.NET Aspire 运行并连接到 datalust/seq 容器映像。

托管集成

Seq 托管集成将 server 建模为 SeqResource 类型。若要访问此类型和 API，请在应用主机项目中添加 📦Aspire.Hosting.Seq NuGet 包。

.NET 命令行界面
包引用

dotnet add package Aspire.Hosting.Seq

<PackageReference Include="Aspire.Hosting.Seq"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或管理 .NET 应用程序中的包依赖项。

添加 Seq 资源

在应用主机项目中，调用 AddSeq 添加并返回 Seq 资源生成器。

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...

注意

Seq 容器启动速度可能很慢，因此最好使用 持久性 生存期以避免不必要的重启。有关详细信息，请参阅容器资源生存期。

接受 Seq 最终用户许可协议（EULA）

必须接受 Seq EULA 才能启动 Seq。若要在代码中接受协议，请将环境变量 ACCEPT_EULA 传递给 Seq 容器，并将其值设置为 Y。上述代码在链式调用中传递此变量到 WithEnvironment。

Seq 在 .NET Aspire 清单中

Seq 不应是 .NET Aspire部署清单的一部分，因此，进行了对 ExcludeFromManifest的链式调用。建议在 .NET Aspire 外部为生产环境设置一个安全的生产 Seqserver。

持久日志和跟踪

将 Seq 注册到应用主机项目中的数据目录，以便在应用程序重启时保留 Seq的数据和配置：

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

指定的目录必须已存在。

使用数据卷添加 Seq 资源

若要将数据卷添加到 Seq 资源，请在 Seq 资源上调用 WithDataVolume 方法：

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);

数据卷用于在容器的生命周期之外保留 Seq 数据。数据卷装载在 /data 路径的 Seq 容器中，如果未提供 name 参数，则会随机生成名称。有关数据卷的详细信息，以及它们为何优于绑定挂载的详细信息，请参阅 Docker 文档：卷。

使用数据绑定挂载添加 Seq 资源

若要将数据绑定挂载添加到 Seq 资源，请调用 WithDataBindMount 方法。

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 数据。数据绑定挂载在主机上的 Seq 容器中，对应 Windows 系统的 C:\Data 路径（或在 Unix上的 /Data 路径）。有关数据绑定装载的详细信息，请参阅 Docker 文档：绑定装载。

Client 集成

若要开始 .NET AspireSeqclient 集成，请在使用 Seqclient的应用程序的 client项目中安装 📦Aspire和Seq NuGet 包。

.NET 命令行界面
包引用

dotnet add package Aspire.Seq

<PackageReference Include="Aspire.Seq"
                  Version="*" />

添加 Seqclient

在 client使用项目的 Program.cs 文件中，调用 AddSeqEndpoint 扩展方法来注册 OpenTelemetry 协议的导出器，以将日志和跟踪信息发送到Seq 和 .NET Aspire 仪表板。该方法采用连接名称参数。

builder.AddSeqEndpoint(connectionName: "seq");

提示

connectionName 参数必须与在应用主机项目中添加 Seq 资源时使用的名称匹配。换句话说，当调用 AddSeq 时提供了 seq 的名称，该名称应在调用 AddSeqEndpoint时使用。有关详细信息，请参阅添加 Seq 资源。

配置

.NET Aspire Seq 集成提供了多个选项，用于根据项目的要求和约定配置与 Seq 的连接。

使用配置提供程序

.NET Aspire Seq 集成支持 Microsoft.Extensions.Configuration。它使用 SeqSettings 键从配置中加载 Aspire:Seq。以下代码片段是配置某些选项的 appsettings.json 文件的示例：

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

有关完整的 Seqclient 集成 JSON 架构，请参阅 Aspire。Seq/ConfigurationSchema。json。

使用内联委托

您还可以传递 Action<SeqSettings> configureSettings 委托来直接在代码中设置某些或所有选项，例如通过代码禁用运行状况检查：

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

健康检查

默认情况下，.NET.NET Aspire 集成为所有服务启用健康检查。有关详细信息，请参阅 .NET.NET Aspire 集成概述。

.NET Aspire Seq 集成处理以下内容：

在 SeqSettings.DisableHealthChecks 是 false的情况下，添加一个运行状况检查，尝试连接到 Seqserver的 /health 终结点。
与 /health HTTP 端点集成，该端点规定所有注册的健康检查都必须通过，应用才能开始接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Seq 集成使用以下日志类别：

Seq

跟踪和指标

.NET Aspire Seq 集成不会发出跟踪活动和/或指标，因为它是遥测接收器，而不是遥测源。

通过