EUM Browser агент

Proto OBP End User Monitoring Browser агент позволяет собирать данные о производительности веб-приложения напрямую с веб-клиентов, инструментируя браузеры конечных пользователей.
Tags:

На этой странице:

Подключение и инициализация агента

Подключение файла JavaScript

Добавьте подключение файла JavaScript агента как можно раньше в теге head на каждой странице сайта, которые хотите отслеживать, например, в шаблон сайта.

  1. Асинхронное подключение. В данном варианте загрузка JavaScript файла агента происходит в асинхронном режиме. Это позволяет не блокировать загрузку основного контента страницы, но не позволяет агенту остлеживать ошибки и события, которые произошли до момента загрузки и инициализации агента.

    <script>
  (function (h, o, u, n, d) {
    h = h[d] = h[d] || {
      q: [],
      onReady: function (c) {
        h.q.push(c);
      },
    };
    d = o.createElement(u);
    d.async = 1;
    d.src = n;
    n = o.getElementsByTagName(u)[0];
    n.parentNode.insertBefore(d, n);
  })(window, document, "script", "/js/pobp-rum.js", "POBP_RUM");
  POBP_RUM.onReady(function () {
    POBP_RUM.init({
      clientToken: "1", // обязательно, любое уникальное число
      applicationId: "1", //  обязательно, любое уникальное число
      site: "https://eum.domain.ru:443", // адрес для отсылки данных, например, прокси сервер, который направляет данные на сервер Proto OBP 
      service: "web-front-end-async", // уникальное имя приложения для идентификации данных в интерфейсе Proto OBP
      env: "prod", // например, prod|test|dev|qa
      version: "1.0.0", // версия фронт-енд приложения, обязательно
      sessionSampleRate: 100, // процент сэмплирования, 100 - все клиенты, 10 - данные будут собираться только с 10% клиентов
      trackResources: true, // обязательно
      trackLongTasks: true, // обязательно
      trackUserInteractions: true, // обязательно
      trackFrustrations: true, // обязательно
      telemetrySampleRate: 0, // обязательно
      allowedTracingUrls: [
        "<https://api.example.com>",
        /https:\/\/.*\.my-api-domain\.com/,
        (url) => url.startsWith("<https://api.example.com>"),
      ],
      // список разрешенных для трейсинга URL, подробнее в документации ниже
    });
  });
</script>

  2. Синхронное подключение. В данном случае загрузка JavaScript файла агента будет блокировать обработку страницы. Плюс такого метода в том, что агент при ранней инцииализации будет отслеживать вообще JavaScript ошибки и все загрузки ресурсов, с самого начала обработки страницы.

    <!-- подключения EUM агента Proto OBP-->
<script src="/pobp-rum.js" type="text/javascript"></script>
<!-- инициализация EUM агента Proto OBP-->
<script>
  window.POBP_RUM &&
    window.POBP_RUM.init({
      clientToken: "1", // обязательно, любое уникальное число
      applicationId: "1", //  обязательно, любое уникальное число
      site: "https://eum.company.ru:443", // адрес для отсылки данных, например, прокси сервер, который направляет данные на сервер Proto OBP 
      service: "web-front-end-async", // уникальное имя приложения для идентификации данных в интерфейсе Proto OBP
      env: "prod", // например, prod|test|dev|qa
      version: "1.0.0", // версия фронт-енд приложения, обязательно
      sessionSampleRate: 100, // процент сэмплирования, 100 - все клиенты, 10 - данные будут собираться только с 10% клиентов
      trackResources: true, // обязательно
      trackLongTasks: true, // обязательно
      trackUserInteractions: true, // обязательно
      trackFrustrations: true, // обязательно
      telemetrySampleRate: 0, // обязательно
      allowedTracingUrls: [
        "<https://api.example.com>",
        /https:\/\/.*\.my-api-domain\.com/,
        (url) => url.startsWith("<https://api.example.com>"),
      ],
      // список разрешенных для трейсинга URL, подробнее в документации ниже
    });
</script>

Пример конфигурации прокси-сервера для проброса EUM трафика

Рассмотрим пример:

  • адрес подключаемого сайта: www.company.ru,
  • для сбора EUM трафика используется домен: eum.company.ru
  • настройка инициализации POBP_RUM: 
    ...
