Telemetry

One of the primary objectives of Aspire is to ensure that apps are straightforward to debug and diagnose. Aspire integrations automatically set up logging, tracing, and metrics configurations—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 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 (for example, 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.

Aspire projects define OpenTelemetry SDK configurations in the service defaults project. 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.

Aspire enables export of 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 registers exporters to provide your telemetry data to other monitoring tools, such as Prometheus or Azure Monitor.

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.

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=myfrontend
• OTEL_RESOURCE_ATTRIBUTES=service.instance.id=1a5f9c1e-e5ba-451b-95ee-ced1ee89c168
• OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

These environment variables are automatically set in local development.

When you create an Aspire project, the 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.

When you start an Aspire project with debugging (pressing ), the following workflow occurs:

1. Dashboard and DCP start — The Aspire dashboard and developer control plane (DCP) start
2. App configuration runs — The AppHost project runs its configuration:
   • OpenTelemetry environment variables are automatically added to .NET projects
   • DCP provides the service name (OTEL_SERVICE_NAME) and ID (OTEL_RESOURCE_ATTRIBUTES) for exported telemetry
   • The OTLP endpoint is an HTTP/2 port started by the dashboard, set in OTEL_EXPORTER_OTLP_ENDPOINT
   • Small export intervals (OTEL_BSP_SCHEDULE_DELAY, OTEL_BLRP_SCHEDULE_DELAY, OTEL_METRIC_EXPORT_INTERVAL) ensure data is quickly available in the dashboard
3. Resources start — The DCP starts configured projects, containers, and executables
4. Telemetry flows — Once started, apps send telemetry to the dashboard
5. Dashboard displays — The dashboard displays near real-time telemetry of all Aspire projects

All of these steps happen internally, so in most cases you simply need to run the app to see this process in action.

AI coding agents can access Aspire telemetry to diagnose issues, inspect app behavior, and monitor resources without requiring you to manually copy data from the dashboard. The Aspire CLI is built for agent-driven workflows—commands support non-interactive execution and --format Json for structured output that agents can parse.

When running an Aspire AppHost, agents use CLI commands like aspire otel logs, aspire otel traces, and aspire describe to fetch structured logs, distributed traces, and resource status directly from the dashboard. A typical agent workflow starts the app with aspire start, waits for resources with aspire wait, then queries telemetry to diagnose issues and verify fixes.

When using a standalone dashboard, agents pass --dashboard-url to point CLI commands at the dashboard instance and query telemetry from any application sending OTLP data.

The Aspire dashboard exposes APIs for both receiving and querying telemetry data. Applications write data to the dashboard using OTLP endpoints, and developers and tools read data back through multiple interfaces:

• Aspire CLI — The aspire otel logs, aspire otel traces, and aspire otel spans commands query telemetry directly from the terminal. Use --format Json for structured output suitable for scripting and automation.
• Export — The aspire export command packages telemetry and resource data into a zip file for offline analysis or sharing.
• MCP server — The Aspire MCP server exposes dashboard data to AI coding agents through Model Context Protocol tools.
• HTTP telemetry API — The dashboard exposes HTTP endpoints under /api/telemetry/ that return data in OTLP JSON format, supporting real-time streaming and resource filtering.

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.

• Service defaults
• Dashboard overview
• OpenTelemetry Protocol specification
• .NET OpenTelemetry SDK