Partager via

Activer la télémétrie du navigateur

  • Article

Le tableau de bord .NET.NET Aspire peut être configuré pour recevoir les données de télémétrie envoyées à partir d’applications de navigateur. Cette fonctionnalité est utile pour surveiller les performances et les interactions utilisateur côté client. La télémétrie du navigateur nécessite une configuration supplémentaire du tableau de bord et que le SDK JavaScript OTEL soit ajouté aux applications de navigateur.

Cet article explique comment activer la télémétrie du navigateur dans le tableau de bord .NET.NET Aspire.

Configuration du tableau de bord

La télémétrie du navigateur nécessite le tableau de bord pour activer ces fonctionnalités :

  • Point de terminaison HTTP OTLP. Ce point de terminaison est utilisé par le tableau de bord pour recevoir des données de télémétrie à partir d’applications de navigateur.
  • Partage de ressources inter-origines (CORS). CORS permet aux applications de navigateur d’effectuer des demandes au tableau de bord.

Configuration OTLP

Le tableau de bord .NET.NET Aspire reçoit des données de télémétrie via des points de terminaison OTLP. Les points de terminaison HTTP OTLP et les points de terminaison gRPC OTLP sont pris en charge par le tableau de bord. Les applications de navigateur doivent utiliser HTTP OLTP pour envoyer des données de télémétrie au tableau de bord, car les applications de navigateur ne prennent pas en charge gRPC.

Pour configurer les points de terminaison gPRC ou HTTP, spécifiez les variables d’environnement suivantes :

  • DOTNET_DASHBOARD_OTLP_ENDPOINT_URL: point de terminaison gRPC auquel le tableau de bord se connecte pour ses données.
  • DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL: point de terminaison HTTP auquel le tableau de bord se connecte pour ses données.

La configuration du point de terminaison HTTP OTLP dépend du démarrage du tableau de bord par l’hôte de l’application ou de l’exécution autonome.

Configurer le protocole OTLP HTTP avec l'Hôte d'application

Si le tableau de bord et votre application sont démarrés par l’hôte d’application, les points de terminaison OTLP du tableau de bord sont configurés dans les launchSettings de l’hôte d’application, fichierjson.

Prenons l’exemple suivant du fichier 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"
      }
    }
  }
}

Les paramètres de lancement précédents JSON fichier configurent tous les profils pour inclure la variable d’environnement DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL.

Configurer le protocole HTTP OTLP avec un tableau de bord autonome

Si le tableau de bord est utilisé autonome, sans le rest de .NET Aspire, le point de terminaison HTTP OTLP est activé par défaut sur le port 18890. Toutefois, le port doit être mappé lorsque le conteneur de tableau de bord est démarré :

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

La commande précédente exécute le conteneur de tableau de bord et mappe gRPC OTLP au port 4317 et HTTP OTLP au port 4318.

Configuration CORS

Par défaut, les applications de navigateur ne peuvent pas effectuer des appels d’API inter-domaines. Cela a un impact sur l’envoi de données de télémétrie au tableau de bord, car le tableau de bord et l’application de navigateur se trouvent toujours sur différents domaines. La configuration de CORS dans le tableau de bord .NET.NET Aspire supprime la restriction.

Si le tableau de bord et votre application sont démarrés par l’hôte de l’application, aucune configuration CORS n’est requise. .NET .NET Aspire configure automatiquement le tableau de bord pour autoriser toutes les origines des ressources.

Si le tableau de bord est utilisé de manière autonome, CORS doit être configuré manuellement. Le domaine utilisé pour afficher l’application de navigateur doit être configuré en tant qu’origine autorisée en specifant la variable d’environnement DASHBOARD__OTLP__CORS__ALLOWEDORIGINS lorsque le conteneur de tableau de bord est démarré :

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

La commande précédente exécute le conteneur de tableau de bord et configure https://localhost:8080 comme origine autorisée. Cela signifie qu’une application de navigateur accessible à l’aide de https://localhost:8080 est autorisée à envoyer les données de télémétrie du tableau de bord.

