Включение телеметрии браузера

Статья
12/15/2024

Панель мониторинга .NET.NET Aspire может быть настроена для получения телеметрии, отправляемой из приложений браузера. Эта функция полезна для мониторинга производительности и взаимодействий пользователей на стороне client. Для телеметрии браузера требуется дополнительная конфигурация панели мониторинга, и JavaScript SDK OTEL добавляется в браузерные приложения.

В этой статье описывается включение телеметрии браузера на панели мониторинга .NET.NET Aspire.

Конфигурация панели мониторинга

Для телеметрии браузера требуется панель мониторинга, чтобы включить следующие функции:

Конечная точка HTTP OTLP. Эта конечная точка используется панелью мониторинга для получения телеметрии из приложений браузера.
Совместное использование ресурсов между источниками (CORS). CORS позволяет приложениям браузера отправлять запросы на панель мониторинга.

Конфигурация OTLP

Панель мониторинга .NET.NET Aspire получает данные телеметрии через конечные точки OTLP. конечные точки HTTP OTLP и конечные точки OTLP gRPC поддерживаются панелью мониторинга. Приложения браузера должны использовать ПРОТОКОЛ HTTP OLTP для отправки телеметрии на панель мониторинга, так как приложения браузера не поддерживают gRPC.

Чтобы настроить конечные точки gPRC или HTTP, укажите следующие переменные среды:

DOTNET_DASHBOARD_OTLP_ENDPOINT_URL: конечная точка gRPC, к которой панель мониторинга подключается для своих данных.
DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL: конечная точка HTTP, к которой панель мониторинга подключается для своих данных.

Конфигурация конечной точки HTTP OTLP зависит от того, запущена ли панель мониторинга узлом приложения или выполняется автономно.

Настройте OTLP HTTP с использованием узла приложения.

Если приборная панель и ваше приложение запускаются узлом приложения, то OTLP конечные точки для приборной панели настраиваются в файле launchSettings узла приложения.json

Рассмотрим следующий пример 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"
      }
    }
  }
}

Предыдущие параметры запуска JSON файла настраивают все профили для включения переменной среды DOTNET_DASHBOARD_OTLP_HTTP_ENDPOINT_URL.

Настройка OTLP HTTP с автономной панелью мониторинга

Если панель мониторинга используется в автономном режиме, без rest.NET Aspire, то конечная точка HTTP OTLP по умолчанию включена для порта 18890. Однако при запуске контейнера панели мониторинга необходимо сопоставить порт:

Bash
PowerShell

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

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

Предыдущая команда запускает контейнер панели мониторинга и сопоставляет gRPC OTLP с портом 4317 и HTTP OTLP с портом 4318.

Конфигурация CORS

По умолчанию приложения браузера ограничены выполнением междоменных вызовов API. Это влияет на отправку телеметрии на панель мониторинга, так как панель мониторинга и приложение браузера всегда находятся в разных доменах. Настройка CORS на панели мониторинга .NET.NET Aspire удаляет ограничение.

Если панель мониторинга и приложение запущены узлом приложения, конфигурация CORS не требуется. .NET .NET Aspire автоматически настраивает панель мониторинга, чтобы разрешить все источники ресурсов.

Если панель мониторинга используется автономно, CORS необходимо настроить вручную. Домен, используемый для просмотра приложения браузера, должен быть настроен в качестве допустимого источника путем определения переменной среды DASHBOARD__OTLP__CORS__ALLOWEDORIGINS при запуске контейнера панели мониторинга:

Bash
PowerShell

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

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

Предыдущая команда запускает контейнер панели мониторинга и настраивает https://localhost:8080 в качестве разрешенного источника. Это означает, что приложение браузера, доступ к которому осуществляется с помощью https://localhost:8080, имеет разрешение на отправку данных телеметрии панели мониторинга.

Множественные источники можно разрешить в виде значений, разделенных запятыми. Или все происхождения можно разрешить с помощью подстановочного знака *. Например, DASHBOARD__OTLP__CORS__ALLOWEDORIGINS=*.

Дополнительные сведения см. в разделе .NET.NET Aspire конфигурации панели мониторинга: OTLP CORS.

Безопасность конечной точки OTLP

Конечные точки OTLP панели мониторинга можно защитить с помощью проверки подлинности ключа API. При включении HTTP-запросы OTLP на информационную панель должны включать ключ API в заголовке x-otlp-api-key. По умолчанию при каждом запуске панели мониторинга создается новый ключ API.

Проверка подлинности ключа API автоматически включена при запуске панели мониторинга с узла приложения. Проверка подлинности панели мониторинга может быть отключена, задав DOTNET_DASHBOARD_UNSECURED_ALLOW_ANONYMOUS значение true в launchSettings узла приложения.json файл.

Конечные точки OTLP незащищены по умолчанию на автономной панели мониторинга.

Конфигурация приложения браузера

Приложение браузера использует JavaScript SDK OTEL для отправки телеметрии на панель мониторинга. Для успешной отправки телеметрии на панель мониторинга требуется правильно настроить пакет SDK.

Экспортер OTLP

Экспортеры OTLP должны быть включены в приложение браузера и настроены с помощью пакета SDK. Например, при экспорте распределенной трассировки с помощью OTLP используется пакет @opentelemetry/exporter-trace-otlp-proto.

При добавлении OTLP в пакет SDK необходимо указать параметры OTLP. Параметры OTLP включают:

url: адрес, к которому выполняются запросы HTTP OTLP. Адрес должен быть конечной точкой HTTP OTLP панели мониторинга и путь к API HTTP OTLP. Например, https://localhost:4318/v1/traces для экспортера OTLP трассировки. Если приложение браузера запускается узлом приложения, то конечная точка HTTP OTLP доступна из переменной среды OTEL_EXPORTER_OTLP_ENDPOINT.
headers: заголовки, отправляемые с запросами. Если проверка подлинности ключа API конечной точки OTLP включена, необходимо отправить заголовок x-otlp-api-key с запросами OTLP. Если приложение браузера запускается узлом приложения, ключ API доступен из переменной среды OTEL_EXPORTER_OTLP_HEADERS.

Метаданные браузера

Если браузерное приложение настроено для сбора распределенных трассировок, приложение браузера может задать родительские диапазоны трассировки браузера с помощью элемента meta в HTML. Значение метаэлемента name="traceparent" должно соответствовать текущей трассе.

Например, в приложении .NET, значение родительской трассировки, вероятно, будет назначено из Activity.Current, а значение Activity.Id будет передано в качестве content. Например, рассмотрим следующий код Razor:

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

Предыдущий код устанавливает метаэлемент traceparent в идентификатор текущей активности.

Пример кода телеметрии браузера

Следующий код JavaScript демонстрирует инициализацию пакета SDK для JavaScript OpenTelemetry и отправку данных телеметрии на панель мониторинга:

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

Предыдущий код JavaScript определяет функцию initializeTelemetry, которая ожидает URL-адрес конечной точки OTLP, заголовки и атрибуты ресурса. Эти параметры предоставляются приложением браузера, которое извлекает их из переменных среды, заданных узлом приложения. Рассмотрим следующий код Razor:

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

Совет

Объединение и минификации кода JavaScript выходит за рамки этой статьи.

Полный рабочий пример настройки пакета SDK OTEL для JavaScript для отправки данных телеметрии на панель мониторинга см. в примере телеметрии браузера .

См. также

.NET .NET Aspire конфигурация панели мониторинга
Автономная .NET.NET Aspire панель мониторинга
Пример телеметрии браузера

Поделиться через