Создание пользовательских метрик USQL для веб-приложений

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

Создание пользовательских метрик USQL для веб-приложений

С помощью событий метрик USQL вы можете извлекать ключевые показатели эффективности (KPI) на уровне бизнеса из данных о пользовательских сессиях и действиях пользователей и сохранять эти метрики в виде временных рядов. Затем вы можете использовать сохраненные метрики в пользовательских диаграммах, механизмах оповещения или API метрик.

Метрики событий USQL доступны в следующем формате:

  • Метрики событий пользовательских сессий — сокращенно USCM, имеют префикс uscm..
  • Метрики действий пользователей — сокращенно UACM, имеют префикс uacm..

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

Метрики событий USQL могут помочь ответить на такие вопросы, как:

  • Как меняется индекс пользовательского опыта моего сайта с течением времени?
  • Как меняется индекс Apdex для определенного типа действий пользователя с течением времени?
  • Как меняется доход, получаемый от моих пользователей, с течением времени?
  • Сколько пользователей посещают мой сайт и какие браузеры они используют?
  • Какова средняя продолжительность сеанса работы моего веб-приложения?
  • Какова средняя продолжительность действий пользователя при использовании моего мобильного приложения?

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

Настройка метрик через пользовательский интерфейс

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

  1. Перейдите в Настройки > Веб- и мобильный мониторинг > События метрик пользовательских сессий или События метрик действий пользователей.
  2. Выберите Добавить элемент.
  3. Введите ключ метрики, который следует использовать при импорте метрики. Этот ключ будет использоваться при запросе данных метрики через Визуализацию данных.
    • Для событий метрик пользовательских сессий начинайте ключ метрики с префикса uscm..
    • Для событий метрик, связанных с действиями пользователей, начинайте ключ метрики с префикса uacm..
  4. В поле Тип извлекаемого значения выберите один из следующих вариантов:
    • Для событий метрик пользовательских сессий:
      • Счетчик пользовательских сессий — подсчет количества пользовательских сессий, аналогично COUNT(*) в USQL.
      • Значение поля пользовательской сессии — извлечение значения поля, укажите также имя поля. Возможные значения см. в разделе «Значения для событий метрик пользовательской сессии».
    • Для событий, отражающих действия пользователей:
      • Счетчик действий пользователя — подсчет количества действий пользователя, аналогично COUNT(*) в USQL.
      • Значение поля действия пользователя — извлечение значения поля, укажите также имя поля. Возможные значения см. в разделе «Значения для событий метрик действий пользователя».
  5. В разделе Добавить измерение укажите поля, которые следует использовать в качестве измерений. Возможные значения см. в разделах «Измерения для событий метрик пользовательской сессии» и «Измерения для событий метрик действий пользователя».
  6. В разделе Добавить фильтр укажите необходимые фильтры.
    • Введите имя поля. Возможные значения см. в разделах «Фильтры для событий метрик пользовательской сессии» или «Фильтры для событий метрик действий пользователя».
    • Выберите оператор.
    • Если вы выбрали один из бинарных операторов, например, «равно» или «больше», укажите также второй аргумент в текстовом поле Значение.

В качестве альтернативы вы можете использовать USQL для создания событий метрик USQL.

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

Также вы можете использовать API настроек для конфигурации событий метрик USQL.

  1. Создайте токен доступа с правами на запись настроек (settings.write) и чтение настроек (settings.read).
  2. Используйте конечную точку GET для получения схемы, чтобы узнать формат JSON, необходимый для отправки вашей конфигурации.
  3. Идентификатор схемы конфигурации метрик для пользовательских сессий (schemaId) — builtin:custom-metrics. Для действий пользователей — builtin:user-action-custom-metrics.

Пример полезной нагрузки JSON для пользовательской метрики сессии

[
  {
    "schemaVersion" : "0.0.4",
    "schemaId" : "builtin:custom-metrics",
    "scope" : "tenant",
    "value" : {
        "enabled" : true,
        "metricKey" : "uscm.sessions_by_browser_family_and_country_easytravel",
        "value" : {
            "type" : "COUNTER"
        },
        "dimensions" : [
            "browserFamily",
            "country"
        ],
        "filters" : [
            {
            "fieldName" : "useraction.application",
            "operator" : "equals",
            "value" : "www.easytravel.com"
            },
            {
            "fieldName" : "userType",
            "operator" : "equals",
            "value" : "REAL_USER"
            }
        ]
    }
  }
]

Пример полезной нагрузки JSON для пользовательской метрики действий пользователя

