Condividi tramite

Abilitare la telemetria del browser

  • Articolo

Il dashboard .NET.NET Aspire può essere configurato per ricevere i dati di telemetria inviati dalle app del browser. Questa funzionalità è utile per il monitoraggio delle prestazioni lato client e delle interazioni dell'utente. I dati di telemetria del browser richiedono un'ulteriore configurazione del dashboard e che l'SDK JavaScript OTEL venga aggiunto alle app del browser.

Questo articolo illustra come abilitare la telemetria del browser nel dashboard di .NET.NET Aspire.

Configurazione del dashboard

La telemetria del browser richiede che il dashboard abiliti queste funzionalità:

  • Endpoint HTTP OTLP. Questo endpoint viene usato dal dashboard per ricevere dati di telemetria dalle app del browser.
  • Condivisione di risorse tra le origini (CORS). CORS consente alle app del browser di effettuare richieste al dashboard.

Configurazione di OTLP

Il dashboard .NET.NET Aspire riceve i dati di telemetria tramite endpoint OTLP. endpoint HTTP OTLP e gli endpoint OTLP gRPC sono supportati dal dashboard. Le app per browser devono usare HTTP OLTP per inviare dati di telemetria al dashboard poiché le app per browser non supportano gRPC.

Per configurare gli endpoint gPRC o HTTP, specificare le variabili di ambiente seguenti:

  • DOTNET_DASHBOARD_OTLP_ENDPOINT_URL: endpoint gRPC a cui si connette il dashboard per i dati.
  • DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL: endpoint HTTP a cui si connette il dashboard per i dati.

La configurazione dell'endpoint HTTP OTLP dipende dal fatto che il dashboard venga avviato dall'host dell'app o sia eseguito autonomo.

Configurare HTTP OTLP con l'host dell'app

Se il dashboard e l'app vengono avviati dall'host dell'app, gli endpoint OTLP del dashboard vengono configurati nel file launchSettings.json dell'host dell'app.

Si consideri il seguente esempio di file JSON:

{
  "$schema": "http://json.schemastore.org/launchsettings.json",
  "profiles": {
    "https": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "https://localhost:15887;http://localhost:15888",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "https://localhost:16175",
        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "https://localhost:17037",
        "DOTNET_ASPIRE_SHOW_DASHBOARD_RESOURCES": "true"
      }
    },
    "http": {
      "commandName": "Project",
      "dotnetRunMessages": true,
      "launchBrowser": true,
      "applicationUrl": "http://localhost:15888",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development",
        "DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL": "http://localhost:16175",
        "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:17037",
        "DOTNET_ASPIRE_SHOW_DASHBOARD_RESOURCES": "true",
        "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true"
      }
    },
    "generate-manifest": {
      "commandName": "Project",
      "launchBrowser": true,
      "dotnetRunMessages": true,
      "commandLineArgs": "--publisher manifest --output-path aspire-manifest.json",
      "applicationUrl": "http://localhost:15888",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development",
        "DOTNET_ENVIRONMENT": "Development"
      }
    }
  }
}

Le impostazioni di avvio precedenti JSON file configurano tutti i profili in modo da includere la variabile di ambiente DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL.

Configurare OTLP HTTP con dashboard indipendente

Se il dashboard viene usato in modalità autonoma, senza il resto di .NET.NET Aspire, l'endpoint HTTP OTLP è abilitato per impostazione predefinita sulla porta 18890. Tuttavia, la porta deve essere mappata all'avvio del contenitore del dashboard:

docker run --rm -it -d \
    -p 18888:18888 \
    -p 4317:18889 \
    -p 4318:18890 \
    --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:9.0

Il comando precedente esegue il contenitore del dashboard e mappa gRPC OTLP alla porta 4317 e HTTP OTLP alla porta 4318.

Configurazione CORS

