diff --git a/docs/fundamentals/aspire-sdk-templates.md b/docs/fundamentals/aspire-sdk-templates.md index fa747f5689..cfebbaa0dd 100644 --- a/docs/fundamentals/aspire-sdk-templates.md +++ b/docs/fundamentals/aspire-sdk-templates.md @@ -109,6 +109,14 @@ dotnet new aspire-starter > dotnet new aspire-apphost --framework net8.0 > ``` +You need to trust the ASP.NET Core :::no-loc text="localhost"::: certificate before running the app. Run the following command: + +```dotnetcli +dotnet dev-certs https --trust +``` + +For more information, see [Troubleshoot untrusted localhost certificate in .NET Aspire](../troubleshooting/untrusted-localhost-certificate.md). For in-depth details about troubleshooting localhost certificates on Linux, see [ASP.NET Core: GitHub repository issue #32842](https://github.com/dotnet/aspnetcore/issues/32842). + :::zone-end ## See also diff --git a/docs/fundamentals/dashboard/explore.md b/docs/fundamentals/dashboard/explore.md index 5777ef1d3f..18b8736275 100644 --- a/docs/fundamentals/dashboard/explore.md +++ b/docs/fundamentals/dashboard/explore.md @@ -146,7 +146,7 @@ Some values are formatted as JSON or XML. In these cases, the text visualizer en 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: -:::image type="content" source="media/explore/resource-details.png" lightbox="media/explore/resource-details.png" alt-text="A screenshot of the .NET Aspire dashboard Resources page with the details of a selected resource displayed."::: +:::image type="content" source="media/explore/resource-details-thumb.png" lightbox="media/explore/resource-details.png" alt-text="A screenshot of the .NET Aspire dashboard Resources page with the details of a selected resource displayed."::: 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: @@ -168,7 +168,7 @@ Selecting the error count badge navigates to the [Structured logs](#structured-l 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: -:::image type="content" source="media/explore/structured-logs-errors-view.png" lightbox="media/explore/structured-logs-errors-view.png" alt-text="A screenshot of the .NET Aspire dashboard Structured logs page, showing a lower window with the structured log entry details."::: +:::image type="content" source="media/explore/structured-logs-errors-view-thumb.png" lightbox="media/explore/structured-logs-errors-view.png" alt-text="A screenshot of the .NET Aspire dashboard Structured logs page, showing a lower window with the structured log entry details."::: For more information and examples of Structured logs, see the [Structured logs page](#structured-logs-page) section. @@ -199,6 +199,10 @@ If you select a container or executable, formatting is different from a project :::image type="content" source="media/explore/container-logs.png" lightbox="media/explore/container-logs.png" alt-text="A screenshot of the .NET Aspire dashboard Console logs page with a container source selected."::: +You can download any console log to your local machine and use your preferred text programs to analyze it: + +:::image type="content" source="media/explore/download-console-logs.png" lightbox="media/explore/download-console-logs.png" alt-text="A screenshot of the .NET Aspire dashboard Console logs page showing how to download a log to your local machine."::: + #### Resource replicas When project resources are replicated using the 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: @@ -283,11 +287,11 @@ Each trace has a color, which is generated to help differentiate between spans :::image type="content" source="media/explore/traces.png" lightbox="media/explore/traces.png" alt-text="A screenshot of the .NET Aspire dashboard Traces page."::: -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: +In the **Actions** column, you can select **View details** 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: :::image type="content" source="media/explore/trace.png" lightbox="media/explore/trace.png" alt-text="A screenshot of the .NET Aspire dashboard Trace details page."::: -For each span in the trace, select **View** to see more details: +For each span in the trace, select **View details** to see more details: :::image type="content" source="media/explore/trace-span-details.png" lightbox="media/explore/trace-span-details.png" alt-text="A screenshot of the .NET Aspire dashboard Trace details page with the details of a span displayed."::: @@ -295,6 +299,10 @@ Scroll down in the span details pain to see full information. At the bottom of t :::image type="content" source="media/explore/trace-span-event-details.png" lightbox="media/explore/trace-span-event-details.png" alt-text="A screenshot of the .NET Aspire dashboard Trace details page with the event timings for a span displayed."::: +For complex traces with many spans, use the **Filter** textbox to display only matching spans: + +:::image type="content" source="media/explore/filter-spans-trace-details.png" lightbox="media/explore/filter-spans-trace-details.png" alt-text="A screenshot of the .NET Aspire dashboard Trace details page with the filter used to display only weather spans."::: + When errors are present, the page renders an error icon next to the trace name. Consider an example screenshot of traces with errors: :::image type="content" source="media/explore/traces-errors.png" lightbox="media/explore/traces-errors.png" alt-text="A screenshot of the .NET Aspire dashboard Traces page, showing traces with errors."::: @@ -349,6 +357,30 @@ Selecting the exemplar indicator opens the trace details page, where you can vie For more information, see [OpenTelemetry Docs: Exemplars](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exemplars). +### Interact with telemetry + +Telemetry information is generated continuously while you run a .NET Aspire application and it can flood the dashboard with information. The dashboard includes tools you can use to reduce the amount of data displayed in monitoring pages and make it easier to target specific events. + +#### Pause telemetry output + +In the **Console logs**, **Structured logs**, **Traces**, and **Metrics** pages, you can pause the collection of telemetry data: + +:::image type="content" source="media/explore/pause-telemetry.png" lightbox="media/explore/pause-telemetry.png" alt-text="A screenshot of the .NET Aspire dashboard Console logs page, showing how to pause telemetry."::: + +The pause button affects only the type of telemetry displayed on that page. So, for example, if you pause console logs collection, your app continues to collect structured logs, traces, and metrics telemetry. + +#### Remove data + +Next to the **Pause** button, the **Remove data** button enables you to clear the telemetry on the current page. Drop down the list, and choose whether to remove the telemetry for all resource, or only for the current resource: + +:::image type="content" source="media/explore/remove-telemetry-data-thumb.png" lightbox="media/explore/remove-telemetry-data.png" alt-text="A screenshot of the .NET Aspire dashboard Structured logs page, showing how to remove telemetry."::: + +The button is available for control logs, structured logs, traces, and metrics. It works independently for each type of data. + +If you want to remove all telemetry of all types and for all resources in a single step, use the **Remove all** button in the **Settings** dialog: + +:::image type="content" source="media/explore/remove-all-telemetry.png" lightbox="media/explore/remove-all-telemetry.png" alt-text="A screenshot of the .NET Aspire dashboard Settings page, showing how to remove all telemetry."::: + ## Settings dialog diff --git a/docs/fundamentals/dashboard/media/explore/download-console-logs.png b/docs/fundamentals/dashboard/media/explore/download-console-logs.png new file mode 100644 index 0000000000..309b337f70 Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/download-console-logs.png differ diff --git a/docs/fundamentals/dashboard/media/explore/filter-spans-trace-details.png b/docs/fundamentals/dashboard/media/explore/filter-spans-trace-details.png new file mode 100644 index 0000000000..6600b869e6 Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/filter-spans-trace-details.png differ diff --git a/docs/fundamentals/dashboard/media/explore/pause-telemetry.png b/docs/fundamentals/dashboard/media/explore/pause-telemetry.png new file mode 100644 index 0000000000..2ed7a457e7 Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/pause-telemetry.png differ diff --git a/docs/fundamentals/dashboard/media/explore/remove-all-telemetry.png b/docs/fundamentals/dashboard/media/explore/remove-all-telemetry.png new file mode 100644 index 0000000000..cc478fac74 Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/remove-all-telemetry.png differ diff --git a/docs/fundamentals/dashboard/media/explore/remove-telemetry-data-thumb.png b/docs/fundamentals/dashboard/media/explore/remove-telemetry-data-thumb.png new file mode 100644 index 0000000000..c7e3fad237 Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/remove-telemetry-data-thumb.png differ diff --git a/docs/fundamentals/dashboard/media/explore/remove-telemetry-data.png b/docs/fundamentals/dashboard/media/explore/remove-telemetry-data.png new file mode 100644 index 0000000000..8c4dd1911a Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/remove-telemetry-data.png differ diff --git a/docs/fundamentals/dashboard/media/explore/resource-details-thumb.png b/docs/fundamentals/dashboard/media/explore/resource-details-thumb.png new file mode 100644 index 0000000000..71adbd4d66 Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/resource-details-thumb.png differ diff --git a/docs/fundamentals/dashboard/media/explore/resource-details.png b/docs/fundamentals/dashboard/media/explore/resource-details.png index c169dd8578..1e20d3a409 100644 Binary files a/docs/fundamentals/dashboard/media/explore/resource-details.png and b/docs/fundamentals/dashboard/media/explore/resource-details.png differ diff --git a/docs/fundamentals/dashboard/media/explore/resources-filtered-containers.png b/docs/fundamentals/dashboard/media/explore/resources-filtered-containers.png index b87203289c..0583e7d935 100644 Binary files a/docs/fundamentals/dashboard/media/explore/resources-filtered-containers.png and b/docs/fundamentals/dashboard/media/explore/resources-filtered-containers.png differ diff --git a/docs/fundamentals/dashboard/media/explore/structured-logs-errors-view-thumb.png b/docs/fundamentals/dashboard/media/explore/structured-logs-errors-view-thumb.png new file mode 100644 index 0000000000..cfe186b0e1 Binary files /dev/null and b/docs/fundamentals/dashboard/media/explore/structured-logs-errors-view-thumb.png differ diff --git a/docs/fundamentals/dashboard/media/explore/structured-logs-errors-view.png b/docs/fundamentals/dashboard/media/explore/structured-logs-errors-view.png index 9865a1ecf2..588edf1195 100644 Binary files a/docs/fundamentals/dashboard/media/explore/structured-logs-errors-view.png and b/docs/fundamentals/dashboard/media/explore/structured-logs-errors-view.png differ diff --git a/docs/fundamentals/dashboard/media/explore/trace-span-details.png b/docs/fundamentals/dashboard/media/explore/trace-span-details.png index 2f7559e8c3..ce120a29c9 100644 Binary files a/docs/fundamentals/dashboard/media/explore/trace-span-details.png and b/docs/fundamentals/dashboard/media/explore/trace-span-details.png differ diff --git a/docs/fundamentals/dashboard/media/explore/trace.png b/docs/fundamentals/dashboard/media/explore/trace.png index bc267d4e95..9632d1948b 100644 Binary files a/docs/fundamentals/dashboard/media/explore/trace.png and b/docs/fundamentals/dashboard/media/explore/trace.png differ diff --git a/docs/fundamentals/service-defaults.md b/docs/fundamentals/service-defaults.md index 87c21d5cf8..0553f1fbbf 100644 --- a/docs/fundamentals/service-defaults.md +++ b/docs/fundamentals/service-defaults.md @@ -1,7 +1,7 @@ --- title: .NET Aspire service defaults description: Learn about the .NET Aspire service defaults project. -ms.date: 11/04/2024 +ms.date: 04/21/2025 ms.topic: reference uid: dotnet/aspire/service-defaults --- @@ -121,7 +121,8 @@ The `MapDefaultEndpoints` method: - Maps the health checks endpoint to `/health`. - Maps the liveness endpoint to `/alive` route where the health check tag contains `live`. -For more information, see [.NET Aspire health checks](health-checks.md). +> [!NOTE] +> Starting with .NET Aspire 9.2, the [starter template](aspire-sdk-templates.md#solution-templates) has been updated to include a call to for ASP.NET Core projects. To keep the request trace logs cleaner during development, traces for the configured health endpoints (`/health` and `/alive`) are now excluded by default in the **Service Defaults** project template. ## Custom service defaults diff --git a/docs/fundamentals/snippets/template/YourAppName/Extensions.cs b/docs/fundamentals/snippets/template/YourAppName/Extensions.cs index 97e3cc6b28..141f940567 100644 --- a/docs/fundamentals/snippets/template/YourAppName/Extensions.cs +++ b/docs/fundamentals/snippets/template/YourAppName/Extensions.cs @@ -1,20 +1,24 @@ -using Microsoft.AspNetCore.Builder; +using Microsoft.AspNetCore.Builder; using Microsoft.AspNetCore.Diagnostics.HealthChecks; using Microsoft.Extensions.DependencyInjection; using Microsoft.Extensions.Diagnostics.HealthChecks; using Microsoft.Extensions.Logging; using Microsoft.Extensions.ServiceDiscovery; -using OpenTelemetry.Logs; +using OpenTelemetry; using OpenTelemetry.Metrics; using OpenTelemetry.Trace; namespace Microsoft.Extensions.Hosting; - +// Adds common .NET Aspire services: service discovery, resilience, health checks, and OpenTelemetry. +// This project should be referenced by each service project in your solution. +// To learn more about using this project, see https://aka.ms/dotnet/aspire/service-defaults public static class Extensions { + private const string HealthEndpointPath = "/health"; + private const string AlivenessEndpointPath = "/alive"; + // - public static IHostApplicationBuilder AddServiceDefaults( - this IHostApplicationBuilder builder) + public static TBuilder AddServiceDefaults(this TBuilder builder) where TBuilder : IHostApplicationBuilder { builder.ConfigureOpenTelemetry(); @@ -42,8 +46,7 @@ public static IHostApplicationBuilder AddServiceDefaults( // // - public static IHostApplicationBuilder ConfigureOpenTelemetry( - this IHostApplicationBuilder builder) + public static TBuilder ConfigureOpenTelemetry(this TBuilder builder) where TBuilder : IHostApplicationBuilder { builder.Logging.AddOpenTelemetry(logging => { @@ -60,15 +63,14 @@ public static IHostApplicationBuilder ConfigureOpenTelemetry( }) .WithTracing(tracing => { - if (builder.Environment.IsDevelopment()) - { - // We want to view all traces in development - tracing.SetSampler(new AlwaysOnSampler()); - } - - tracing.AddAspNetCoreInstrumentation() - // Uncomment the following line to enable gRPC instrumentation - // (requires the OpenTelemetry.Instrumentation.GrpcNetClient package) + tracing.AddSource(builder.Environment.ApplicationName) + .AddAspNetCoreInstrumentation(tracing => + // Exclude health check requests from tracing + tracing.Filter = context => + !context.Request.Path.StartsWithSegments(HealthEndpointPath) + && !context.Request.Path.StartsWithSegments(AlivenessEndpointPath) + ) + // Uncomment the following line to enable gRPC instrumentation (requires the OpenTelemetry.Instrumentation.GrpcNetClient package) //.AddGrpcClientInstrumentation() .AddHttpClientInstrumentation(); }); @@ -80,31 +82,17 @@ public static IHostApplicationBuilder ConfigureOpenTelemetry( // // - private static IHostApplicationBuilder AddOpenTelemetryExporters( - this IHostApplicationBuilder builder) + private static TBuilder AddOpenTelemetryExporters(this TBuilder builder) where TBuilder : IHostApplicationBuilder { - var useOtlpExporter = !string.IsNullOrWhiteSpace( - builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]); + var useOtlpExporter = !string.IsNullOrWhiteSpace(builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]); if (useOtlpExporter) { - builder.Services.Configure( - logging => logging.AddOtlpExporter()); - builder.Services.ConfigureOpenTelemetryMeterProvider( - metrics => metrics.AddOtlpExporter()); - builder.Services.ConfigureOpenTelemetryTracerProvider( - tracing => tracing.AddOtlpExporter()); + builder.Services.AddOpenTelemetry().UseOtlpExporter(); } - // Uncomment the following lines to enable the Prometheus exporter - // (requires the OpenTelemetry.Exporter.Prometheus.AspNetCore package) - // builder.Services.AddOpenTelemetry() - // .WithMetrics(metrics => metrics.AddPrometheusExporter()); - - // Uncomment the following lines to enable the Azure Monitor exporter - // (requires the Azure.Monitor.OpenTelemetry.AspNetCore package) - //if (!string.IsNullOrEmpty( - // builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"])) + // Uncomment the following lines to enable the Azure Monitor exporter (requires the Azure.Monitor.OpenTelemetry.AspNetCore package) + //if (!string.IsNullOrEmpty(builder.Configuration["APPLICATIONINSIGHTS_CONNECTION_STRING"])) //{ // builder.Services.AddOpenTelemetry() // .UseAzureMonitor(); @@ -115,8 +103,7 @@ private static IHostApplicationBuilder AddOpenTelemetryExporters( // // - public static IHostApplicationBuilder AddDefaultHealthChecks( - this IHostApplicationBuilder builder) + public static TBuilder AddDefaultHealthChecks(this TBuilder builder) where TBuilder : IHostApplicationBuilder { builder.Services.AddHealthChecks() // Add a default liveness check to ensure app is responsive @@ -129,23 +116,15 @@ public static IHostApplicationBuilder AddDefaultHealthChecks( // public static WebApplication MapDefaultEndpoints(this WebApplication app) { - // Uncomment the following line to enable the Prometheus endpoint - // (requires the OpenTelemetry.Exporter.Prometheus.AspNetCore package) - // app.MapPrometheusScrapingEndpoint(); - - // Adding health checks endpoints to applications in non-development - // environments has security implications. - // See https://aka.ms/dotnet/aspire/healthchecks for details before - // enabling these endpoints in non-development environments. + // Adding health checks endpoints to applications in non-development environments has security implications. + // See https://aka.ms/dotnet/aspire/healthchecks for details before enabling these endpoints in non-development environments. if (app.Environment.IsDevelopment()) { - // All health checks must pass for app to be considered ready to - // accept traffic after starting - app.MapHealthChecks("/health"); + // All health checks must pass for app to be considered ready to accept traffic after starting + app.MapHealthChecks(HealthEndpointPath); - // Only health checks tagged with the "live" tag must pass for - // app to be considered alive - app.MapHealthChecks("/alive", new HealthCheckOptions + // Only health checks tagged with the "live" tag must pass for app to be considered alive + app.MapHealthChecks(AlivenessEndpointPath, new HealthCheckOptions { Predicate = r => r.Tags.Contains("live") }); @@ -154,4 +133,4 @@ public static WebApplication MapDefaultEndpoints(this WebApplication app) return app; } // -} \ No newline at end of file +}