Экспорт пользовательских сессий в RUM

Материал из Документация Ключ-АСТРОМ

Экспорт пользовательских сессий в RUM Classic

Ключ-АСТРОМ может непрерывно отправлять данные пользовательских сессий на указанную конечную точку веб-перехватчика.

Для начала получения данных о пользовательских сессиях необходимо настроить конечную точку, а затем сконфигурировать экспорт сессий через веб-интерфейс Ключ-АСТРОМ или через API настроек.

Ключ-АСТРОМ отправляет данные о завершенных пользовательских сессиях пакетом на все определенные конечные точки, с отправкой данных каждые несколько секунд для экспорта сразу после того, как пользовательская сессия помечена как завершенная. Передача данных происходит при выполнении одного из следующих условий:

  • Завершилось 1000 пользовательских сессий.
  • Размер пакета данных превышает 896 000 байт.
  • За последние 30 секунд ни одна пользовательская сессия не завершилась.

Чтобы предотвратить перегрузку системы, Ключ-АСТРОМ отменяет запрос, если ваша конечная точка не отвечает в течение 30 секунд. Ключ-АСТРОМ повторяет попытку еще три раза, прежде чем окончательно отклонить запрос и отправить уведомление с сообщением об ошибке «Тайм-аут запроса».

Определите конечную точку

Сервер, предоставляющий веб-перехватчик, должен прослушивать PUT или POST запросы по URL-адресу, указанному в конфигурации экспорта сессии. Кроме того, по соображениям безопасности Ключ-АСТРОМ разрешает использовать только конечные точки HTTPS.

  • Метод HTTP: PUT или POST
  • Путь: как указано в конфигурации
  • Тип контента: application/json или application/x-ndjson. При отправке в Elasticsearch установите значение application/x-ndjson.
  • Код состояния ответа: 200

Пример кода для Eclipse Jersey

Приведённый ниже пример кода использует фреймворк RESTful Web Services с открытым исходным кодом Jersey. Вы можете использовать этот код для настройки необходимой конечной точки для получения данных пользовательской сессии. 

@Path("/export/")
public class ExportREST {
    ...

    @PUT
    @Produces(MediaType.APPLICATION_JSON)
    @Path("events")
    public JResponse<String> jsonEvents(final String data) {
        ...
        // Разделить основной текст на отдельные документы
        final String[] lines = StringUtils.split(data, '\n');
        for(String line : lines) {
            ...
            // обработка данных в формате JSON
        }

        return JResponse.ok("")
            .header(HttpHeaders.SERVER, "Конечная точка для экспорта данных сессии Ключ-АСТРОМ")
            .build();
    }
}

Настройка экспорта сессий через веб-интерфейс Ключ-АСТРОМ

Для настройки экспорта пользовательских сессий через веб-интерфейс Ключ-АСТРОМ:

  1. Перейдите в Настройки > Интеграция > Экспорт пользовательских сессий.
  2. Выберите Добавить элемент.
  3. Укажите URL-адрес конечной точки и включите параметр Включить экспорт пользовательских сессий, если вы готовы начать получать данные пользовательских сессий.
    • В целях безопасности Ключ-АСТРОМ разрешает использование только HTTPS-интерфейсов.
  4. Установите тип содержимого на application/json или application/x-ndjson. При отправке данных сессии в Elasticsearch установите его на application/x-ndjson.
  5. Включите параметр Использовать метод POST (вместо PUT) при отправке данных сессии в Elasticsearch или при настройке конечной точки для приема POST запросов.
  6. Необязательно: Настройте аутентификацию, включите передачу данных в Elasticsearch или задайте область экспорта, оповещения и расширенные параметры конфигурации.
  7. Вы также можете протестировать экспорт пользовательских сессий, а также загрузить пример набора данных или пример сопоставления.

Вы можете настроить до трех HTTPS-конечных точек.

Настройка аутентификации

Ключ-АСТРОМ может отправлять данные пользовательской сессии, используя либо базовую аутентификацию, либо аутентификацию OAuth 2.0. Эти типы аутентификации позволяют защитить ваши конечные точки.

При активации аутентификации для конфигурации экспорта сессии проверьте конфигурацию перед сохранением.

В целях безопасности при тестировании конфигурации экспорта сессий необходимо повторно ввести пароль базовой аутентификации или секретный ключ клиента OAuth 2.0. Также необходимо повторно ввести пароль или секретный ключ при редактировании существующей конфигурации экспорта сессий с включенной аутентификацией.

Настройка базовой аутентификации

