Provide documentation for Instrumentation / OpenTelemetry

[ascott18]

Description

I cannot find any official documentation about adding OTel to a MAUI app.

The general docs are very sparse in information about adding OTel to a client app. Most of the examples are about server apps and it is very easy to fall into the major pitfall of using builder.Services.AddOpenTelemetry() in a MAUI app, which doesn't work because of #2244.

Public API Changes

N/A: docs request

Intended Use-Case

Collecting traces and metrics from client applications in order to diagnose problems

[BretJohnson]

@ascott18 - We're doing some work around this now, to help support Aspire integration. Just for our understanding, can you say more about your use case: Is this for developer machine scenarios (like Aspire) or for production scenarios (end users using apps) or both? Who will consume the Open Telemetry, in your use cases? App Insights? Something else? Thanks.

[moljac]

@ascott18 I managed to add ConsoleExporter, but not yet managed to send it to backend

MAUI does not utilize Microsoft.Extensions.* like ASP.net does, because of startup performance which is not THAT critical for web apps, but we are working on it.

I have samples where I added OpenTelemerty to console apps and integrated it with Aspire. MAUI kinda works too, but it needs more a lot more love.

But there is no docs. Yet

[ascott18]

@BretJohnson The main use case I have currently is for production, but having it locally can be useful too. Trying to export data to App Insights.

I've come up with the following so far, but it doesn't work very well. None of my resource attributes pass through to App Insights because the AI exporter appears to have a very limited set of attributes that can be exported to AI and they're all hardcoded.

  <PropertyGroup>
    <!-- Send trace headers through HTTP requests https://github.com/dotnet/runtime/issues/83227 -->
    <HttpActivityPropagationSupport>true</HttpActivityPropagationSupport>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.7.0" />
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.7.0" />
    <PackageReference Include="Azure.Monitor.OpenTelemetry.Exporter" Version="1.2.0" />
  </ItemGroup>

void ConfigureOtel(AzureMonitorExporterOptions opts)
{
    builder.Configuration.GetSection("AzureMonitor").Bind(opts);
}

var resource = ResourceBuilder.CreateDefault()
    .AddService(
        Process.GetCurrentProcess().ProcessName,
        serviceVersion: new MauiAppVersionProvider().GetAppVersionAndBuild(),
        autoGenerateServiceInstanceId: false
    )
    .AddAttributes(new Dictionary<string, object>
    {
        // None of these attributes do anything. App insights won't pass them through.
        ["device.model.name"] = DeviceInfo.Current.Model,
        ["device.manufacturer"] = DeviceInfo.Current.Manufacturer,
        ["os.name"] = DeviceInfo.Current.Platform.ToString(),
        ["os.type"] = 
            DeviceInfo.Current.Platform == DevicePlatform.Android ? "linux" :
            DeviceInfo.Current.Platform == DevicePlatform.iOS ? "darwin" :
            "",
        ["os.version"] = DeviceInfo.Current.VersionString,

        // This is an attempt to get app insights to classify our mobile app as browser instead of a server.
        // However, it doesn't work at all. The AI exporter won't pass the tag through.
        ["ai.device.type"] = "Browser",

#if ANDROID
        ["android.os.api_level"] = (int)Android.OS.Build.VERSION.SdkInt,
#endif
    });

builder.Logging
    // Suppress HttpClient logs that are redundant with OTel traces/spans.
    .AddFilter<OpenTelemetryLoggerProvider>("System.Net.Http.HttpClient", LogLevel.Warning)
    .AddOpenTelemetry(otel =>
    {
        otel.AddAzureMonitorLogExporter(ConfigureOtel);
        otel.SetResourceBuilder(resource);
        otel.IncludeFormattedMessage = true;
        otel.IncludeScopes = true;
    });

OpenTelemetry.Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resource)
    .AddHttpClientInstrumentation()
    .AddAzureMonitorTraceExporter(ConfigureOtel)
#if DEBUG
    .AddConsoleExporter(c => c.Targets = OpenTelemetry.Exporter.ConsoleExporterOutputTargets.Debug)
#endif
    .Build();

[rhythmnewt]

@ascott18 Have you had any luck with your approach? I'm currently researching doing the same thing.

[ascott18]

Nope, it still is pretty bad. You're probably best off not using app insights at all and using some other platform that actually supports OTel.

[rhythmnewt]

Thank you for your response, it's really appreciated.

[gabsamples6]

What about this approach -
`Create a .net 8 min api that u host in azure for example that exposes a log method as a post .
In here u do all the telemetry stuff and from the app you just call this web api. Am I missing the obvious? This way u don’t have a nuget or dependency either and just delegate responsibility to the api that has proper integration with any logging framework u like.

[ascott18]

Yes, I'm afraid you've missed the point. The principal issue here isn't sending of the data that's been collected. That's easy. The hard part is collecting it in the first place. This issue is specifically around the lack of documentation on how to do that. Telemetry and tracing is much more that just "a log method".

The sending of data is only a secondary issue because App Insights doesn't support OTel payloads. Putting an intermediary server in the middle doesn't solve this problem - it just adds a middleman. We could construct App Insights payloads directly in the MAUI app, but that's a level of work that just isn't worth it, and adding a middleman server would only shift that problem to a different part of the infrastructure.

[gabsamples6]

@ascott18 I get it now. I misunderstood the issue , hence the suggestion to delegate to a web api.. Documentation and responses from MS , is very tricky issues these days , as we have same problem and lack of documenation on the azure notification hub and maui implementaion.. thanks for clarifying

[peruchali]

Is there a sample anyone can share? How do I integrate OpenTelemetry into my MAUI app (Android)?

[rokmeglic71]

@ascott18 maybe things will get better?

[peruchali]

@rokmeglic71 Could you elaborate? I'm new to OpenTelemetry and would like to see how to integrate it with MAUI.

[rokmeglic71]

@peruchali we are on the same boat, I am new too. If you open the link above, you will see there is some text about

We've added comprehensive diagnostics and metrics tracking for .NET MAUI applications.

[MerSpyro]

I'm actually curious how @mattleibow managed to setup MAUI app with .Aspire for #31058 .
Maybe we will get some insights from him? :D

The app used for the PR's screen shots would be amazing IMO

[mattleibow]

@jfversluis has a template. But I think in net10 you can right click and add aspire. Just like Web apps.

[jfversluis]

A current sample project can be found on https://github.com/jfversluis/MauiAspire. But working hard to make things better and more integrated with .NET 10!

[MerSpyro]

@jfversluis @mattleibow Thank you very much!