Osservabilità LLM in .NET: tracce, token e costi con OpenTelemetry e la dashboard Aspire

span name       chat llama3.2:3b
duration        2.41s

gen_ai.operation.name        chat
gen_ai.provider.name         ollama
gen_ai.request.model         llama3.2:3b
gen_ai.response.model        llama3.2:3b
gen_ai.usage.input_tokens    412
gen_ai.usage.output_tokens   128

# aggiunto dal middleware che mi scrivo più avanti
llmobs.usage.cost_usd        0.000139

services:
  ollama:
    image: ollama/ollama:latest
    ports: ["11434:11434"]
    volumes: [ollama-data:/root/.ollama]
    healthcheck:
      test: ["CMD-SHELL", "ollama list >/dev/null 2>&1 || exit 1"]
      interval: 10s
      retries: 12
      start_period: 20s

  # one-shot: scarica il modello appena Ollama è sano, poi esce
  ollama-init:
    image: ollama/ollama:latest
    depends_on:
      ollama:
        condition: service_healthy
    environment:
      OLLAMA_HOST: http://ollama:11434
    entrypoint: ["/bin/sh", "-c", "ollama pull ${OLLAMA_MODEL:-llama3.2:3b}"]
    restart: "no"

  aspire-dashboard:
    image: mcr.microsoft.com/dotnet/aspire-dashboard:9.0
    ports:
      - "18888:18888"   # UI
      - "4317:18889"    # OTLP/gRPC
    environment:
      DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS: "true"
      ASPNETCORE_URLS: http://+:18888

volumes:
  ollama-data:

dotnet add package Microsoft.Extensions.AI
dotnet add package OllamaSharp

dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http
dotnet add package OpenTelemetry.Instrumentation.Runtime

namespace LlmObservability.Api.Observability;

// Unica fonte di verità per i nomi emessi dall'app: è ciò che tiene
// allineati UseOpenTelemetry() e AddSource()/AddMeter().
public static class TelemetryNames
{
    // ActivitySource + Meter passati esplicitamente a UseOpenTelemetry().
    public const string ChatSource = "LlmObservability.Ai";

    // Meter del middleware di costo (custom, fuori dalle semantic conventions).
    public const string CostMeter = "LlmObservability.Cost";

    // ActivitySource dell'app per gli span aperti a mano.
    public const string AppSource = "LlmObservability.Api";

    // Nome usato da Microsoft.Extensions.AI quando non passi sourceName.
    public const string LibraryDefaultSource = "Experimental.Microsoft.Extensions.AI";
}

// Registra l'intero stack OpenTelemetry più gli oggetti che serve
// alla pipeline AI (listino prezzi, calcolatore, Meter del costo).
public static IHostApplicationBuilder AddLlmObservability(this IHostApplicationBuilder builder)
{
    // 1) Listino e calcolatore, condivisi con il middleware di costo.
    builder.Services.Configure<PricingOptions>(builder.Configuration.GetSection(PricingOptions.SectionName));
    builder.Services.AddSingleton(sp =>
        new CostCalculator(sp.GetRequiredService<IOptions<PricingOptions>>().Value));

    // 2) Il Meter che porta il contatore custom: singleton, nome stabile.
    builder.Services.AddSingleton(_ => new Meter(TelemetryNames.CostMeter));

    // 3) Chi sta emettendo: service.name è il campo su cui raggruppa tutto.
    var serviceName = builder.Configuration["Otel:ServiceName"] ?? "llm-observability-api";
    var otlpEndpoint = builder.Configuration["Otel:Endpoint"] ?? "http://localhost:4317";

    builder.Services.AddOpenTelemetry()
        .ConfigureResource(r => r.AddService(serviceName))
        .WithTracing(tracing => tracing
            .AddAspNetCoreInstrumentation()   // span radice HTTP
            .AddHttpClientInstrumentation()   // la chiamata vera a Ollama
            .AddSource(TelemetryNames.ChatSource)
            .AddSource(TelemetryNames.LibraryDefaultSource)
            .AddSource(TelemetryNames.AppSource)
            .AddOtlpExporter(o => o.Endpoint = new Uri(otlpEndpoint)))
        .WithMetrics(metrics => metrics
            .AddAspNetCoreInstrumentation()
            .AddHttpClientInstrumentation()
            .AddRuntimeInstrumentation()
            .AddMeter(TelemetryNames.ChatSource)          // istogrammi token/durata
            .AddMeter(TelemetryNames.LibraryDefaultSource)
            .AddMeter(TelemetryNames.CostMeter)           // il contatore di costo
            .AddOtlpExporter(o => o.Endpoint = new Uri(otlpEndpoint)));

    // 4) Log sullo stesso canale: warning e span correlati per trace id.
    builder.Logging.AddOpenTelemetry(logging =>
    {
        logging.IncludeFormattedMessage = true;
        logging.IncludeScopes = true;
        logging.AddOtlpExporter(o => o.Endpoint = new Uri(otlpEndpoint));
    });

    return builder;
}