site: "https://eum.company.ru:443"
...
  • адрес ProtoOBP Backend сервера во внутренней корпоративной сети: protoobp.company.local
  • пример базовой конфигурации Nginx для домена eum.company.ru: 
    http {
    server {
        listen 443 ssl;
        server_name eum.company.ru;

        # действительный путь к вашему SSL сертификату и ключу
        ssl_certificate     /etc/nginx/ssl/eum.company.ru.crt;
        ssl_certificate_key /etc/nginx/ssl/eum.company.ru.key;

        location /api/v2/rum {
            proxy_pass https://protoobp.company.local;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }
        location / {
          return 404;
        }
    }
}

Поддерживаемые переменные инциализации

clientToken
      Обязательное
      Тип: строка
      Пример значения: '1111'
      Комментарий: Любое уникальное число.

applicationId
      Обязательное
      Тип: строка
      Пример значения: '2222'
      Комментарий: Любое уникальное число.

site
      Обязательное
      Тип: строка
      Пример значения: 'https://eum.site.ru', 'https://site.ru/eum'
      Комментарий: Адрес для отсылки данных, например, прокси сервер, который направляет данные на сервер Proto OBP.

telemetrySampleRate
      Обязательное
      Тип: число
      Пример значения: 0
      Комментарий: Указать значение 0.

service
      Обязательное
      Тип: строка
      Пример значения: 'web-frontend'
      Комментарий: Уникальное имя приложения для идентификации данных в интерфейсе Proto OBP.

env
      Опциональное
      Тип: строка
      Пример значения: 'prod'
      Комментарий: Например, prod|test|dev|qa

version
      Опциональное
      Тип: строка
      Пример значения: '1.0.0'
      Комментарий: Версия фронт-енд приложения. По каждой версии в Proto OBP доступна отдельная аналитика.

sessionSampleRate
      Обязательное
      Тип: число
      Пример значения: 100
      Комментарий: Процент сэмплирования пользователей для сбора данных EUM. Значение 100 - все клиенты, 10 - данные будут собираться только с 10% клиентов.

trackUserInteractions
      Обязательное
      Тип: булево
      Пример значения: true
      Комментарий: Указать значение true. Отвечает за сбор действий пользователей, таких как click и scroll.

trackFrustrations
      Обязательное
      Тип: булево
      Пример значения: true
      Комментарий: Указать значение true. Отвечает за сбор сигналов фрустрации пользователей - rage clicks, dead clicks, error clicks.

allowedTracingUrls
      Опциональное
      Тип: список
      Пример значения: ["<https://api.example.com>", /https:\/\/.*\.my-api-domain\.com/, (url) => url.startsWith("<https://api.example.com>")]
      Комментарий: Список разрешенных для трейсинга URL. При отсылке запросов из браузера к этим URL агент будет инжектировать http заголовки, которые позволят связать трейс транзакции на бэкенде с просмотром страницы или запросом на фронтенде. Обязательно указать список URL с корректной схемой, номером порта (если в приложении при отсылке запросов используется нестандартный порт).

Работа агента c SPA фреймворками

Введение

Для Single Page Apllications (SPA) агент различает навигацию initial_load и route_change с помощью атрибута loading_type. Если клик на странице ведет к новой странице без полного обновления страницы, агент генерирует новый просмотр страницы атрибутом load_type:route_change.

Proto OBP предоставляет уникальную метрику производительности loading_time, которая рассчитывает время, необходимое для загрузки страницы. Эта метрика работает как для первичной загрузки страницы (initial_load), так и для изменения роута (route_change).

Для учета современных веб-приложений время загрузки учитывает сетевые запросы и мутации DOM:

  • Первичная загрузка: loading_time равно, в зависимости от того, что больше:
    • Разница между navigationStart и loadEventEnd.
    • Разница между navigationStart и первым временем отсутствия активности на странице.
  • Изменение роута SPA: Время загрузки равно разнице между кликом пользователя и первым моментом отсутствия активности на странице.

Настройка работы с SPA

  1. В коде инициализации агента добавить параметр:

    trackViewsManually: true,

  2. В коде вашего SPA приложения самотоятельно запускать создание view (startView) для каждой загрузки новой страницы или изменения роута. Опционально, можно изменить имя, сервис и версию.

    • view: по умолчанию равно пути в URL.
    • service: по умолчанию равно указанному значению при инициализации агента.
    • version: по умолчанию равно указаному значению при инициализации агента.

    Пример, в файле приложения добавить ручное создание view (startView) при смене роута:

    // агент может быть не инициализирован, поэтому нужно проверить объект POBP_RUM
$rootScope.$on("$routeChangeSuccess", (event, next, current) => {
  if (typeof window.POBP_RUM !== "undefined") {
    window.POBP_RUM &&
      window.POBP_RUM.startView(
        next.loadedTemplateUrl,
        "web-front-end",
        "1.0.0"
      );
  }
});

Добавление информации о пользователях

Эта опциональная информация поможет идентифицировать пользователя и связать транзакции и просмотры страниц

  1. В режиме асинхронного подключения:

    POBP_RUM.onReady(function() {
    POBP_RUM.setUser({
        id: '1234',             // внутренний идентификатор пользователя
        name: 'John Doe',       // внутреннее имя пользователя
        email: 'john@doe.com',  // email пользователя
       ...
     })
  })

  2. В режиме синхронного подключения:

    window.POBP_RUM && window.POBP_RUM.setUser({
    POBP_RUM.setUser({
        id: '1234',             // внутренний идентификатор пользователя
        name: 'John Doe',       // внутреннее имя пользователя
        email: 'john@doe.com',  // email пользователя
       ...
     })
  })

Исключение определенных JavaScript ошибок

В случае, если небходимо исключить из сбора какие-то JavaScript ошибки, необходимо добавить к коду инициализации агента следующий снипет:


    POBP_RUM.init({
    ...,
    beforeSend: (event, context) => {
        // отключение передачи ошибок с текстом сообщениея 'ignored error'
        if (event.type === 'error' && event.error.message.includes('ignored error')) {
            return false
        }
    },
    ...
    });

Запись сессий пользователя

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


  POBP_RUM.init({
    ...
     sessionSampleRate: 50, // процент сэмплирования, 100 - все сессии, 10 - данные будут собираться только с 10% сессий
  )},
  POBP_RUM.startSessionReplayRecording(); // включение функционала заиписи сессий

Настройка EUM в корпоративной сети

Content Security Policy (CSP)

Добавьте директиву:

connect-src https://<адрес сервер Proto OBP или прокси>

Поддерживаемые версии браузеров

Поддерживаются все современные браузеры.

Возможности Chrome Firefox Safari Edge Chrome Android Safari iOS IE11 < IE11 Opera
сбор ошибок ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ✅
трейсинг ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ✅
смена роута SPA ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ✅
время загрузки ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ✅
resource timing ✅ ✅ 2 ✅ ✅ 2 3 ❌ ✅
navigation timing ✅ ✅ ✅ ✅ ✅ ✅ ✅ ❌ ✅
web vitals ✅ 1 1 ✅ ✅ 1 ❌ ❌ ✅
FCP ✅ ❌ ❌ ✅ ✅ ❌ ❌ ❌ ✅
  1. только First Input Delay
  2. без информации о размере ресурса
  3. только firstByte и загрузка

Какие данные собирает агент

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

ua.string
      заголовок User-Agent
      пример значения: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36

device.type
      тип устройства
      варианты значений:
         desktop - компьютер или ноутбук
         mobile - мобильное устройство
         table - плашет
         bot - бот (синтетический клиент)

os.name
      тип операционной системы
      примеры значений: windows, macos, linux, iOS, android и тд

os.version
      версия операционной системы
      пример значения: 10.15.7

ua.name
      название браузера
      пример значения: Chrome

ua.version
      версия браузера
      пример значения: 104.0.0.0

geo.ip
      IP адрес пользователя
      пример значения: 45.241.11.200

geo.country_iso_code
      страна пользователя
      пример значения: RU

geo.country_subdivision
      регион пользователя
      пример значения: Moskva

geo.city
      город пользователя
      пример значения: Rublevo

В случае необходимости отключения логгирования IP адреса пользователя добавьте в конфигурацию компонента proto-trace-processor переменную (с версии 178):

POBP_TRACE_PROCESSOR_COLLECT_EUM_IP: false

Устранение неисправностей

Нет данных

  1. Поздняя инициализация. Если вы не видите части запросов, таких как XHR, то следует инициализировать агента как можно раньше. Например, инициализировать агента до того, как происходит инициализации другой библиотеки, с помощью которой отсылаются XHR запросы с клиентов.

Проверка инициализации агента

Выполните window.POBP_RUM.getInternalContext() в консоли браузера и убедитесь, что возвращаются данные, как на примере ниже.

../../images/eum-browser-check.png

Настройка CORS для передачи заголовков ProtoOBP

В случае, если от Браузера пользователя уходят запросы на сервер с инструментированным приложением трейсером ProtoOBP необходимо на стороне веб-сервера разрешать передачу следующих заголовков, добавив их в Access-Control-Allow-Headers:

x-protoobp-origin
x-protoobp-parent-id
x-protoobp-sampling-priority
x-protoobp-trace-id

Подробнее о настройке CORS: Документация

А также, необходимо разрешить Preflight запросы с методом OPTIONS. Документация