YMJake.Aspire.Hosting.VictoriaLogs 0.1.0-alpha.1

Aspire.Hosting.VictoriaLogs

VictoriaLogs hosting integration for .NET Aspire.

dotnet add package YMJake.Aspire.Hosting.VictoriaLogs

VictoriaLogs is a single-binary log database from the VictoriaMetrics project: it stores logs, exposes an HTTP insert API on several protocols, and serves queries through LogsQL. This package models one single-node container as one Aspire resource.

vlogs
└── victoriametrics/victoria-logs:v1.53.0  (http endpoint -> 9428)

Usage

IDistributedApplicationBuilder builder = DistributedApplication.CreateBuilder(args);

IResourceBuilder<VictoriaLogsResource> vlogs = builder.AddVictoriaLogs("vlogs");

builder.AddProject<Projects.Api>("api")
    .WithReference(vlogs);

await builder.Build().RunAsync();

By default, the integration creates:

• a victoriametrics/victoria-logs container
• an HTTP endpoint on http://localhost:9428 (a random host port when port is omitted)
• --storageDataPath=/vlogs and --retentionPeriod=7d
• a /health health check
• a dashboard link that opens the built-in UI at /select/vmui/

Connection string

WithReference(vlogs) injects ConnectionStrings__vlogs with the base URL of the instance, for example http://localhost:9428. Container-to-container consumers get the container network address instead of localhost.

The connection string is the base URL only. Each client appends its own path:

OpenTelemetry logs

For .NET services, reference the Aspire.VictoriaLogs client package and call AddVictoriaLogsEndpoint with the same connection name. It reads ConnectionStrings:vlogs, so the URL never appears in code:

// Api
builder.AddVictoriaLogsEndpoint("vlogs");

Only the log signal is redirected; traces and metrics keep flowing to the Aspire dashboard.

WithLogsExporter is the AppHost-side alternative for resources that are not .NET, or that already configure their OTLP exporter from environment variables:

builder.AddProject<Projects.Api>("api")
    .WithLogsExporter(vlogs);

It sets only OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (to <base>/insert/opentelemetry/v1/logs) and OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf.

The full signal path is required in both cases: the .NET OTLP exporter uses OTEL_EXPORTER_OTLP_LOGS_ENDPOINT verbatim and only appends v1/logs to the generic OTEL_EXPORTER_OTLP_ENDPOINT.

Retention and persistence

The retention window defaults to 7d and is enforced by VictoriaLogs itself. The minimum supported value is 1d.

builder.AddVictoriaLogs("vlogs", retentionPeriod: "30d");

Data is ephemeral by default. Persist it explicitly:

builder.AddVictoriaLogs("vlogs")
    .WithDataVolume();              // auto-generated volume name

builder.AddVictoriaLogs("vlogs")
    .WithDataVolume("vlogs-data");  // explicit volume name

builder.AddVictoriaLogs("vlogs")
    .WithDataBindMount("./data/vlogs");

Querying

The web UI is available at http://localhost:9428/select/vmui/. LogsQL queries can also be issued over HTTP:

curl 'http://localhost:9428/select/logsql/query' --data-urlencode 'query=_time:5m "hello"'

LogsQL treats bare words as filters and - as negation, so quote phrases that contain hyphens.

Notes

• Only the single-node image is supported. Cluster mode (vlinsert/vlselect/vlstorage) is out of scope.
• VictoriaLogs has no authentication of its own. Keep the endpoint on localhost, or put a proxy in front of it for shared environments.
• The container listens on 9428 and needs no configuration beyond the data path and retention.