Браузерный JS

Браузерный SDK для ClickStack — стека обсервабилити ClickHouse

Браузерный SDK ClickStack позволяет добавить в ваше frontend-приложение инструментацию для отправки событий в ClickStack. Это дает возможность просматривать сетевые запросы и исключения вместе с серверными событиями на единой временной шкале.

Кроме того, SDK автоматически собирает и помогает коррелировать данные воспроизведения сеанса, чтобы вы могли пошагово просматривать и отлаживать то, что видел пользователь во время работы с вашим приложением.

Это руководство включает интеграцию следующего:

• Журналы консоли
• Воспроизведение сеансов
• Запросы XHR/Fetch/WebSocket
• Исключения

​

Начало работы

Импорт пакета

Установка через импорт пакета (рекомендуется)

Используйте следующую команду, чтобы установить браузерный пакет.

npm install @hyperdx/browser

Инициализируйте ClickStack

import HyperDX from '@hyperdx/browser';

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // не указывайте для Управляемого ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Укажите, чтобы связывать трассировки из фронтенда с запросами к бэкенду
    consoleCapture: true, // Собирать журналы консоли (по умолчанию false)
    advancedNetworkCapture: true, // Собирать полные заголовки и тела HTTP-запросов/ответов (по умолчанию false)
});

Тег script

Установка через тег script (альтернативный вариант)

Вы также можете подключить и установить скрипт через тег script вместо установки через NPM. Это создаст глобальную переменную HyperDX, которую можно использовать так же, как и пакет NPM.

Этот вариант рекомендуется, если ваш сайт сейчас не собирается с помощью бандлера.

<script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
<script>
  window.HyperDX.init({
    url: 'http://localhost:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // не указывайте для Управляемого ClickStack
    service: 'my-frontend-app',
    tracePropagationTargets: [/api.myapp.domain/i], // Укажите, чтобы связывать трассировки из фронтенда с запросами к бэкенду
  });
</script>

​

Параметры

• apiKey - Ваш ключ API ClickStack для приёма данных.
• service - Имя сервиса, под которым события будут отображаться в интерфейсе HyperDX.
• tracePropagationTargets - Список шаблонов регулярных выражений для сопоставления с HTTP запросами, чтобы связывать трассировки фронтенда и бэкенда; ко всем запросам, соответствующим любому из шаблонов, будет добавляться дополнительный заголовок traceparent. Здесь следует указать домен API вашего бэкенда (например, api.yoursite.com).
• consoleCapture - (Необязательно) Захватывать весь журнал консоли (по умолчанию false).
• advancedNetworkCapture - (Необязательно) Захватывать полные заголовки и тела запросов и ответов (по умолчанию false).
• url - (Необязательно) URL OpenTelemetry Collector; требуется только для самоуправляемых экземпляров.
• maskAllInputs - (Необязательно) Маскировать ли все поля ввода в воспроизведении сеанса (по умолчанию false).
• maskAllText - (Необязательно) Маскировать ли весь текст в воспроизведении сеанса (по умолчанию false).
• disableIntercom - (Необязательно) Отключить ли интеграцию с Intercom (по умолчанию false)
• disableReplay - (Необязательно) Отключить ли воспроизведение сеанса (по умолчанию false)

​

Дополнительная конфигурация

​

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

Добавление информации о пользователе позволит искать/фильтровать сеансы и события в интерфейсе HyperDX. Это можно вызвать в любой момент в течение клиентского сеанса. Текущий клиентский сеанс и все события, отправленные после этого вызова, будут связаны с информацией о пользователе.

userEmail, userName и teamName будут отображаться в интерфейсе сеансов как соответствующие значения, но их можно не указывать. Любые другие дополнительные значения можно задать и использовать для поиска событий.

HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Другие пользовательские свойства...
});

​

Автоматический перехват ошибок в границах ошибок React

Если вы используете React, вы можете автоматически перехватывать ошибки, которые возникают в границах ошибок React, передав компонент границы ошибок в функцию attachToReactErrorBoundary.

// Импортируйте ваш ErrorBoundary (в качестве примера используется react-error-boundary)
import { ErrorBoundary } from 'react-error-boundary';

// Это подключится к компоненту ErrorBoundary и перехватит все ошибки, возникающие
// в любом его экземпляре.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);

​

Отправка пользовательских действий

Чтобы явно отслеживать конкретное событие в приложении (например, регистрацию, отправку формы и т. д.), можно вызвать функцию addAction, указав имя события и при необходимости его метаданные.

Пример:

HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});

​

Динамическое включение захвата сетевого трафика

Чтобы динамически включать или отключать захват сетевого трафика, просто вызывайте функцию enableAdvancedNetworkCapture или disableAdvancedNetworkCapture по мере необходимости.

HyperDX.enableAdvancedNetworkCapture();

​

Включение таймингов ресурсов для CORS-запросов

Если ваше фронтенд-приложение отправляет API-запросы на другой домен, вы можете при необходимости настроить отправку заголовка Timing-Allow-Origin вместе с запросом. Это позволит ClickStack собирать подробную информацию о таймингах ресурса для запроса, такую как DNS lookup, загрузка ответа и т. д., через PerformanceResourceTiming.

Если вы используете express с пакетами cors, можно воспользоваться следующим фрагментом, чтобы включить этот заголовок:

var cors = require('cors');
var onHeaders = require('on-headers');

// ... весь ваш код

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());