Per impostazione predefinita, le app browser non possono effettuare chiamate API tra domini. Ciò influisce sull'invio dei dati di telemetria al dashboard perché il dashboard e l'app del browser si trovano sempre in domini diversi. La configurazione di CORS nel dashboard .NET.NET Aspire rimuove la restrizione.

Se il dashboard e l'applicazione vengono avviati dall'host dell'applicazione, non è necessaria alcuna configurazione CORS. .NET .NET Aspire configura automaticamente il dashboard per consentire tutte le origini delle risorse.

Se il dashboard viene usato standlone, è necessario configurare CORS manualmente. Il dominio utilizzato per visualizzare l'app del browser deve essere configurato come origine consentita specificando la variabile d'ambiente DASHBOARD__OTLP__CORS__ALLOWEDORIGINS quando viene avviato il contenitore del dashboard.

docker run --rm -it -d \
    -p 18888:18888 \
    -p 4317:18889 \
    -p 4318:18890 \
    -e DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=https://localhost:8080 \
    --name aspire-dashboard \
    mcr.microsoft.com/dotnet/aspire-dashboard:9.0

Il comando precedente esegue il contenitore del dashboard e configura https://localhost:8080 come origine consentita. Ciò significa che un'applicazione del browser a cui si accede tramite https://localhost:8080 ha l'autorizzazione per inviare i dati di telemetria del dashboard.

È possibile consentire più origini con un valore delimitato da virgole. Oppure tutte le origini possono essere consentite con il carattere jolly *. Ad esempio, DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=*.

Per ulteriori informazioni, vedere la configurazione del dashboard: .NET.NET Aspire OTLP CORS.

Sicurezza degli endpoint OTLP

Gli endpoint OTLP del dashboard possono essere protetti con l'autenticazione con chiave API. Se abilitata, le richieste HTTP OTLP al dashboard devono includere la chiave API come intestazione x-otlp-api-key. Per impostazione predefinita, viene generata una nuova chiave API ogni volta che viene eseguito il dashboard.

L'autenticazione con chiave API viene abilitata automaticamente quando il dashboard viene eseguito dall'host dell'app. L'autenticazione del dashboard può essere disattivata configurando DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS a true nel file launchSettings.json dell'host dell'applicazione.

Gli endpoint OTLP, nel dashboard indipendente, non sono protetti per impostazione predefinita.

Configurazione dell'app browser

Un'app browser usa JAVAScript INTUNE SDK per inviare dati di telemetria al dashboard. Per inviare correttamente i dati di telemetria al dashboard, l'SDK deve essere configurato correttamente.

Esportazione OTLP

Gli esportatori OTLP devono essere inclusi nell'app browser e configurati con l'SDK. Ad esempio, l'esportazione del tracciamento distribuito con OTLP utilizza il pacchetto @opentelemetry/exporter-trace-otlp-proto.

Quando OTLP viene aggiunto all'SDK, è necessario specificare le opzioni OTLP. Le opzioni OTLP includono:

  • url: indirizzo a cui vengono effettuate richieste HTTP OTLP. L'indirizzo deve essere l'endpoint HTTP OTLP del dashboard e il percorso dell'API HTTP OTLP. Ad esempio, https://localhost:4318/v1/traces per l'esportatore di tracce OTLP. Se l'app del browser viene avviata dall'host dell'app, l'endpoint HTTP OTLP è disponibile dalla variabile di ambiente OTEL_EXPORTER_OTLP_ENDPOINT.

  • headers: le intestazioni inviate con le richieste. Se è abilitata l'autenticazione della chiave API dell'endpoint OTLP, bisogna inviare l'intestazione x-otlp-api-key con le richieste OTLP. Se l'app browser viene avviata dall'host dell'app, la chiave API è disponibile dalla variabile di ambiente OTEL_EXPORTER_OTLP_HEADERS.

Metadati del browser

Quando un'app browser è configurata per raccogliere tracce distribuite, l'app browser può impostare gli intervalli di traccia di un browser usando l'elemento meta nel codice HTML. Il valore dell'elemento meta name="traceparent" deve corrispondere alla traccia corrente.