[
  {
    "schemaVersion" : "1.0.0",
    "schemaId" : "builtin:user-action-custom-metrics",
    "scope" : "tenant",
    "value" : {
        "enabled" : true,
        "metricKey" : "uacm.actions_by_type_and_country_easytravel",
        "value" : {
            "type" : "COUNTER"
        },
        "dimensions" : [
            "type",
            "usersession.country"
        ],
        "filters" : [
            {
            "fieldName" : "application",
            "operator" : "equals",
            "value" : "www.easytravel.com"
            },
            {
            "fieldName" : "usersession.userType",
            "operator" : "equals",
            "value" : "REAL_USER"
            }
        ]
    }
  }
]

Используйте конечную точку POST для отправки объекта, чтобы передать вашу конфигурацию.

Параметры конфигурации

Свойство Описание Возможные значения
enabled Определяет, включена ли пользовательская метрика USQL. Установите false, чтобы временно отключить метрику. true или false
metricKey Ключ метрики, используемый при загрузке метрики. Используйте этот ключ при запросе данных метрики через Визуализацию данных.
Для событий метрик пользовательских сессий ключ метрики должен начинаться с префикса uscm..
Для событий метрик, связанных с действиями пользователей, ключ метрики должен начинаться с префикса uacm..
value Источник значения метрики.
value.type Чтобы подсчитать количество пользовательских сессий или действий пользователей, аналогично COUNT(*) в USQL, установите значение COUNTER.
Чтобы извлечь значение поля пользовательской сессии или действия пользователя, установите значение FIELD.		 COUNTER или FIELD
value.fieldName Если value.type=FIELD, указывается имя поля пользовательской сессии или действия пользователя. См. «Значения для событий метрик пользовательской сессии» и «Значения для событий метрик действий пользователя»
dimensions Список полей, используемых в качестве измерений. См. «Измерения для событий метрик пользовательской сессии» и «Измерения для событий метрик действий пользователя»
filters Указывает фильтры.
filter.fieldName Указывает имя поля фильтра. См. «Фильтры для событий метрик пользовательской сессии» и «Фильтры для событий метрик действий пользователя»
filter.operator Указывает оператора. EQUALS, NOT_EQUAL, IS_NULL, IS_NOT_NULL, LIKE, LESS_THAN, LESS_THAN_OR_EQUAL_TO, GREATER_THAN, GREATER_THAN_OR_EQUAL_TO
filter.value Предоставляет второй аргумент для бинарных операторов (таких как EQUALS или GREATER_THAN).

Поддерживаемые значения, размеры и фильтры

Значения для событий метрик пользовательской сессии

  • В качестве значения поддерживаются только поля пользовательской сессии. Поля действий пользователя в качестве значения не поддерживаются.
  • Все имена полей должны совпадать с именами полей USQL.
  • Префикс usersession. в названии поля необязателен. Например, usersession.duration и duration означают одно и то же.
  • Если в заданном поле содержится значение null, метрика игнорируется, но Ключ-АСТРОМ использует самодиагностику для выявления таких случаев.

Поддерживаемые поля:

  • duration
  • numberOfRageClicks
  • numberOfRageTaps
  • totalErrorCount
  • totalLicenseCreditCount
  • userActionCount
  • longProperties.* (любое пользовательское свойство типа long, например, longProperties.outerwidth)
  • doubleProperties.* (любое пользовательское свойство типа double, например, doubleProperties.revenue)

Размеры для событий метрик пользовательской сессии

  • Поддерживаются как поля пользовательской сессии, так и поля действий пользователя. Поддержка полей действий пользователя начинается с версии Ключ-АСТРОМ 1.234.
  • Все имена полей должны совпадать с именами полей USQL.
  • Для имени поля пользовательской сессии префикс usersession. является необязательным. При обработке метрики префикс usersession. отбрасывается.
  • Для имени поля действия пользователя префикс useraction. является обязательным. При обработке метрики префикс useraction. сохраняется.
  • К пользовательской метрике одной пользовательской сессии можно добавить до 10 измерений.
  • Если поле, настроенное как измерение, содержит строку null, Ключ-АСТРОМ использует эту строку null в качестве значения измерения.
  • Если вы используете useraction.application как измерение, и пользовательская сессия охватывает несколько приложений, значение пользовательской метрики пользовательской сессии записывается для каждого приложения. Чтобы избежать двойного учета значения, разделите метрику по приложениям.