Настройка экспорта пользовательских сессий с базовой аутентификацией:

  1. На странице экспорта пользовательских сессий разверните необходимый URL-адрес конечной точки.
  2. В разделе Аутентификация включите параметр Активировать.
  3. В качестве типа аутентификации укажите Базовая аутентификация.
  4. Введите ваше имя пользователя и пароль.
    • Пароль зашифрован и скрыт в вашей среде.

Настройка аутентификации OAuth 2.0

Для настройки экспорта пользовательских сессий с аутентификацией по учетным данным клиента OAuth 2.0:

  1. На странице экспорта пользовательских сессий разверните необходимый URL-адрес конечной точки.
  2. В разделе Аутентификация включите параметр Активировать.
  3. В качестве типа аутентификации укажите OAuth 2.0.
  4. Введите URL-адрес токена доступа, идентификатор клиента, секретный ключ клиента и область действия (необязательно).
    • Секретный ключ клиента зашифрован и замаскирован в вашей среде.

Дополнительная информация об аутентификации OAuth 2.0

OAuth 2.0 предлагает различные типы предоставления доступа, но Ключ-АСТРОМ поддерживает только тип предоставления доступа «учетные данные клиента».

Для отправки данных пользовательской сессии с использованием аутентификации OAuth 2.0 необходимо настроить сервер авторизации OAuth2, имеющий конечную точку для токена доступа. Также убедитесь, что ваш URL-адрес конечной точки работает с токеном доступа.

Ниже описаны шаги, которые обеспечивают работу аутентификации OAuth 2.0 при экспорте пользовательских сессий:

  1. Ключ-АСТРОМ отправляет запрос на ваш сервер авторизации для получения токена доступа. В запрос включаются URL-адрес вашего токена доступа, идентификатор клиента, секретный ключ клиента и область действия (необязательно).
  2. Ваш сервер авторизации отвечает токеном доступа.
  3. Ключ-АСТРОМ отправляет POST-запрос на настроенный URL-адрес конечной точки. Запрос включает данные пользовательской сессии, а также токен доступа, полученный на предыдущем шаге, который передается в заголовке Authorization в виде токена Bearer.

Отправляйте данные напрямую в Elasticsearch

Для отправки данных непосредственно в вашу установку Elasticsearch:

  1. Убедитесь, что ваш экземпляр Elasticsearch доступен с сервера кластера. Ваш экземпляр Elasticsearch должен быть общедоступным. Для защиты доступа можно использовать SSL-сертификат и базовую аутентификацию или аутентификацию OAuth 2.0.
  2. Убедитесь, что URL-адрес экспорта имеет следующий формат: https://<your_host>:9200/_bulk. Замените <your_host> на ваше фактическое значение.
  3. На странице экспорта пользовательских сессий разверните необходимый URL-адрес конечной точки.
  4. В разделе Определение конечной точки убедитесь, что для параметра Тип содержимого установлено значение application/x-ndjson и включен параметр Использовать метод POST (вместо PUT).
  5. В разделе Отправлять данные непосредственно в Elasticsearch включите параметр Активировать.
  6. Введите имя индекса, куда отправляются данные, и тип документов в индексе Elasticsearch.

Индекс Elasticsearch

Создайте индекс, куда вы хотите отправлять данные пользовательской сессии, и определите сопоставление для этого индекса.

Если вы не создадите индекс до включения экспорта пользовательских сессий, ваша установка Elasticsearch автоматически создаст сопоставления для полей. Это автоматическое сопоставление не всегда создает соответствующие сопоставления полей. Например, поля типа «дата» сопоставляются как long.

Тип индекса Elasticsearch

В настоящее время Elasticsearch прекращает поддержку типов сопоставления. Способ создания индексов и настройки типов зависит от вашей версии Elasticsearch. Мы рекомендуем указывать _doc в качестве типа документа независимо от используемой вами версии Elasticsearch.

  • Elasticsearch версии 6: Для каждого индекса укажите только один тип. При создании индекса укажите параметр include_type_name.
  • Elasticsearch версии 7: Указание типов устарело. Параметр include_type_name по умолчанию имеет значение false.
  • Elasticsearch версии 8: Указание типов больше не поддерживается. Тип документа следует опустить.

Type относится к «типу индекса», используемому в Elasticsearch, и не ограничивает экспорт пользовательских сессий. Независимо от выбранного типа, экспортируются все данные пользовательских сессий, включая действия пользователей, события и ошибки. Чтобы ограничить экспортируемые пользовательские сессии, можно определить зону управления.