In un'app .NET, ad esempio, il valore padre di traccia verrà probabilmente assegnato dal Activity.Current e passando il relativo valore Activity.Id come content. Si consideri ad esempio il codice Razor seguente:

<head>
    @if (Activity.Current is { } currentActivity)
    {
        <meta name="traceparent" content="@currentActivity.Id" />
    }
    <!-- Other elements omitted for brevity... -->
</head>

Il codice precedente assegna l'elemento meta traceparent all'ID dell'attività corrente.

Codice di telemetria del browser di esempio

Il codice JavaScript seguente illustra l'inizializzazione di OpenTelemetry JavaScript SDK e l'invio di dati di telemetria al dashboard:

import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { DocumentLoadInstrumentation } from '@opentelemetry/instrumentation-document-load';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
import { ZoneContextManager } from '@opentelemetry/context-zone';

export function initializeTelemetry(otlpUrl, headers, resourceAttributes) {
    const otlpOptions = {
        url: `${otlpUrl}/v1/traces`,
        headers: parseDelimitedValues(headers)
    };

    const attributes = parseDelimitedValues(resourceAttributes);
    attributes[SemanticResourceAttributes.SERVICE_NAME] = 'browser';

    const provider = new WebTracerProvider({
        resource: new Resource(attributes),
    });
    provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
    provider.addSpanProcessor(new SimpleSpanProcessor(new OTLPTraceExporter(otlpOptions)));

    provider.register({
        // Prefer ZoneContextManager: supports asynchronous operations
        contextManager: new ZoneContextManager(),
    });

    // Registering instrumentations
    registerInstrumentations({
        instrumentations: [new DocumentLoadInstrumentation()],
    });
}

function parseDelimitedValues(s) {
    const headers = s.split(','); // Split by comma
    const result = {};

    headers.forEach(header => {
        const [key, value] = header.split('='); // Split by equal sign
        result[key.trim()] = value.trim(); // Add to the object, trimming spaces
    });

    return result;
}

Il codice JavaScript precedente definisce una funzione initializeTelemetry che prevede l'URL dell'endpoint OTLP, le intestazioni e gli attributi della risorsa. Questi parametri sono forniti dall'app browser consumatore, che li recupera dalle variabili di ambiente impostate dall'host dell'app. Si consideri il codice Razor seguente:

@using System.Diagnostics
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>@ViewData["Title"] - BrowserTelemetry</title>
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-QWTKZyjpPEjISv5WaRU9OFeRpok6YctnYmDr5pNlyT2bRjXh0JMhjY6hW+ALEwIH" crossorigin="anonymous">
    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />

    @if (Activity.Current is { } currentActivity)
    {
        <meta name="traceparent" content="@currentActivity.Id" />
    }
</head>
<body>
    <header>
        <nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow mb-3">
            <div class="container">
                <a class="navbar-brand" asp-area="" asp-page="/Index">BrowserTelemetry</a>
            </div>
        </nav>
    </header>
    <div class="container">
        <main role="main" class="pb-3">
            @RenderBody()
        </main>
    </div>
    @await RenderSectionAsync("Scripts", required: false)
    <script src="scripts/bundle.js"></script>
    @if (Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT") is { Length: > 0 } endpointUrl)
    {
        var headers = Environment.GetEnvironmentVariable("OTEL_EXPORTER_OTLP_HEADERS");
        var attributes = Environment.GetEnvironmentVariable("OTEL_RESOURCE_ATTRIBUTES");
        <script>
            BrowserTelemetry.initializeTelemetry('@endpointUrl', '@headers', '@attributes');
        </script>
    }
</body>
</html>

Consiglio

La creazione di bundle e la minimizzazione del codice JavaScript esula dall'ambito di questo articolo.

Per l'esempio completo di funzionamento su come configurare JavaScript OTEL SDK per inviare dati di telemetria al dashboard, visualizzare l'esempio di telemetria del browser .

Vedere anche