Поля пользовательской сессии, поддерживаемые в качестве измерений:

  • appVersion, applicationType, bounce, browserFamily, browserMajorVersion, browserType, carrier, region, continent, country, connectionType, device, displayResolution, endReason, hasCrash, hasError, hasSessionReplay, manufacturer, networkTechnology, newUser, osFamily, osVersion, reasonForNoSessionReplay, reasonForNoSessionReplayMobile, rootedOrJailbroken, screenHeight, screenOrientation, screenWidth, userExperienceScore, userType, stringProperties.* (любое пользовательское строковое свойство, используйте поля с низкой кардинальностью).

Поля действий пользователя, поддерживаемые в качестве измерений:

  • useraction.application (поддерживается начиная с версии Ключ-АСТРОМ 1.234)

Фильтры для событий метрик пользовательских сессий

  • Поддерживаются как поля пользовательской сессии, так и поля действий пользователя.
  • Все имена полей должны совпадать с именами полей USQL.
  • Для имени поля пользовательской сессии префикс usersession. необязателен.
  • Для имени поля действия пользователя префикс useraction. является обязательным.
  • При добавлении нескольких фильтров все они должны совпадать — фильтры объединяются с помощью AND.
  • Фильтры, использующие поле «Действие пользователя», требуют наличия хотя бы одного действия пользователя для сопоставления. Сопоставление действий пользователя осуществляется с помощью ANY.
  • Для одной пользовательской сессии можно настроить до 10 фильтров по пользовательской метрике.

Поля пользовательской сессии, поддерживаемые в качестве фильтров:

  • appVersion, applicationType, bounce, browserFamily, browserMajorVersion, browserMonitorName, browserType, carrier, city, region, continent, country, connectionType, device, displayResolution, duration, endReason, hasCrash, hasError, hasSessionReplay, ip, isp, manufacturer, networkTechnology, newUser, numberOfRageClicks, osFamily, osVersion, reasonForNoSessionReplay, reasonForNoSessionReplayMobile, rootedOrJailbroken, screenHeight, screenOrientation, screenWidth, totalErrorCount, totalLicenseCreditCount, userActionCount, userExperienceScore, userId, userType, longProperties.*, doubleProperties.*, stringProperties.* (любое пользовательское свойство типа long, double или string).

Поля действий пользователя, поддерживаемые в качестве фильтров:

  • useraction.apdexCategory, useraction.application, useraction.cdnBusyTime, useraction.cdnResources, useraction.customErrorCount, useraction.domCompleteTime, useraction.domContentLoadedTime, useraction.documentInteractiveTime, useraction.domain, useraction.duration, useraction.firstInputDelay, useraction.firstPartyBusyTime, useraction.firstPartyResources, useraction.frontendTime, useraction.hasCrash, useraction.internalApplicationId, useraction.internalKeyUserActionId, useraction.javascriptErrorCount, useraction.keyUserAction, useraction.largestContentfulPaint, useraction.name, useraction.networkTime, useraction.requestErrorCount, useraction.serverTime, useraction.speedIndex, useraction.targetUrl, useraction.thirdPartyBusyTime, useraction.thirdPartyResources, useraction.type, useraction.visuallyCompleteTime.

Значения для событий метрик действий пользователя

  • В качестве значений поддерживаются поля "Пользовательская сессия" и "Пользовательские действия".
  • Все имена полей должны совпадать с именами полей USQL.
  • Для полей действий пользователя префикс useraction. необязателен.
  • Для полей пользовательской сессии префикс usersession. обязателен.
  • Если в заданном поле содержится значение null, метрика игнорируется.

Поля действий пользователя, поддерживаемые в качестве значений:

  • speedIndex, duration, networkTime, serverTime, frontendTime, documentInteractiveTime, firstPartyResources, firstPartyBusyTime, thirdPartyResources, thirdPartyBusyTime, cdnResources, cdnBusyTime, domCompleteTime, domContentLoadedTime, loadEventStart, loadEventEnd, visuallyCompleteTime, requestStart, responseStart, responseEnd, userActionPropertyCount, customErrorCount, javascriptErrorCount, requestErrorCount, largestContentfulPaint, firstInputDelay, totalBlockingTime (устаревший), cumulativeLayoutShift, longProperties.*, doubleProperties.* (любое пользовательское свойство типа long или double).

Поля пользовательской сессии, поддерживаемые в качестве значений:

  • usersession.duration, usersession.numberOfRageClicks, usersession.numberOfRageTaps, usersession.totalErrorCount, usersession.totalLicenseCreditCount, usersession.userActionCount, usersession.longProperties.*, usersession.doubleProperties.* (любое пользовательское свойство типа long или double).