// ChatClientBuilder avvolge in ordine inverso: il PRIMO stadio registrato
// è il PIÙ ESTERNO. OpenTelemetry misura quindi l'intera chiamata,
// giri di tool compresi, e lo stadio di costo gira dentro il suo span.
public static IHostApplicationBuilder AddInstrumentedChatClient(this IHostApplicationBuilder builder)
{
    builder.Services.Configure<OllamaOptions>(builder.Configuration.GetSection(OllamaOptions.SectionName));

    // Prompt e risposte sugli span: oro in sviluppo, incidente GDPR in produzione.
    var enableSensitiveData = builder.Configuration.GetValue("Otel:EnableSensitiveData", false);

    builder.Services.AddChatClient(sp =>
    {
        var options = sp.GetRequiredService<IOptions<OllamaOptions>>().Value;
        return new OllamaApiClient(new Uri(options.Endpoint), options.Model);
    })
        // Più esterno: span e istogrammi coprono tutto quello che sta sotto.
        .UseOpenTelemetry(
            sourceName: TelemetryNames.ChatSource,
            configure: c => c.EnableSensitiveData = enableSensitiveData)
        // Poi il costo, così i suoi tag atterrano sullo span aperto sopra.
        .Use((inner, sp) => new CostTrackingChatClient(
            inner,
            sp.GetRequiredService<CostCalculator>(),
            sp.GetRequiredService<Meter>(),
            sp.GetRequiredService<ILogger<CostTrackingChatClient>>()))
        // Più interno: il ciclo dei tool resta dentro lo span.
        .UseFunctionInvocation();

    return builder;
}

// Stadio che trasforma i token dichiarati dal modello in denaro. Sta DENTRO
// UseOpenTelemetry(), quindi i tag finiscono sullo span gen_ai già aperto.
public sealed class CostTrackingChatClient : DelegatingChatClient
{
    private const string CostAttribute = "llmobs.usage.cost_usd";

    // Chiamata bloccante: delega e poi prezza l'uso che è tornato.
    public override async Task<ChatResponse> GetResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        var response = await base.GetResponseAsync(messages, options, cancellationToken);
        Record(response.ModelId, response.Usage);
        return response;
    }

    // In streaming l'uso arriva come UsageContent negli update: accumulo
    // e prezzo una volta sola alla fine dello stream.
    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        var totals = new UsageDetails();
        string? modelId = null;

        await foreach (var update in base.GetStreamingResponseAsync(messages, options, cancellationToken))
        {
            modelId ??= update.ModelId;
            var usages = update.Contents.OfType<UsageContent>().Select(c => c.Details);
            usages.ToList().ForEach(totals.Add);
            yield return update;
        }

        Record(modelId, totals);
    }

    // Calcola il costo, lo registra sul contatore e lo scrive sullo span.
    private void Record(string? modelId, UsageDetails? usage)
    {
        // 1) Guardia: alcuni provider non riportano l'uso — niente da prezzare.
        if (usage is null)
            return;

        var model = modelId ?? "unknown";
        var input = usage.InputTokenCount ?? 0;
        var output = usage.OutputTokenCount ?? 0;

        // 2) Quale listino valorizza questi token (shadow pricing).
        var billingModel = _calculator.ResolveBillingModel(model);
        var cost = _calculator.Estimate(billingModel, input, output);

        // 3) Un grafico piatto a zero è quasi sempre un errore di configurazione.
        if (cost == 0m && (input > 0 || output > 0))
            _logger.LogWarning("Nessun listino per il modello {BillingModel}: costo riportato a 0.", billingModel);

        // 4) Contatore con i tag su cui raggrupperai nella dashboard.
        _costCounter.Add((double)cost,
            new KeyValuePair<string, object?>("gen_ai.request.model", model),
            new KeyValuePair<string, object?>("llmobs.billing.model", billingModel));

        // 5) Stesso numero sullo span: una richiesta lenta dice anche quanto è costata.
        Activity.Current?.SetTag(CostAttribute, (double)cost);
    }
}

// Trasforma un conteggio di token in una stima monetaria usando il listino.
// Puro e senza dipendenze: è il pezzo che vale la pena testare.
public sealed class CostCalculator(PricingOptions pricing)
{
    // Modello il cui listino valorizza i token: quello configurato se c'è
    // (shadow pricing), altrimenti quello che ha risposto.
    public string ResolveBillingModel(string responseModel)
    {
        if (!string.IsNullOrWhiteSpace(pricing.BillingModel))
            return pricing.BillingModel;
        return responseModel;
    }

