Condividi tramite

integrazione .NET AspireSeq

  • Articolo

include integrazione dell'hosting e integrazione di Client

Seq è un server di ricerca e analisi self-hosted che gestisce i log e i file di traccia delle applicazioni strutturati. Include un archivio eventi JSON e un linguaggio di query semplice che semplifica l'uso. È possibile usare l'integrazione .NET AspireSeq per inviare dati OTLP (OpenTelemetry Protocol) a Seq. L'integrazione supporta log persistenti e tracce tra i riavvii dell'applicazione.

Durante lo sviluppo, .NET.NET Aspire viene eseguito e si connette all'immagine del contenitore datalust/seq.

Integrazione dell'hosting

L'integrazione di hosting Seq modella il server come tipo SeqResource. Per accedere a questo tipo e all'API, aggiungere il pacchetto NuGet 📦Aspire.Hosting.Seq nel progetto host dell'app .

dotnet add package Aspire.Hosting.Seq

Per altre informazioni, vedere dotnet add package o Gestisci le dipendenze dei pacchetti nelle applicazioni .NET.

Aggiungere una risorsa Seq

Nel progetto host dell'app chiamare AddSeq per aggiungere e restituire un generatore di risorse 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...

Nota

L'avvio del contenitore Seq potrebbe essere lento, pertanto è consigliabile usare una durata permanente per evitare riavvii non necessari. Per ulteriori informazioni, vedere durata delle risorse del contenitore.

Accettare il contratto di licenza con l'utente finale di Seq

Per avviare Seq, è necessario accettare l'EULA . Per accettare il contratto nel codice, passare la variabile di ambiente ACCEPT_EULA al contenitore Seq e impostarne il valore su Y. Il codice precedente passa questa variabile nella chiamata concatenata a WithEnvironment.

Seq nel manifesto .NET Aspire

Seq non dovrebbe far parte del .NET Aspiremanifesto di distribuzione, quindi la chiamata concatenata a ExcludeFromManifest. È consigliabile configurare un server di produzione sicuro Seq all'esterno di .NET Aspire per l'ambiente di produzione.

Log e tracce persistenti

Registrare Seq in una directory dei dati nel progetto host dell'app per mantenere i dati e la configurazione di Seqtra un riavvio e l'altro dell'applicazione.

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

La directory specificata deve esistere già.

Aggiungere una risorsa Seq con un volume di dati

Per aggiungere un volume di dati alla risorsa Seq, chiamare il metodo WithDataVolume nella risorsa Seq:

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

Il volume di dati viene usato per rendere persistenti i dati Seq all'esterno del ciclo di vita del contenitore. Il volume di dati viene montato nel percorso /data nel contenitore Seq e quando non viene specificato un parametro name, il nome viene generato in modo casuale. Per ulteriori informazioni sui volumi di dati e sui motivi per cui sono preferiti rispetto ai bind mounts, vedere la documentazioneDocker: Volumi.

Aggiungi la risorsa Seq con il mount di data bind

Per aggiungere un punto di montaggio per l'associazione dati alla risorsa Seq, chiamare il metodo 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);

Importante

I bind mount di dati hanno funzionalità limitate rispetto ai volumi , che offrono prestazioni, portabilità e sicurezza migliori, rendendoli più adatti per gli ambienti di produzione. Tuttavia, i montaggi di associazione consentono l'accesso diretto e la modifica diretta dei file nel sistema host, ideale per lo sviluppo e il test in cui sono necessarie modifiche in tempo reale.

I montaggi di associazione dati si basano sul file system del computer host per rendere persistenti i dati Seq tra i riavvii del contenitore. Il bind mount dei dati è montato al percorso C:\Data su Windows (o al percorso /Data su Unix) nella macchina host all'interno del contenitore Seq. Per altre informazioni sui montaggi di associazione dati, vedere Docker docs: Bind mounts.

integrazione Client

Per iniziare a utilizzare l'integrazione del client .NET AspireSeq, installare il pacchetto NuGet 📦AspireSeq nel progetto utilizzatore del client, ovvero nel progetto dell'applicazione che utilizza il client Seq.

dotnet add package Aspire.Seq

Aggiungere un client Seq

Nel file Program.cs del progetto che utilizza il client chiamare il metodo di estensione AddSeqEndpoint per registrare gli esportatori di protocolli OpenTelemetry per inviare log e tracce a Seq e al dashboard di .NET Aspire. Il metodo accetta un parametro del nome di connessione.

builder.AddSeqEndpoint(connectionName: "seq");

Suggerimento

Il parametro connectionName deve corrispondere al nome usato quando si aggiunge la risorsa Seq nel progetto host dell'app. In altre parole, quando si chiama AddSeq e si specifica un nome di seq lo stesso nome deve essere usato quando si chiama AddSeqEndpoint. Per altre informazioni, vedere Aggiungere una risorsa Seq.

Configurazione

L'integrazione .NET AspireSeq offre più opzioni per configurare la connessione a Seq in base ai requisiti e alle convenzioni del progetto.

Usare i provider di configurazione

L'integrazione .NET AspireSeq supporta Microsoft.Extensions.Configuration. Carica il SeqSettings dalla configurazione utilizzando la chiave Aspire:Seq. Il frammento di codice seguente è un esempio di un file appsettings.json che configura alcune delle opzioni:

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

Per lo schema completo di integrazione client SeqJSON, vedere Aspire.Seq/ConfigurationSchema.json.

Usare delegati in linea

È anche possibile passare il delegate Action<SeqSettings> configureSettings per configurare alcune o tutte le opzioni direttamente nel codice, ad esempio per disabilitare i controlli dello stato di integrità dal codice.

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

Client verifiche di integrità dell'integrazione

Per impostazione predefinita, le integrazioni client .NET.NET Aspire hanno i controlli di integrità abilitati per tutti i servizi. Analogamente, molte integrazioni di hosting .NET.NET Aspire abilitano anche gli endpoint di controllo dell'integrità. Per altre informazioni, vedere:

L'integrazione .NET AspireSeq gestisce le operazioni seguenti:

  • Aggiunge il controllo di integrità quando SeqSettings.DisableHealthChecks è false, che tenta di connettersi all'endpoint Seq del server /health.
  • Si integra con l'endpoint HTTP /health, che specifica che tutti i controlli di integrità registrati devono essere passati affinché l'app sia considerata pronta per accettare il traffico.

Osservabilità e telemetria

.NET .NET Aspire le integrazioni configurano automaticamente configurazioni di registrazione, traccia e metriche, talvolta note come i pilastri dell'osservabilità. Per altre informazioni sull'osservabilità e la telemetria dell'integrazione, vedere panoramica delle integrazioni .NET.NET Aspire. A seconda del servizio di backup, alcune integrazioni possono supportare solo alcune di queste funzionalità. Ad esempio, alcune integrazioni supportano la registrazione e la traccia, ma non le metriche. Le funzionalità di telemetria possono essere disabilitate anche usando le tecniche presentate nella sezione Configurazione .

Registrazione

L'integrazione .NET AspireSeq usa le categorie di log seguenti:

  • Seq

Traccia e metriche

L'integrazione .NET AspireSeq non genera attività di tracciamento né metriche perché funge da ricevitore di telemetria, e non da fonte di telemetria.

Vedere anche