Plusieurs origines peuvent être autorisées avec une valeur séparée par des virgules. Ou toutes les origines peuvent être autorisées avec le caractère générique *. Par exemple, DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=*.

Pour plus d’informations, consultez .NET.NET Aspire configuration du tableau de bord : OTLP CORS.

Sécurité des points de terminaison OTLP

Les points de terminaison OTLP du tableau de bord peuvent être sécurisés avec l’authentification par clé API. Lorsque cette option est activée, les requêtes HTTP OTLP au tableau de bord doivent inclure la clé API comme en-tête x-otlp-api-key. Par défaut, une nouvelle clé API est générée chaque fois que le tableau de bord est exécuté.

L’authentification par clé API est automatiquement activée lorsque le tableau de bord est exécuté à partir de l’hôte de l’application. L'authentification du tableau de bord peut être désactivée en définissant DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS sur true dans le fichier de lancement launchSettings de l'hôte d'application, fichierjson.

Les points de terminaison OTLP ne sont pas sécurisés par défaut dans le tableau de bord autonome.

Configuration de l’application du navigateur

Une application de navigateur utilise le SDK JavaScript OTEL pour envoyer des données de télémétrie au tableau de bord. L’envoi de données de télémétrie au tableau de bord nécessite que le Kit de développement logiciel (SDK) soit correctement configuré.

Exportateur OTLP

Les exportateurs OTLP doivent être inclus dans l’application de navigateur et configurés avec le Kit de développement logiciel (SDK). Par exemple, l’exportation du suivi distribué avec OTLP utilise le package @opentelemetry/exporter-trace-otlp-proto.

Quand OTLP est ajouté au Kit de développement logiciel (SDK), les options OTLP doivent être spécifiées. Les options OTLP incluent :

  • url: adresse à laquelle les requêtes HTTP OTLP sont adressées. L’adresse doit être le point de terminaison HTTP OTLP du tableau de bord et le chemin d’accès à l’API HTTP OTLP. Par exemple, https://localhost:4318/v1/traces pour l’exportateur de traces OTLP. Si l’application de navigateur est lancée par l’hôte de l’application, le point de terminaison HTTP OTLP est disponible à partir de la variable d’environnement OTEL_EXPORTER_OTLP_ENDPOINT.

  • headers: Les en-têtes envoyés avec les requêtes. Si l’authentification par clé API du point de terminaison OTLP est activée, l’en-tête x-otlp-api-key doit être envoyé avec des requêtes OTLP. Si l’application de navigateur est lancée par l’hôte de l’application, la clé API est disponible à partir de la variable d’environnement OTEL_EXPORTER_OTLP_HEADERS.

Métadonnées du navigateur

Lorsqu’une application de navigateur est configurée pour collecter des traces distribuées, l’application de navigateur peut définir les étendues du parent de trace d’un navigateur à l’aide de l’élément meta dans le code HTML. La valeur de l’élément meta name="traceparent" doit correspondre à la trace actuelle.

Dans une application .NET, par exemple, la valeur de trace parent serait probablement assignée à partir du Activity.Current en passant sa valeur Activity.Id comme content. Par exemple, considérez le code Razor suivant :

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

Le code précédent définit l’élément meta traceparent sur l’ID d’activité actuel.

Exemple de code de télémétrie du navigateur

Le code JavaScript suivant illustre l’initialisation du Kit de développement logiciel (SDK) JavaScript OpenTelemetry et l’envoi de données de télémétrie au tableau de bord :

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;
}

Le code JavaScript précédent définit une fonction initializeTelemetry qui attend l’URL du point de terminaison OTLP, les en-têtes et les attributs de ressource. Ces paramètres sont fournis par l’application de navigateur consommatrice qui les extrait des variables d’environnement définies par l’hôte de l’application. Considérez le code Razor suivant :

@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>

Pourboire

Le regroupement et la minification du code JavaScript dépassent la portée de cet article.

Pour obtenir un exemple complet de configuration du Kit de développement logiciel (SDK) JavaScript afin d'envoyer des données de télémétrie au tableau de bord, consultez l'exemple de télémétrie du navigateur .

Voir aussi