    // Costo in USD di una coppia input/output per il modello indicato.
    // Zero se il modello non è a listino: tipico di un modello locale.
    public decimal Estimate(string model, long inputTokens, long outputTokens)
    {
        // 1) Guardia: modello sconosciuto, nessun prezzo da applicare.
        if (!pricing.Models.TryGetValue(model, out var price))
            return 0m;

        // 2) I prezzi sono per milione di token: scalo entrambi i lati.
        var input = inputTokens / 1_000_000m * price.InputPerMillionUsd;
        var output = outputTokens / 1_000_000m * price.OutputPerMillionUsd;
        return input + output;
    }
}

// Chiamata bloccante: risponde con i numeri che finiscono anche in dashboard,
// più il trace id con cui ritrovare la richiesta.
private static async Task<IResult> HandleChatAsync(
    ChatRequest request,
    IChatClient chatClient,
    CostCalculator calculator,
    IOptions<PricingOptions> pricing,
    CancellationToken cancellationToken)
{
    // 1) Guardia: un prompt vuoto è un bug del client, non del modello.
    if (string.IsNullOrWhiteSpace(request.Prompt))
        return TypedResults.BadRequest(new ErrorResponse("Prompt must not be empty."));

    // 2) Interrogo il modello: tool e telemetria li gestisce la pipeline.
    var messages = BuildMessages(request.Prompt);
    var response = await chatClient.GetResponseAsync(
        messages,
        new ChatOptions { Tools = SupportTools.BuildTools() },
        cancellationToken);

    // 3) Ricalcolo lo stesso costo registrato dal middleware, per esporlo.
    var model = response.ModelId ?? "unknown";
    var input = response.Usage?.InputTokenCount ?? 0;
    var output = response.Usage?.OutputTokenCount ?? 0;
    var cost = calculator.Estimate(calculator.ResolveBillingModel(model), input, output);

    return TypedResults.Ok(new ChatReply(
        response.Text,
        model,
        input,
        output,
        cost,
        Activity.Current?.TraceId.ToString() ?? string.Empty));
}

curl -s http://localhost:5173/chat \
  -H 'content-type: application/json' \
  -d '{"prompt":"Qual è lo stato dell ordine A-1001?"}'

{
  "text": "Lo stato dell'ordine A-1001 è spedito, consegna prevista il 12 agosto 2026 con BRT.",
  "model": "llama3.2:3b",
  "inputTokens": 383,
  "outputTokens": 75,
  "estimatedCostUsd": 0.00010245,
  "traceId": "d6b5f062116d0af3fc41d7ac617dc81a"
}

{
  "Ollama": {
    "Endpoint": "http://localhost:11434",
    "Model": "llama3.2:3b"
  },
  "Otel": {
    "ServiceName": "llm-observability-api",
    "Endpoint": "http://localhost:4317",
    "EnableSensitiveData": true
  },
  "Pricing": {
    "BillingModel": "gpt-4o-mini",
    "Models": {
      "gpt-4o-mini": { "InputPerMillionUsd": 0.15, "OutputPerMillionUsd": 0.60 }
    }
  }
}

[Fact]
public async Task Pipeline_EmitsAGenAiSpanOnTheConfiguredSource()
{
    // 1) Ascolto solo il nome che l'app registra con AddSource().
    var captured = new List<Activity>();
    using var listener = new ActivityListener
    {
        ShouldListenTo = source => source.Name == TelemetryNames.ChatSource,
        Sample = (ref ActivityCreationOptions<ActivityContext> _) => ActivitySamplingResult.AllDataAndRecorded,
        ActivityStopped = captured.Add,
    };
    ActivitySource.AddActivityListener(listener);

    // 2) Una chiamata attraverso la pipeline, su un provider finto.
    var (client, meter) = BuildPipeline(billingModel: "gpt-4o-mini");
    using var _ = meter;
    await client.GetResponseAsync("ciao");

    // 3) Lo span deve esistere e portare gli attributi delle semantic conventions.
    var span = Assert.Single(captured);
    Assert.Contains("gen_ai.usage.input_tokens", span.TagObjects.Select(t => t.Key));
    Assert.Contains("gen_ai.usage.output_tokens", span.TagObjects.Select(t => t.Key));

    // 4) …e il tag del mio middleware: prova che il costo gira DENTRO lo span.
    Assert.Contains("llmobs.usage.cost_usd", span.TagObjects.Select(t => t.Key));
}

git clone https://github.com/fscamuzzi/llm-observability-dotnet-opentelemetry
cd llm-observability-dotnet-opentelemetry

docker compose up -d
docker compose logs -f ollama-init   # aspetta il 'success'

dotnet test
dotnet run --project src/LlmObservability.Api