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();