Размеры для событий метрик действий пользователя

  • Поддерживаются как поля пользовательской сессии, так и поля действий пользователя.
  • Все имена полей должны совпадать с именами полей USQL.
  • Для полей действий пользователя префикс useraction. является необязательным. При обработке метрики префикс useraction. отбрасывается.
  • Для полей пользовательской сессии префикс usersession. обязателен. При обработке метрики префикс usersession. сохраняется.
  • Для пользовательской метрики действий пользователя можно указать до 4 измерений, но только 2 из них могут быть измерениями с высокой кардинальностью.
  • Если поле содержит строку null, она используется как значение измерения.

Поля действий пользователя, поддерживаемые в качестве измерений:

  • application, hasCrash, type, apdexCategory, internalApplicationId, internalKeyUserActionId, keyUserAction, isEntryAction, isExitAction, stringProperties.* (любое пользовательское строковое свойство, используйте поля с низкой кардинальностью).

Поля пользовательской сессии, поддерживаемые в качестве измерений:

  • usersession.appVersion, usersession.applicationType, usersession.bounce, usersession.browserFamily, usersession.browserMajorVersion, usersession.browserType, usersession.carrier, usersession.region, usersession.continent, usersession.country, usersession.connectionType, usersession.device, usersession.displayResolution, usersession.endReason, usersession.hasCrash, usersession.hasError, usersession.hasSessionReplay, usersession.manufacturer, usersession.networkTechnology, usersession.newUser, usersession.osFamily, usersession.osVersion, usersession.reasonForNoSessionReplay, usersession.reasonForNoSessionReplayMobile, usersession.rootedOrJailbroken, usersession.screenHeight, usersession.screenOrientation, usersession.screenWidth, usersession.userExperienceScore, usersession.userType, usersession.stringProperties.* (любое пользовательское строковое свойство).

Фильтры для событий метрик действий пользователей

  • Поддерживаются как поля пользовательской сессии, так и поля действий пользователя.
  • Все имена полей должны совпадать с именами полей USQL.
  • Для полей действий пользователя префикс useraction. необязателен.
  • Для полей пользовательской сессии префикс usersession. обязателен.
  • При добавлении нескольких фильтров они объединяются с помощью AND.
  • Для одной метрики действий пользователя можно настроить до 10 фильтров.

Поля действий пользователя, поддерживаемые в качестве фильтров:

  • apdexCategory, application, cdnBusyTime, cdnResources, customErrorCount, cumulativeLayoutShift, domCompleteTime, domContentLoadedTime, documentInteractiveTime, domain, duration, firstInputDelay, firstPartyBusyTime, firstPartyResources, frontendTime, hasCrash, internalApplicationId, internalKeyUserActionId, isEntryAction, isExitAction, javascriptErrorCount, keyUserAction, largestContentfulPaint, loadEventStart, loadEventEnd, name, networkTime, requestErrorCount, requestStart, responseStart, responseEnd, serverTime, speedIndex, targetUrl, thirdPartyBusyTime, thirdPartyResources, totalBlockingTime (устаревший), type, userActionPropertyCount, visuallyCompleteTime, syntheticEvent, longProperties.*, doubleProperties.*, stringProperties.*.

Поля пользовательской сессии, поддерживаемые в качестве фильтров:

  • usersession.appVersion, usersession.applicationType, usersession.bounce, usersession.browserFamily, usersession.browserMajorVersion, usersession.browserMonitorName, usersession.browserType, usersession.carrier, usersession.city, usersession.region, usersession.continent, usersession.country, usersession.connectionType, usersession.device, usersession.displayResolution, usersession.duration, usersession.endReason, usersession.hasCrash, usersession.hasError, usersession.hasSessionReplay, usersession.ip, usersession.isp, usersession.manufacturer, usersession.networkTechnology, usersession.newUser, usersession.numberOfRageClicks, usersession.numberOfRageTaps, usersession.osFamily, usersession.osVersion, usersession.reasonForNoSessionReplay, usersession.reasonForNoSessionReplayMobile, usersession.rootedOrJailbroken, usersession.screenHeight, usersession.screenOrientation, usersession.screenWidth, usersession.totalErrorCount, usersession.totalLicenseCreditCount, usersession.userActionCount, usersession.userExperienceScore, usersession.userId, usersession.userType, usersession.longProperties.*, usersession.doubleProperties.*, usersession.stringProperties.*.

