---
title: "Aspirations - Embracing OpenTelemetry"
description: "Integrating OpenTelemetry with Aspire"
canonical_url: "https://techwatching.dev/posts/aspire-open-telemetry"
---

> Index of every page on this site: [llms.txt](https://techwatching.dev/llms.txt)

In my previous [Aspire blog post](https://techwatching.dev/posts/aspire-tailor-to-your-stack), we talked about using Aspire to orchestrate the different parts of our web application. However, the Aspire dashboard did not show any telemetry (traces, metrics, or structured logging) because we did not instrument the API or front-end code. We are going to change that in this article, and see how we can easily integrate [OpenTelemetry](https://opentelemetry.io/) into our [application](https://github.com/TechWatching/AspnetWithNuxt).

## Observability with the Aspire Dashboard

When your application is deployed in a production environment, you are likely using observability platforms like Jaeger, Prometheus, New Relic, Honeycomb, Datadog, Azure Monitor, or other vendors that support OpenTelemetry. But you probably don’t have any of these tools in your local development environment. The Aspire dashboard is designed to provide built-in support for observability when debugging your application locally. This allows you to better understand how your application behaves in your development environment, detect potential performance issues, and investigate any problems.

To achieve that, the [Aspire dashboard implements an OpenTelemetry Protocol (OTLP) server](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/telemetry#net-aspire-local-development?wt.mc_id=MVP_430820). It provides OTLP endpoints for applications to send telemetry data, and includes pages to visualize the received data.

That's great, but if we want to see telemetry from our web application, we first need to set up the instrumentation. To demonstrate this, we will use our [existing web application](https://github.com/TechWatching/AspnetWithNuxt/tree/f13278296bf3989af53d8560a5c4eae4862a1bea), which consists of a Nuxt.js front end called `WebApp` and an ASP.NET Core API called `WebApi`, and instrument both parts.

## Add the instrumentation code to the `WebApi`

The [OpenTelemetry SDK for .NET](https://github.com/open-telemetry/opentelemetry-dotnet) includes everything we need to collect the telemetry data (logs, traces, metrics). So we could directly install the nuget packages in the `WebApi` project, and implement the code to configure the instrumentation and use the Aspire dashboard OTLP endpoint. It would work, and if you already have an app using OpenTelemetry, you likely only need to make a few configuration changes to make it compatible with the Aspire dashboard.

In our case, we will use instead an [Aspire service defaults project](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/service-defaults?wt.mc_id=MVP_430820) to set everything up easily. The purpose of using this Aspire Shared project is to offer predefined extension methods that help configure things like OpenTelemetry, health check endpoints, retry policies, and more across the various services and resources that make up the application. Let’s create this project using the `aspire-servicedefaults` template (from the [Aspire template](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/aspire-sdk-templates?pivots=dotnet-cli&wt.mc_id=MVP_430820)) and reference it in the `WebApi` project.

```bash
dotnet new aspire-servicedefaults -o ServiceDefaults
dotnet sln AspnetWithNuxt.slnx add ServiceDefaults\ServiceDefaults.csproj
dotnet add .\WebApi\WebApi.csproj reference .\ServiceDefaults\ServiceDefaults.csproj
```

We can see the `ServiceDefaults` project contains references to the necessary OpenTelemetry nuget packages and other packages for resilience and service discovery:

```xml [ServiceDefaults.csproj]
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireSharedProject>true</IsAspireSharedProject>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="9.0.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.9.0" />
  </ItemGroup>

</Project>
```

```csharp [ServiceDefaults/Extensions.cs]
public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
    {
        builder.Logging.AddOpenTelemetry(logging =>
        {
            logging.IncludeFormattedMessage = true;
            logging.IncludeScopes = true;
        });

        builder.Services.AddOpenTelemetry()
            .WithMetrics(metrics =>
            {
                metrics.AddAspNetCoreInstrumentation()
                    .AddHttpClientInstrumentation()
                    .AddRuntimeInstrumentation();
            })
            .WithTracing(tracing =>
            {
                tracing.AddSource(builder.Environment.ApplicationName)
                    .AddAspNetCoreInstrumentation()
                    // Uncomment the following line to enable gRPC instrumentation (requires the OpenTelemetry.Instrumentation.GrpcNetClient package)
                    //.AddGrpcClientInstrumentation()
                    .AddHttpClientInstrumentation();
            });

        builder.AddOpenTelemetryExporters();

        return builder;
    }
```

If we want to customize something in this instrumentation code, we can directly modify this code. Here, we will let everything like that and just call this method in our `WebApi` project.

```csharp [WebApi/Program.cs]
var builder = WebApplication.CreateBuilder(args);

builder.ConfigureOpenTelemetry();
```

<callout icon="i-heroicons-light-bulb">

Please note that this method only configures OpenTelemetry. To benefit from service discovery, resilience, and health checks, there are other methods you should call. However, the simplest way is to call `builder.AddServiceDefaults`, which configures everything directly.

</callout>

![OpenTelemetry environment variables in the Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_1.png)

Since Aspire automatically provides the needed OpenTelemetry environment variables to the various resources it manages, the code we added in the `WebApi` will correctly export the traces, metrics, and logs to the dashboard, where they will be displayed.

![Logs of the WebApi in the Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_2.png)

![Traces of the WebApi in the Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_3.png)

![Metrics of the WebApi in the Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_4.png)

If we had other .NET resources (such as other APIs, services, or a Blazor front end), we could configure them just as easily by calling the same methods from `ServiceDefaults`. However, for a browser application, it's not as straightforward.

## Add the instrumentation code to the `WebApp`

There are several challenges when it comes to instrumenting applications running in the browser:

- Browser apps don’t support gRPC, so they can't use the gRPC OTLP endpoint.
- At the time of writing, the OpenTelemetry JavaScript SDK’s documentation states that:

  - The client instrumentation for the browser is still experimental and mostly unspecified.
  - Only the traces and metrics signals are stable; the logs signal is still in development.
- OTEL environment variables need to be made available to the browser app

The first point can be handled easily by replacing the environment variable `DOTNET_DASHBOARD_OTLP_ENDPOINT_URL` by the environment variable `DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL` in the `launchsettings.json` file the `AppHost`. It will enable the [OTLP HTTP endpoint](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/enable-browser-telemetry?tabs=bash#otlp-configuration&&wt.mc_id=MVP_430820).

```json [AppHost/Properties/launchSettings.json]
"DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "https://localhost:16175",
```

![HTTP OTEL endpoint environment variable in the Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_5.png)

For the second point, there isn't much we can do. However, even though client instrumentation in the browser is still experimental, the OpenTelemetry JavaScript SDK works well and there are resources to help you set it up:

- Examples in the [OpenTelemetry documentation](https://opentelemetry.io/docs/languages/js/getting-started/browser/)
- This tutorial in the [Microsoft documentation](https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/dashboard/enable-browser-telemetry?wt.mc_id=MVP_430820)
- This great video from [Aaron Powell](https://youtu.be/9Cn5WDvmWtg?si=paVc4ynRnXzHjG6I)
- Some code samples on GitHub like this [one](https://github.com/aaronpowell/aspire-azure-dev-day-js-talk/blob/main/src/bookstore-web/src/instrumentation.ts) or this [one](https://github.com/robrich/net-aspire/blob/main/01-full/vue-app/src/tracing.ts)

Anyway, for the moment we won’t be able to see in the dashboard structured logs coming from the `WebApp`. However, what matters more to me than logs or even metrics are traces and the ability to correlate traces from both the `WebApp` and the `WebApi`. Without that, it’s hard to link events happening in the frontend with those in the backend.

I won’t explain everything we need to do to add the instrumentation code to our Nuxt.js application `WebApp` because I already did it in this [blog post](https://techwatching.dev/posts/aspire-otel). What I did is I implemented an OpenTelemetry plugin for Nuxt.js that export the application traces to an OTEL backend. You can grab the code [here](https://github.com/TechWatching/AspnetWithNuxt/blob/f13278296bf3989af53d8560a5c4eae4862a1bea/WebApp/app/plugins/instrumentation.ts) but I suggest you to read the [article](https://techwatching.dev/posts/aspire-otel) to understand how this code is using the OpenTelemetry SDKs.

Starting from this code, we now just have to make it work with the Aspire dashboard as the OTEL backend. That’s the third, to provide the OTEL environment variables that the browser application will use.

In the `WebApp`, we have some OpenTelemetry configuration that the plugin uses to process and export the telemetry data:

```typescript [nuxt.config.ts]
runtimeConfig: {
    public: {
      otelExporterOtlpEndpoint: '',
      otelExporterOtlpHeaders: '',
      otelResourceAttributes: '',
      otelServiceName: '',
    }
  }
```

To override this configuration at runtime ([you don’t want to set them in your code because you would only override them at build time](https://www.youtube.com/watch?v=_FYV5WfiWvs)), we would need to set these environment variables:

- `NUXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT`
- `NUXT_PUBLIC_OTEL_RESOURCE_ATTRIBUTES`
- `NUXT_PUBLIC_OTEL_EXPORTER_OTLP_HEADERS`
- `NUXT_PUBLIC_OTEL_SERVICE_NAME`

Those are the same environment variables that Aspire provides to the `WebApp` but prefixed with `NUXT_PUBLIC`. Fortunately, someone with the same problem but for Vite created [an issue on the Aspire repository](https://github.com/dotnet/aspire/issues/1898) and David Fowler suggested the following code to automatically add a prefix:

```csharp [AppHost/EnvironmentExtensions.cs]
namespace AppHost;

public static class EnvironmentExtensions
{
    public static IResourceBuilder<T> WithEnvironmentPrefix<T>(this IResourceBuilder<T> resourceBuilder, string prefix)
        where T : IResourceWithEnvironment
    {
        return resourceBuilder.WithEnvironment(context =>
        {
            var kvps = context.EnvironmentVariables.ToArray();

            // Adds a prefix to all environment variable names
            foreach (var p in kvps)
            {
                context.EnvironmentVariables[$"{prefix}{p.Key}"] = p.Value;
            }
        });
    }
}
```

This is useful for OpenTelemetry but could be useful for other environment variables as well so I did not add filters. To make it work we just have to call the method `WithEnvironmentPrefix` when defining our `WebApp` resource in the `AppHost`.

```csharp [AppHost/Program.cs]
var webApp= builder.AddPnpmApp("WebApp", "../WebApp", "dev")
    .WithHttpsEndpoint(env: "PORT")
    .WithExternalHttpEndpoints()
    .WithPnpmPackageInstallation()
    .WithReference(webApi)
    .WaitFor(webApi)
    .WithEnvironment("ApiUrl", webApi.GetEndpoint("https"))
    .WithEnvironmentPrefix("NUXT_PUBLIC_");
```

We can check that we now have the environment variables twice (with prefix and without) so that Aspire correctly provides the OTEL configuration in the `WebApp`.

![Environment variables twice in Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_6.png)

And with just that, we can now see both the traces from the `WebApi` and the `WebApp` in the dashboard.

![Traces of the WebApi and WebApp in the Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_7.png)

![Details of a trace in the Aspire dashboard.](https://techwatching.dev/posts/images/71.aspire-otel_8.png)

<callout icon="i-heroicons-light-bulb">

Please note that traces are correlated when using client side rendering (like on the screenshot above), but not when using server side rendering. There is probably an additional thing to configure in the Nuxt instrumentation.

</callout>

## Final thoughts

Thanks to the Aspire dashboard, we can easily view telemetry data from different parts of the application locally. Additionally, with the `ServiceDefaults` project, integrating OpenTelemetry with .NET applications is straightforward. Although adding instrumentation to browser applications can be challenging and requires some extra work, it is still possible and improves the overall observability of the application.

Not only does Aspire improve the local development experience by bringing observability to where you code, but it also encourages you to implement things correctly by default. Without Aspire, I probably wouldn't have delved into the subject of OpenTelemetry and kept using vendor specific SDKs.

You can find the complete code [here](https://github.com/TechWatching/AspnetWithNuxt/tree/254a27e60849f9ecfb759bf4f29c8b9307cbfb2e). Keep learning.

## Sitemap

See the full [sitemap](https://techwatching.dev/sitemap.md) for all pages.