Настройте область экспорта, оповещения и расширенные параметры конфигурации

В разделе Область экспорта, оповещения и расширенная конфигурация вашей конечной точки вы можете сузить область экспорта сессий, отключить уведомления и настроить некоторые другие параметры экспорта сессий.

  • Область экспорта: Чтобы определить область экспорта пользовательских сессий, выберите необходимую зону управления. После настройки зоны управления Ключ-АСТРОМ будет отправлять только те пользовательские сессии, которые содержат хотя бы одно действие пользователя с соответствующим приложением. В настоящее время ограничить экспорт сессий только синтетическими пользовательскими сессиями невозможно.
  • Оповещения: Включите оповещения, если не хотите получать уведомления о сбоях экспорта пользовательских сессий.
  • Пользовательская конфигурация: Укажите параметры пользовательской конфигурации для дальнейшей настройки параметров экспорта пользовательских сессий. Перед изменением этого поля свяжитесь со специалистом по продуктам Ключ-АСТРОМ через онлайн-чат.

Если у вас возникнут какие-либо проблемы с экспортом пользовательских сессий, свяжитесь со специалистом Ключ-АСТРОМ через онлайн-чат, прежде чем настраивать какие-либо дополнительные параметры.

Тестовый экспорт

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

Если кнопка Проверить экспорт неактивна, скорее всего, это связано с тем, что в вашем URL-адресе конечной точки или URL-адресе токена доступа указан протокол HTTP. В целях безопасности Ключ-АСТРОМ разрешает только протокол HTTPS.

Ключ-АСТРОМ использует текущую конфигурацию экспорта сессий для экспорта до 50 пользовательских сессий за последние семь дней. Если данные за этот период отсутствуют, тестовый экспорт недоступен. Как только тестовый экспорт завершится, вы получите уведомление о результатах.

Для тестирования конечной точки сохранять конфигурацию не требуется.

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

  • Проверьте конфигурацию перед сохранением.
  • При проверке конфигурации повторно введите пароль для базовой аутентификации или секретный ключ клиента OAuth 2.0.

Скачать пример набора данных

Чтобы увидеть, как выглядят данные пользовательской сессии при экспорте на ваши конечные точки, разверните необходимый URL-адрес конечной точки на странице Экспорт пользовательских сессий и выберите Загрузить пример данных для экспорта.

Пример набора данных содержит до 50 пользовательских сессий, отслеживаемых в вашей среде за последние семь дней. Если за этот период нет пользовательских сессий, загрузка примера данных недоступна.

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

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

Скачать пример сопоставления

Чтобы экспортировать данные пользовательских сессий непосредственно в свой экземпляр Elasticsearch, вы можете загрузить пример сопоставления для ваших индексов. Разверните необходимый URL-адрес конечной точки на странице экспорта пользовательских сессий и выберите Загрузить сопоставление. Загруженный файл шаблона сопоставления содержит сопоставление для каждого экспортируемого поля.

Созданный пример сопоставления отражает ваши текущие настройки, поэтому вы можете использовать его при создании индекса, куда будут экспортироваться данные пользовательских сессий.

Настройка экспорта сессий через API

Конфигурация экспорта пользовательских сессий хранится с использованием платформы Settings 2.0. Она предоставляет REST API, который можно использовать для создания, чтения, обновления и удаления конфигураций экспорта сессий.

Идентификатор схемы для конфигурации экспорта пользовательских сессий: builtin:elasticsearch.user-session-export-settings-v2.

С помощью этого идентификатора схемы вы можете, например, прочитать текущую конфигурацию экспорта пользовательских сессий, используя любой REST-клиент.

В один запрос можно добавить только одну конфигурацию экспорта пользовательской сессии. Если вам необходимо добавить вторую конфигурацию экспорта сессии, отправьте новый POST запрос.

Проверьте конфигурацию экспорта сессии

Для проверки конфигурации экспорта сессии выполните команду ниже. 

curl -v -H "Content-Type: application/json" -X PUT -d '{"visitorId":"14804637803609BCTKP776NMJBOIF3R8OD6R0E4NQALJO","visitId":"16229530","startTime":1480463779085,"endTime":1480463784889,"visitType":"SYNTHETIC"}' http://localhost:3000/export/events

При необходимости можно установить следующие дополнительные флаги:

  • --insecure чтобы отключить проверку SSL
  • --http1.1 если команда возвращает ошибку REFUSED_STREAM
Источник — https://doc.ruscomtech.ru/index.php?title=Экспорт_пользовательских_сессий_в_RUM&oldid=6464