Training
Module
Use telemetry in a .NET Aspire project - Training
In this module, you'll learn about using telemetry to record the behavior of a cloud-native application and how the .NET Aspire stack makes it easier store data and view it later.
This browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
One of the primary objectives of .NET Aspire is to ensure that apps are straightforward to debug and diagnose. .NET Aspire integrations automatically set up Logging, Tracing, and Metrics configurations, which are sometimes known as the pillars of observability, using the .NET OpenTelemetry SDK.
Logging: Log events describe what's happening as an app runs. A baseline set is enabled for .NET Aspire integrations by default and more extensive logging can be enabled on-demand to diagnose particular problems.
Tracing: Traces correlate log events that are part of the same logical activity (e.g. the handling of a single request), even if they're spread across multiple machines or processes.
Metrics: Metrics expose the performance and health characteristics of an app as simple numerical values. As a result, they have low performance overhead and many services configure them as always-on telemetry. This also makes them suitable for triggering alerts when potential problems are detected.
Together, these types of telemetry allow you to gain insights into your application's behavior and performance using various monitoring and analysis tools. Depending on the backing service, some integrations may only support some of these features.
The .NET OpenTelemetry SDK includes features for gathering data from several .NET APIs, including ILogger, Activity, Meter, and Instrument<T>. These APIs correspond to telemetry features like logging, tracing, and metrics. .NET Aspire projects define OpenTelemetry SDK configurations in the ServiceDefaults project. For more information, see .NET Aspire service defaults.
By default, the ConfigureOpenTelemetry
method enables logging, tracing, and metrics for the app. It also adds exporters for these data points so they can be collected by other monitoring tools.
The .NET OpenTelemetry SDK facilitates the export of this telemetry data to a data store or reporting tool. The telemetry export mechanism relies on the OpenTelemetry protocol (OTLP), which serves as a standardized approach for transmitting telemetry data through REST or gRPC. The ConfigureOpenTelemetry
method also registers exporters to provide your telemetry data to other monitoring tools, such as Prometheus or Azure Monitor. For more information, see OpenTelemetry configuration.
OpenTelemetry has a list of known environment variables that configure the most important behavior for collecting and exporting telemetry. OpenTelemetry SDKs, including the .NET SDK, support reading these variables.
.NET Aspire projects launch with environment variables that configure the name and ID of the app in exported telemetry and set the address endpoint of the OTLP server to export data. For example:
OTEL_SERVICE_NAME
= myfrontendOTEL_RESOURCE_ATTRIBUTES
= service.instance.id=1a5f9c1e-e5ba-451b-95ee-ced1ee89c168OTEL_EXPORTER_OTLP_ENDPOINT
= http://localhost:4318
The environment variables are automatically set in local development.
When you create a .NET Aspire project, the .NET Aspire dashboard provides a UI for viewing app telemetry by default. Telemetry data is sent to the dashboard using OTLP, and the dashboard implements an OTLP server to receive telemetry data and store it in memory. The .NET Aspire debugging workflow is as follows:
OTEL_SERVICE_NAME
) and ID (OTEL_RESOURCE_ATTRIBUTES
) of the app in exported telemetry.OTEL_EXPORTER_OTLP_ENDPOINT
environment variable on each project. That tells projects to export telemetry back to the dashboard.OTEL_BSP_SCHEDULE_DELAY
, OTEL_BLRP_SCHEDULE_DELAY
, OTEL_METRIC_EXPORT_INTERVAL
) so data is quickly available in the dashboard. Small values are used in local development to prioritize dashboard responsiveness over efficiency.All of these steps happen internally, so in most cases the developer simply needs to run the app to see this process in action.
.NET Aspire deployment environments should configure OpenTelemetry environment variables that make sense for their environment. For example, OTEL_EXPORTER_OTLP_ENDPOINT
should be configured to the environment's local OTLP collector or monitoring service.
.NET Aspire telemetry works best in environments that support OTLP. OTLP exporting is disabled if OTEL_EXPORTER_OTLP_ENDPOINT
isn't configured.
For more information, see .NET Aspire deployments.
.NET Aspire feedback
.NET Aspire is an open source project. Select a link to provide feedback:
Training
Module
Use telemetry in a .NET Aspire project - Training
In this module, you'll learn about using telemetry to record the behavior of a cloud-native application and how the .NET Aspire stack makes it easier store data and view it later.