The .NET team recently released the Aspire dashboard as a standalone Docker public image. This can be easily used as an OpenTelemetry exporter to collect and display the traces, metrics, and structured logs generated by your applications during local development. The Aspire dashboard can be used to visualize telemetry emitted by any application using the OpenTelemetry SDK which is available for .NET, Java, JavaScript, PHP, Python, and many others runtimes.
Previously, the recommended solution was to use Docker Compose to bootstrap a complex setup including components such as OpenTelemetry Collector, Grafana, Loki, Jaeger, Zipkin, Prometheus, and others. It was just too much. At the end of the day, most developers simply want to visualize their application telemetry, not learn to become YAML engineers.
The Aspire dashboard is currently in preview and is subject to change. Last updated for preview 6.
Start the standalone Aspire dashboard
Ensure you have Docker started on your machine. Then, execute the following command to start the Aspire dashboard:
docker run --rm -it -p 18888:18888 -p 4317:18889 -d --name aspire-dashboard -e DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS='true' mcr.microsoft.com/dotnet/nightly/aspire-dashboard:8.0.0-preview.6
This command starts a container from the mcr.microsoft.com/dotnet/nightly/aspire-dashboard
image and exposes ports 18888
and 4317
on your local machine. Port 18888
is used to access the UI of the dashboard, while port 4317
is used to receive telemetry in accordance with the OpenTelemetry Protocol (OTLP).
The DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS
environment variable is set to true
to skip the login page that has been added in preview 6. As long as you are running the dashboard locally, this should be fine. Consider securing the dashboard otherwise.
Modify your apps to emit OpenTelemetry data
In your applications, install and configure the OpenTelemetry SDK corresponding to the technology or language you are using, and start them by providing the following environment variable. I provide a complete code sample at the end of this article for .NET.
OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
OTEL_SERVICE_NAME="your-app-name"
Then, use your application and make sure it generates telemetry.
Visualize your OpenTelemetry data
The Aspire dashboard is accessible at http://localhost:18888
in your browser. Here you can visualize the traces, metrics, and structured logs emitted by your applications.
Here is the structured logs screen, with the ability to view the details of each:
The traces screen, currently focused on a specific trace:
And finally, the metrics screen:
Bonus: complete code sample for ASP.NET Core
Create a blank ASP.NET Core application and install the following packages (note that newer versions may be available since the publication of this article):
<PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.8.1" />
<PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.8.1" />
<PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.8.1" />
<PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.8.1" />
<PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.8.0"/>
Next, replace your Program.cs
with the following code:
using OpenTelemetry;
using OpenTelemetry.Metrics;
using OpenTelemetry.Trace;
var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddOpenTelemetry(logging =>
{
logging.IncludeFormattedMessage = true;
logging.IncludeScopes = true;
});
builder.Services.AddOpenTelemetry()
.WithMetrics(metrics =>
{
metrics.AddRuntimeInstrumentation()
.AddMeter("Microsoft.AspNetCore.Hosting", "Microsoft.AspNetCore.Server.Kestrel", "System.Net.Http");
})
.WithTracing(tracing =>
{
tracing.AddAspNetCoreInstrumentation()
.AddHttpClientInstrumentation();
});
var useOtlpExporter = !string.IsNullOrWhiteSpace(builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]);
if (useOtlpExporter)
{
builder.Services.AddOpenTelemetry().UseOtlpExporter();
}
var app = builder.Build();
app.MapGet("/", () => "Hello world");
app.Run();
Finally, here is the content of the appsettings.Development.json
file:
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning"
}
},
"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "my-web-app"
}
Top comments (2)
The .NET Aspire dashboard is a game-changer for local development! What challenges did you face during its configuration?
None? It just works