Известные ограничения

  • В каждой среде можно создать до 500 пользовательских метрик для каждой сессии.
  • В каждой среде можно создать до 100 пользовательских метрик, отслеживающих действия пользователей.
  • Синтетические данные пользовательских сессий не учитываются при расчете значений метрик событий USQL; включаются только данные реальных пользователей.
  • Ключ-АСТРОМ обновляет события метрик USQL каждый раз, когда сессия закрывается. Это означает, что данные о текущей сессии не учитываются в значениях пользовательских метрик USQL; включаются только данные о закрытых сессиях.
  • Ключевое слово DISTINCT, используемое в USQL, не поддерживается. Если у вас есть запрос, подобный SELECT COUNT(DISTINCT country) from usersession, создать эквивалентную пользовательскую метрику USQL невозможно.

Учебное пособие

Шаг 1. Создайте метрику

Используя веб-интерфейс Ключ-АСТРОМ, создадим пользовательскую метрику «Средняя продолжительность сеанса пользователя» (USCM) на основе данных о сеансах реальных пользователей. Метрика будет включать два измерения для сегментации данных о сеансах по семейству браузеров и основным версиям браузеров. Затем, используя эту метрику, создадим диаграмму, закрепим ее на панели мониторинга и создадим пользовательское событие для метрики, чтобы получать оповещения, когда значение метрики превысит заданный порог.

  1. Перейдите в Настройки > Веб- и мобильный мониторинг > События метрик пользовательских сессий.
  2. Выберите Добавить элемент.
  3. Введите uscm.average_duration_of_sessions_by_browser_family_and_version в качестве ключа метрики.
  4. В разделе Тип извлекаемого значения выберите Значение поля пользовательской сессии и задайте имя поля duration.
  5. Выберите Добавить измерение и добавьте измерения browserFamily и browserMajorVersion.
  6. В разделе Добавить фильтр укажите следующие фильтры:
    • userType = REAL_USER (Имя поля: userType, Оператор: equals, Значение: REAL_USER)
    • useraction.application = www.easytravel.com (Имя поля: useraction.application, Оператор: equals, Значение: www.easytravel.com). Вместо значения www.easytravel.com можно использовать имя собственного приложения.
  7. Выберите Сохранить изменения.

Теперь у вас есть настраиваемая метрика пользовательской сессии, которая извлекается как поле (duration) только тогда, когда useraction.application равно www.easytravel.com (фильтрация для конкретного приложения) и userType равно REAL_USER (фильтрация только для реальных пользователей). Кроме того, вы добавили два измерения, которые позволяют разделять данные на основе семейства браузеров или основной версии браузера.

Шаг 2. Создайте и закрепите диаграмму

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

  1. Перейдите в Визуализацию данных.
  2. Выберите метрику uscm.average_duration_of_sessions_by_browser_family_and_version и нажмите Выполнить запрос.
  3. С помощью Визуализации данных разделите собранные данные, чтобы увидеть данные пользовательской сессии, разбитые по browserMajorVersion, browserFamily или по обоим факторам.
  4. Фильтруйте данные пользовательских сессий на основе определенных критериев browserMajorVersion или browserFamily, чтобы сосредоточиться на интересующих данных.
  5. После создания диаграммы закрепите ее на панели мониторинга: выберите Закрепить на панели мониторинга, выберите одну из ваших панелей мониторинга и введите название плитки.

Шаг 3. Создайте оповещение

  1. Перейдите в Настройки > Обнаружение аномалий > События метрик.
  2. Выберите Добавить событие метрики.
  3. Создайте событие метрики на основе метрики uscm.average_duration_of_sessions_by_browser_family_and_version. Подробности см. в разделе «События метрик».

Часто задаваемые вопросы

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

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

Почему результаты моих запросов к USQL не соответствуют событиям метрик USQL? Синтетические данные пользовательских сессий не учитываются в метрических событиях USQL. Исключите синтетические сессии из запроса. Также убедитесь, что к запросу и метрике применяется один и тот же временной интервал.

Как осуществляется выставление счетов за события метрик USQL? Начиная с версии Ключ-АСТРОМ 1.232, события метрик USQL регулируются лицензией Davis Data Unit (DDU). Эти метрики позиционируются как обычные бессхемные метрики. Для оценки стоимости по каждому показателю анализируются сессии за последние 7 дней, и стоимость в DDU на каждый показатель рассчитывается в соответствии с ожидаемым объемом входящих данных в минуту.

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

Источник — https://doc.ruscomtech.ru/index.php?title=Создание_пользовательских_метрик_USQL_для_веб-приложений&oldid=6409