Delen via

Browsertelemetrie inschakelen

  • Artikel

Het .NET.NET Aspire-dashboard kan worden geconfigureerd voor het ontvangen van telemetrie die wordt verzonden vanuit browser-apps. Deze functie is handig voor het bewaken van prestaties aan de clientzijde en gebruikersinteracties. Voor browsertelemetrie is extra dashboardconfiguratie vereist en dat de JavaScript OTEL SDK- wordt toegevoegd aan de browser-apps.

In dit artikel wordt beschreven hoe u browsertelemetrie inschakelt in het .NET.NET Aspire-dashboard.

Dashboardconfiguratie

Voor browsertelemetrie moet het dashboard deze functies inschakelen:

  • OTLP HTTP-eindpunt. Dit eindpunt wordt door het dashboard gebruikt om telemetrie van browser-apps te ontvangen.
  • CORS (Cross-Origin Resource Sharing) is een methode voor het delen van resources tussen verschillende oorsprongsbronnen. MET CORS kunnen browser-apps aanvragen indienen bij het dashboard.

OTLP-configuratie

Het .NET.NET Aspire-dashboard ontvangt telemetrie via OTLP-eindpunten. HTTP OTLP-eindpunten en gRPC OTLP-eindpunten worden ondersteund door het dashboard. Browser-apps moeten HTTP OLTP gebruiken om telemetrie naar het dashboard te verzenden, omdat browser-apps gRPC niet ondersteunen.

Als u de gPRC- of HTTP-eindpunten wilt configureren, geeft u de volgende omgevingsvariabelen op:

  • DOTNET_DASHBOARD_OTLP_ENDPOINT_URL: het gRPC-eindpunt waarmee het dashboard verbinding maakt voor de gegevens.
  • DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL: het HTTP-eindpunt waarmee het dashboard verbinding maakt voor de gegevens.

De configuratie van het HTTP OTLP-eindpunt is afhankelijk van of het dashboard wordt gestart door de app-host of zelfstandig wordt uitgevoerd.

OTLP HTTP configureren met app-host

Als het dashboard en uw app worden gestart door de app-host, worden de OTLP-eindpunten van het dashboard geconfigureerd in het launchSettings.json-bestand van de app-host.

Bekijk het volgende voorbeeld JSON bestand:

{
  "$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"
      }
    }
  }
}

Met de voorgaande startinstellingen JSON bestand worden alle profielen geconfigureerd om de DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL omgevingsvariabele op te nemen.

OTLP HTTP configureren met zelfstandig dashboard

Als het dashboard zelfstandig wordt gebruikt, zonder de rest van .NET.NET Aspire, wordt het OTLP HTTP-eindpunt standaard ingeschakeld op poort 18890. De poort moet echter worden toegewezen wanneer de dashboardcontainer wordt gestart:

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

Met de voorgaande opdracht wordt de dashboardcontainer uitgevoerd en wordt gRPC OTLP toegewezen aan poort 4317 en HTTP OTLP naar poort 4318.

CORS-configuratie

Browser-apps kunnen standaard geen API-aanroepen tussen domeinen maken. Dit heeft gevolgen voor het verzenden van telemetrie naar het dashboard, omdat het dashboard en de browser-app zich altijd op verschillende domeinen bevinden. Als u CORS configureert in het .NET.NET Aspire dashboard, wordt de beperking verwijderd.

Als het dashboard en uw app door de app-host worden gestart, is er geen CORS-configuratie vereist. .NET .NET Aspire het dashboard automatisch configureert om alle bronoorsprongen toe te staan.

Als het dashboard standalone wordt gebruikt, moet CORS handmatig worden geconfigureerd. Het domein dat wordt gebruikt om de browser-app weer te geven, moet worden geconfigureerd als een toegestane oorsprong door de DASHBOARD__OTLP__CORS__ALLOWEDORIGINS omgevingsvariabele op te geven wanneer de dashboardcontainer wordt gestart:

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

Met de voorgaande opdracht wordt de dashboardcontainer uitgevoerd en https://localhost:8080 geconfigureerd als een toegestane oorsprong. Dat betekent dat een browser-app die wordt geopend met behulp van https://localhost:8080 gemachtigd is om de telemetrie van het dashboard te verzenden.

