Explore the .NET Aspire dashboard

In the upcoming sections, you discover how to create a .NET Aspire project and embark on the following tasks:

• Investigate the dashboard's capabilities by using the app generated from the project template as explained in the Quickstart: Build your first .NET Aspire project.

• Delve into the features of the .NET Aspire dashboard app.

The screenshots featured in this article showcase the dark theme. For more information on theme selection, see Theme selection.

Dashboard authentication

When you run a .NET Aspire app host, the orchestrator starts up all the app's dependent resources and then opens a browser window to the dashboard. The .NET Aspire dashboard requires token-based authentication for its users because it displays environment variables and other sensitive information.

When the dashboard is launched from Visual Studio or Visual Studio Code (with the C# Dev Kit extension), the browser is automatically logged in, and the dashboard opens directly. This is the typical developer F5 experience, and the authentication login flow is automated by the .NET Aspire tooling.

However, if you start the app host from the command line, you're presented with the login page. The console window displays a URL that you can select on to open the dashboard in your browser.

The URL contains a token query string (with the token value mapped to the t name part) that's used to log in to the dashboard. If your console supports it, you can hold the Ctrl key and then select the link to open the dashboard in your browser. This method is easier than copying the token from the console and pasting it into the login page. If you end up on the dashboard login page without either of the previously described methods, you can always return to the console to copy the token.

The login page accepts a token and provides helpful instructions on how to obtain the token, as shown in the following screenshot:

After copying the token from the console and pasting it into the login page, select the Log in button.

The dashboard persists the token as a browser persistent cookie, which remains valid for three days. Persistent cookies have an expiration date and remain valid even after closing the browser. This means that users don't need to log in again if they close and reopen the browser. For more information, see the Security considerations for running the .NET Aspire dashboard documentation.

Resources page

The Resources page is the default home page of the .NET Aspire dashboard. This page lists all of the .NET projects, containers, and executables included in your .NET Aspire solution. For example, the starter application includes two projects:

• apiservice: A back-end API project built using Minimal APIs.
• webfrontend: The front-end UI project built using Blazor.

The dashboard also provides essential details about each resource:

• Type: Displays whether the resource is a project, container, or executable.
• Name: The name of the resource.
• State: Displays whether or not the resource is currently running.
  • Errors: Within the State column, errors are displayed as a badge with the error count. It's useful to understand quickly what resources are reporting errors. Selecting the badge takes you to the semantic logs for that resource with the filter at an error level.
• Start time: When the resource started running.
• Source: The location of the resource on the device.
• Endpoints: One or more URLs to reach the running resource directly.
• Logs: A link to the resource logs page.
• Actions: A set of actions that can be performed on the resource:
  • Stop / Start: Stop (or Start) the resource—depending on the current State.
  • Console logs: Navigate to the resource's console logs.
  • Ellipsis: A submenu with extra resource specific actions:
    • View details: View the resource details.
    • Console log: Navigate to the resource's console logs.
    • Structured logs: Navigate to the resource's structured logs.
    • Traces: Navigate to the resource's traces.
    • Metrics: Navigate to the resource's metrics.
    • Restart: Stop and then start the resource.

Consider the following screenshot of the resources page:

Resource actions

Each resource has a set of available actions that are conditionally enabled based on the resource's current state. For example, if a resource is running, the Stop action is enabled. If the resource is stopped, the Start action is enabled. Likewise, some actions are disabled when they're unavailable, for example, some resources don't have structured logs. In these situations, the Structured logs action is disabled.

Stop or Start a resource

The .NET Aspire dashboard allows you to stop or start a resource by selecting the Stop or Start button in the Actions column. Consider the following screenshot of the resources page with the Stop button selected:

When you select Stop, the resource stops running, and the State column updates to reflect the change.

Note

For project resources, when the debugger is attached, it's reattached on restart.

The Start button is then enabled, allowing you to start the resource again. Additionally, the dashboard displays a toast notification of the result of the action:

When a resource is in a non-running state, the Start button is enabled. Selecting Start starts the resource, and the State column updates to reflect the change. The Stop button is then enabled, allowing you to stop the resource again. The dashboard displays a toast notification of the result of the action:

Tip

Resources that depend on other resources that are stopped, or restarted, might experience temporary errors. This is expected behavior and is typically resolved when the dependent resources are in a Running state once again.

Resource submenu actions

Selecting the horizontal ellipsis icon in the Actions column opens a submenu with additional resource-specific actions. In addition to the built-in resource submenu actions, you can also define custom resource actions by defining custom commands. For more information, see Custom resource commands in .NET Aspire. For the built-in resource submenu actions, consider the following screenshot:

The following submenu actions are available:

• View details: View the resource details.
• Console log: Navigate to the resource's console logs.
• Structured logs: Navigate to the resource's structured logs.
• Traces: Navigate to the resource's traces.
• Metrics: Navigate to the resource's metrics.
• Restart: Stop and then start the resource.

Important

There might be resources with disabled submenu actions. They're greyed out when they're disabled. For example, the following screenshot shows the submenu actions disabled:

Copy or Open in text visualizer

To view a text visualizer of certain columns, on hover you see a vertical ellipsis icon. Select the icon to display the available options:

• Copy to clipboard
• Open in text visualizer

Consider the following screenshot of the ellipsis menu options:

When you select the Open in text visualizer option, a modal dialog opens with the text displayed in a larger format. Consider the following screenshot of the text visualizer modal dialog:

Some values are formatted as JSON or XML. In these cases, the text visualizer enables the Select format dropdown to switch between the different formats.

Resource details

You can obtain full details about each resource by selecting the ellipsis button in the Actions column and then selecting View details. The Details page provides a comprehensive view of the resource:

The search bar in the upper right of the dashboard also provides the option to filter the list, which is useful for .NET Aspire projects with many resources. To select the types of resources that are displayed, drop down the arrow to the left of the filter textbox:

In this example, only containers are displayed in the list. For example, if you enable Use Redis for caching when creating a .NET Aspire project, you should see a Redis container listed:

Executables are stand-alone processes. You can configure a .NET Aspire project to run a stand-alone executable during startup, though the default starter templates don't include any executables by default.

The following screenshot shows an example of a project that has errors:

Selecting the error count badge navigates to the Structured logs page with a filter applied to show only the logs relevant to the resource:

To see the log entry in detail for the error, select the View button to open a window below the list with the structured log entry details:

For more information and examples of Structured logs, see the Structured logs page section.

Note

The resources page isn't available if the dashboard is started without a configured resource service. The dashboard starts on the Structured logs page instead. This is the default experience when the dashboard is run in standalone mode without additional configuration.

For more information about configuring a resource service, see Dashboard configuration.

Monitoring pages

The .NET Aspire dashboard provides various ways to view logs, traces, and metrics for your app. This information enables you to track the behavior and performance of your app and to diagnose any issues that arise.

Console logs page

The Console logs page displays text that each resource in your app has sent to standard output. Logs are a useful way to monitor the health of your app and diagnose issues. Logs are displayed differently depending on the source, such as project, container, or executable.

When you open the Console logs page, you must select a source in the Select a resource drop-down list.

If you select a project, the live logs are rendered with a stylized set of colors that correspond to the severity of the log; green for information as an example. Consider the following example screenshot of project logs with the apiservice project selected:

When errors occur, they're styled in the logs such that they're easy to identify. Consider the following example screenshot of project logs with errors:

If you select a container or executable, formatting is different from a project but verbose behavior information is still available. Consider the following example screenshot of a container log with the cache container selected:

Resource replicas

When project resources are replicated using the WithReplicas API, they're represented in the resource selector under a top-level named resource entry with an icon to indicator. Each replicated resource is listed under the top-level resource entry, with its corresponding unique name. Consider the following example screenshot of a replicated project resource:

The preceding screenshot shows the catalogservice (application) project with two replicas, catalogservice-2bpj2qdq6k and catalogservice-6ljdin0hc0. Each replica has its own set of logs that can be viewed by selecting the replica name.

Structured logs page

.NET Aspire automatically configures your projects with logging using OpenTelemetry. Navigate to the Structured logs page to view the semantic logs for your .NET Aspire project. Semantic, or structured logging makes it easier to store and query log-events, as the log-event message-template and message-parameters are preserved, instead of just transforming them into a formatted message. You notice a clean structure for the different logs displayed on the page using columns:

• Resource: The resource the log originated from.
• Level: The log level of the entry, such as information, warning, or error.
• Timestamp: The time that the log occurred.
• Message: The details of the log.
• Trace: A link to the relevant trace for the log, if applicable.
• Details: Additional details or metadata about the log entry.

Consider the following example screenshot of semantic logs:

Filter structured logs

The structured logs page also provides a search bar to filter the logs by service, level, or message. You use the Level drop down to filter by log level. You can also filter by any log property by selecting the filter icon button, which opens the advanced filter dialog.

Consider the following screenshots showing the structured logs, filtered to display items with "Hosting" in the message text:

Traces page

Navigate to the Traces page to view all of the traces for your app. .NET Aspire automatically configures tracing for the different projects in your app. Distributed tracing is a diagnostic technique that helps engineers localize failures and performance issues within applications, especially those that might be distributed across multiple machines or processes. For more information, see .NET distributed tracing. This technique tracks requests through an application and correlates work done by different application integrations. Traces also help identify how long different stages of the request took to complete. The traces page displays the following information:

• Timestamp: When the trace completed.
• Name: The name of the trace, prefixed with the project name.
• Spans: The resources involved in the request.
• Duration: The time it took to complete the request. This column includes a radial icon that illustrates the duration of the request in comparison with the others in the list.

Filter traces

The traces page also provides a search bar to filter the traces by name or span. Apply a filter, and notice the trace results are updated immediately. Consider the following screenshot of traces with a filter applied to weather and notice how the search term is highlighted in the results:

When filtering traces in the Add filter dialog, after selecting a Parameter and corresponding Condition, the Value selection is pre-populated with the available values for the selected parameter. Consider the following screenshot of the Add filter dialog with the http.route parameter selected:

Combine telemetry from multiple resources

When a resource has multiple replicas, you can filter telemetry to view data from all instances at once. Select the parent resource, labeled (application), as shown in the following screenshot:

After selecting the parent resource, the traces page displays telemetry from all instances of the resource.

Trace details

The trace details page contains various details pertinent to the request, including:

• Trace Detail: When the trace started.
• Duration: The time it took to complete the request.
• Resources: The number of resources involved in the request.
• Depth: The number of layers involved in the request.
• Total Spans: The total number of spans involved in the request.

Each span is represented as a row in the table, and contains a Name. Spans also display the error icon if an error occurred within that particular span of the trace. Spans that have a type of client/consumer, but don't have a span on the server, show an arrow icon and then the destination address. This represents a client call to a system outside of the .NET Aspire project. For example, an HTTP request an external web API, or a database call.

Within the trace details page, there's a View Logs button that takes you to the structured logs page with a filter applied to show only the logs relevant to the request. Consider an example screenshot depicting the structured logs page with a filter applied to show only the logs relevant to the trace:

The structured logs page is discussed in more detail in the Structured logs page section.

Trace examples

Each trace has a color, which is generated to help differentiate between spans—one color for each resource. The colors are reflected in both the traces page and the trace detail page. When traces depict an arrow icon, those icons are colorized as well to match the span of the target trace. Consider the following example screenshot of traces:

You can also select the View button to navigate to a detailed view of the request and the duration of time it spent traveling through each application layer. Consider an example selection of a trace to view its details:

For each span in the trace, select View to see more details:

Scroll down in the span details pain to see full information. At the bottom of the span details pane, some span types, such as this call to a cache, show span event timings:

When errors are present, the page renders an error icon next to the trace name. Consider an example screenshot of traces with errors:

And the corresponding detailed view of the trace with errors:

Metrics page

Navigate to the Metrics page to view the metrics for your app. .NET Aspire automatically configures metrics for the different projects in your app. Metrics are a way to measure the health of your application and can be used to monitor the performance of your app over time.

Each metric-publishing project in your app has its own metrics. The metrics page displays a selection pane for each top-level meter and the corresponding instruments that you can select to view the metric.

Consider the following example screenshot of the metrics page, with the webfrontend project selected and the System.Net.Http meter's http.client.request.duration metric selected:

In addition to the metrics chart, the metrics page includes an option to view the data as a table instead. Consider the following screenshot of the metrics page with the table view selected:

Under the chart, there's a list of filters you can apply to focus on the data that interests you. For example, in the following screenshot, the http.request.method field is filtered to show only GET requests:

You can also choose to select the count of the displayed metric on the vertical access, instead of its values:

For more information about metrics, see Built-in Metrics in .NET.

Exemplars

The .NET Aspire dashboard supports and displays OpenTelemetry Exemplars. An exemplar is a recorded value that contains additional associate context from traces with metric events, making them useful for linking trace signals with metrics.

An exemplar is made up of the following data points:

• trace_id and span_id: (Optional) The trace associated with the recording, identified by trace and span identifiers.
• time_unix_nano: The time of the observation, represented in Unix nanoseconds.
• value: The recorded value.
• filtered_attributes: A set of filtered attributes that provide additional context when the observation was made.

Exemplars are displayed in the metrics chart as a small round dot next to the data point. When you hover over the indicator, a tooltip displays the exemplar details as shown in the following screenshot:

The preceding screenshot shows the exemplar details for the http.client.request.duration metric. The exemplar details include the:

• Resource name.
• Operation performed, in this case an HTTP GET to the /catalog/images/{id}.
• Corresponding value and the time stamp.

Selecting the exemplar indicator opens the trace details page, where you can view the trace associated, for example consider the following screenshot:

For more information, see OpenTelemetry Docs: Exemplars.

Theme selection

By default, the theme is set to follow the System theme, which means the dashboard uses the same theme as your operating system. You can also select the Light or Dark theme to override the system theme. Theme selections are persisted.

The following screenshot shows the theme selection dialog, with the default System theme selected:

If you prefer the Light theme, you can select it from the theme selection dialog:

Dashboard shortcuts

The .NET Aspire dashboard provides various shortcuts to help you navigate and control different parts of the dashboard. To display the keyboard shortcuts, press Shift + ?, or select the question mark icon in the top-right corner of the dashboard:

The following shortcuts are available:

Panels:

• +: Increase panel size.
• -: Decrease panel size.
• Shift + r: Reset panel size.
• Shift + t: Toggle panel orientation.
• Shift + x: Close panel.

Page navigation:

• r: Go to Resources.
• c: Go to Console Logs.
• s: Go to Structured Logs.
• t: Go to Traces.
• m: Go to Metrics.

Site-wide navigation:

• ?: Got to Help.
• Shift + s: Go to Settings.

Next steps

Standalone .NET Aspire dashboard