Meerdere oorsprongen kunnen worden toegestaan met een door komma's gescheiden waarde. Ofwel kunnen alle herkomst worden toegelaten met het jokerteken *. Bijvoorbeeld DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=*.

Zie .NET.NET Aspire dashboardconfiguratie: OTLP CORS-voor meer informatie.

OTLP-eindpuntbeveiliging

OTLP-eindpunten voor dashboards kunnen worden beveiligd met VERIFICATIE van API-sleutels. Wanneer deze functie is ingeschakeld, moeten HTTP OTLP-aanvragen naar het dashboard de API-sleutel als de x-otlp-api-key-header bevatten. Er wordt standaard een nieuwe API-sleutel gegenereerd telkens wanneer het dashboard wordt uitgevoerd.

VERIFICATIE van API-sleutels wordt automatisch ingeschakeld wanneer het dashboard wordt uitgevoerd vanaf de app-host. Dashboardverificatie kan worden uitgeschakeld door DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS in te stellen op true in het launchSettings.json-bestand van de app-host.

OTLP-eindpunten zijn standaard niet beveiligd in het zelfstandige dashboard.

Configuratie van browser-apps

Een browser-app maakt gebruik van de JavaScript OTEL SDK om telemetrie naar het dashboard te verzenden. Voor het verzenden van telemetrie naar het dashboard moet de SDK correct zijn geconfigureerd.

OTLP-exporteur

OTLP-exporteurs moeten worden opgenomen in de browser-app en geconfigureerd met de SDK. Het exporteren van gedistribueerde tracering met OTLP maakt bijvoorbeeld gebruik van het pakket @opentelemetry/exporter-trace-otlp-proto.

Wanneer OTLP wordt toegevoegd aan de SDK, moeten OTLP-opties worden opgegeven. OTLP-opties omvatten:

  • url: het adres waarnaar HTTP OTLP-aanvragen worden gedaan. Het adres moet het HTTP OTLP-eindpunt van het dashboard en het pad naar de OTLP HTTP-API zijn. Bijvoorbeeld https://localhost:4318/v1/traces voor de OTLP-trace-exporteur. Als de browser-app wordt gestart door de app-host, is het HTTP OTLP-eindpunt beschikbaar vanuit de omgevingsvariabele OTEL_EXPORTER_OTLP_ENDPOINT.

  • headers: de headers die worden verzonden met aanvragen. Als de verificatie van de OTLP-eindpunt-API-sleutel is ingeschakeld, moet de x-otlp-api-key-koptekst met OTLP-aanvragen worden verzonden. Als de browser-app wordt gestart door de app-host, is de API-sleutel beschikbaar vanuit de omgevingsvariabele OTEL_EXPORTER_OTLP_HEADERS.

Browsermetagegevens

Wanneer een browser-app is geconfigureerd voor het verzamelen van gedistribueerde traceringen, kan de browser-app de trace parent van de spans van een browser instellen met behulp van het meta-element in de HTML. De waarde van het name="traceparent" meta-element moet overeenkomen met de huidige tracering.

In een .NET-app kan de traceringsouderwaarde bijvoorbeeld worden toegewezen van de Activity.Current en wordt de Activity.Id-waarde doorgegeven als de content. Denk bijvoorbeeld aan de volgende Razor-code:

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

Met de voorgaande code wordt het traceparent meta-element ingesteld op de huidige activiteits-id.

Voorbeeld van code voor browsertelemetrie

De volgende JavaScript-code demonstreert de initialisatie van de OpenTelemetry JavaScript SDK en het verzenden van telemetriegegevens naar het 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;
}

De voorgaande JavaScript-code definieert een initializeTelemetry functie die de URL van het OTLP-eindpunt, de headers en de resourcekenmerken verwacht. Deze parameters worden geleverd door de verbruikende browser-app die ze ophaalt uit de omgevingsvariabelen die zijn ingesteld door de app-host. Overweeg de volgende Razor-code:

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

Tip

De bundeling en minificatie van de JavaScript-code valt buiten het bereik van dit artikel.

Zie het voorbeeld van browsertelemetrievoor het configureren van de JavaScript OTEL SDK om telemetrie naar het dashboard te verzenden.

Zie ook