Настройка автоматического внедрения

Материал из Документация Ключ-АСТРОМ
Версия от 18:18, 11 марта 2026; IKuznetsov (обсуждение | вклад) (Новая страница: «После развертывания ЕдиногоАгента в режиме полнофункционального мониторинга на хосте,...»)
(разн.) ← Предыдущая | Текущая версия (разн.) | Следующая → (разн.)

После развертывания ЕдиногоАгента в режиме полнофункционального мониторинга на хосте, он по умолчанию автоматически внедряет JavaScript RUM в HTML ваших веб-приложений для технологий, перечисленных в разделе Техническая поддержка — Мониторинг реальных пользователей — Веб-серверы и приложения. Для запуска внедрения просто перезапустите процессы веб-сервера после установки ЕдиногоАгента.

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

JavaScript-код RUM отвечает за сбор данных RUM из веб-браузеров ваших клиентов. Он отправляет эти данные в виде XHR POST-запросов на конечную точку маяка, которая выполняет первоначальную проверку перед пересылкой данных в ваш кластер Ключ-АСТРОМ. В сценариях автоматического внедрения конечная точка маяка по умолчанию предоставляется ЕдинымАгентом, который отслеживает работу вашего веб-сервера или сервера приложений, но возможны и альтернативные настройки (см. раздел Настройка конечной точки маяка для веб-приложений).

Внедряемые в HTML-код вашего приложения фрагменты JavaScript RUM могут иметь различный формат, каждый из которых разработан для удовлетворения конкретных требований, описанных в разделе Выбор формата фрагмента. Чтобы настроить формат, используемый для автоматической внедрения, см. раздел Настройка формата фрагмента.

ЕдиныйАгент внедряет JavaScript-код RUM на каждую страницу в зависимости от текущей конфигурации всякий раз, когда инструментированный веб-сервер или сервер приложений доставляет страницу. Однако политика кэширования страницы определяет, как часто ЕдиныйАгент имеет возможность выполнять это внедрение. Для решения этой проблемы ЕдиныйАгент включает функцию, которая оптимизирует заголовки управления кэшированием. Подробную информацию о работе этой функции и ее ограничениях см. в разделе Оптимизация заголовков управления кэшированием (ниже).

Если у вас нет доступа к веб-серверу, на котором размещено ваше приложение, и, следовательно, вы не можете установить ЕдиныйАгент, вы можете отслеживать работу своего приложения с помощью RUM без агента.

Встроенные правила для автоматического внедрения

ЕдиныйАгент обнаруживает ответы, содержащие HTML-контент, и внедряет JavaScript-код RUM в раздел <head> каждой страницы. Он не изменяет другие ресурсы, такие как изображения, файлы CSS, документы JSON или XML, а также обычный текст.

ЕдиныйАгент пытается внедрить JavaScript-код RUM в качестве первого скрипта на странице, что помогает обеспечить надежные результаты мониторинга. Внедрение работает только с корректным HTML-кодом, соответствующим основным рекомендациям — например, обеспечивающим правильное открытие и закрытие всех элементов. ЕдиныйАгент использует встроенные правила, указанные ниже, для определения наиболее подходящего места в HTML-документе для внедрения JavaScript-кода RUM.

Спецификация правил автоматического внердения

Название Состояние Действие Отмена
<!DOCTYPE> Тег <!DOCTYPE> не <!DOCTYPE html> Прервать выполнение и отменить внедрение. Обратите внимание, что допускается только одно объявление типа документа (Doctype).
initial tag Перед этим появляется тег <html>, который не относится к следующим:
  • <!DOCTYPE ...>
  • <html>
  • <link>
  • <meta>
  • <script>
  • <style>
 Прервать внедрение.
<?xml?> Встречается спецификация <?xml ...?>. Проигнорируйте это и продолжайте просматривать документ. non-<meta> tag

non-<head> tag

initial tag

<html> tag Обнаружен тег <html>. Если потенциальная точка внедрения обнаружена раньше, сделайте внедрение в это место и не проводите дальнейшее сканирование. Если потенциальных точек внедрений несколько, используйте самую раннюю из них.

В противном случае продолжайте сканирование документа.

<script src> tag Внутри <script src="..."> находится тег <head>. Если потенциальная точка внедрения обнаружена раньше, сделайте внедрение в это место и не проводите дальнейшее сканирование. Если потенциальных точек внедрений несколько, используйте самую раннюю из них.

В противном случае, выполните внедение перед тегом <script> и не выполняйте дальнейшее сканирование.

non-<meta> tag

<base>/<meta> tag

<title>/<noscript> tag Встречается тег «<title> или <noscript>». Игнорируйте все, кроме метки </title> или тега </noscript>, затем продолжайте сканирование документа. <body> tag
<base>/<meta> tag Встречается либо тег <base>, либо метка <meta>. Удалите все обнаруженные ранее точки условного внедрения. Продолжайте сканирование документа. any conditional injection point found earlier by:

non-<meta> tag

unclosed <meta>

non-<head> tag

non-<meta> tag Внутри находится тег <head>, который не является ни <meta>, ни <title>. Внедрение перед условным внедрением.

Продолжайте сканирование документа на случай, если этот вариант внедрения будет отменен.

unclosed <meta> Тег </head> появляется после тега <meta>, который не закрывается ни закрывающим тегом </meta>, ни тегом XML <meta ... />. Затем следует добавление </meta> и внедрение, обе процедуры предшествуют </head> (условному внедрению).

Продолжайте сканирование документа на случай, если этот вариант внедрения будет отменен.

comment Обнаружен тег <!- comment ->. Проигнорируйте это и продолжайте просматривать документ. non-<meta> tag

non-<head> tag

non-<head> tag Тег находится после <html>, но перед <head>, что не является ни <head>, ни <body>. Внедрение перед условным внедрением.

Продолжайте сканирование документа на случай, если этот вариант внедрения будет отменен.

</head> tag Обнаружен тег </head>. Если потенциальная точка внедрения обнаружена раньше, сделайте внедрение в это место и не проводите дальнейшее сканирование. Если потенциальных точек внедрений несколько, используйте самую раннюю из них.

В противном случае, продолжайте сканирование документа.

flush Только Java

Запрос подается на поток ввода/записи за пределами секции <head></head>, и условный ввод ожидает подтверждения.

Удалите условную точку внедрения, распространите сброс и продолжите сканирование документа для поиска новой точки внедрения. any conditional injection point found before by:

non-<head> tag

flush in <head> Только Java

Выполняется запрос ввода/записи внутри системы <head></head>, и условный ввод ожидает подтверждения.

Удерживайте точку ввода и продолжайте сканирование документа.
<body> tag Обнаружен тег <body>. Сканирование документа прекращается. Используется любая из ранее обнаруженных потенциальных точек внедрения. Если потенциальных точек внедрения несколько, используется самая ранняя.

Если ранее не было найдено подходящего правила, добавьте его после <body>.

end of file Достигнут конец файла, и сканирование не завершилось до этого момента. Не делайте внедрение. any conditional injection point found before by:

non-<meta> tag

unclosed <meta>

non-<head tag

parse error Содержимое документа, по всей видимости, не демонстрирует базовой структуры, ожидаемой от HTML-тегов и атрибутов. Сканирование документа прекращается.

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

Если ни одно правило не предусматривает более раннюю точку внедрения, не выполняйте внедрение.

Укажите, куда следует внедрить JavaScript-код RUM

В некоторых случаях ЕдиныйАгент может быть не в состоянии выполнить внедрение кода с помощью встроенных правил. Обычно это происходит из-за некорректного HTML-кода, хотя в редких случаях набор правил также может препятствовать определению подходящей точки внедрения. В таких сценариях можно добиться автоматического внедрения, определив пользовательское правило внедрения, которое явно указывает, куда следует внедрить JavaScript RUM в HTML-документе.

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

  1. Перейдите в Веб-приложения.
  2. Выберите приложение, которое хотите настроить.
  3. В правом верхнем углу страницы обзора приложения выберите Дополнительно ( … ) > Редактировать.
  4. В настройках приложения выберите Внедрение > Пользовательские правила внедрения.
  5. В разделе Определение пользовательских правил внедрения выберите Добавить пользовательское правило.
  6. Определите оператор и, при необходимости, соответствующий шаблон URL-адреса, чтобы контролировать, к каким страницам применяется ваше пользовательское правило внедрения.
  7. В разделе Правило выберите либо Перед определенным HTML-кодом, либо После определенного HTML-кода и введите соответствующий HTML-шаблон.
  8. Выберите Сохранить изменения, чтобы создать пользовательское правило внедрения.

Отключить внедрение кода для отдельных страниц

Чтобы отключить внедрение зависимостей для одной или нескольких страниц вашего приложения

  1. Перейдите в Веб-приложения.
  2. Выберите приложение, которое хотите настроить.
  3. В правом верхнем углу страницы обзора приложения выберите Дополнительно ( … ) > Редактировать.
  4. В настройках приложения выберите Внедрение > Пользовательские правила внедрения.
  5. В разделе Определение пользовательских правил внедрения выберите Добавить пользовательское правило.
  6. Определите оператор и, при необходимости, соответствующий шаблон URL-адреса, чтобы контролировать, к каким страницам применяется ваше пользовательское правило внедрения.
  7. В разделе Правило выберите Не внедрять.
  8. Выберите Сохранить изменения, чтобы создать пользовательское правило внедрения.

Это правило отключает только оптимизацию заголовков внедрения и управления кэшем; оно не отключает функциональность RUM полностью. Например, файлы cookie могут по-прежнему устанавливаться. Если вы ищете способ выборочного включения RUM, обратитесь к инструкциям в разделе Выборочное внедрение RUM для ваших приложений.

Настройте формат фрагмента

Для настройки формата фрагмента кода для автоматической инъекции

  1. Перейдите в Веб-приложения.
  2. Выберите приложение, которое хотите настроить.
  3. В правом верхнем углу страницы обзора приложения выберите Дополнительно ( … ) > Редактировать.
  4. В настройках приложения выберите Ввод > Автоматический ввод.
  5. В разделе Формат фрагмента выберите нужный формат.

Чтобы узнать больше о различных форматах фрагментов текста, см. раздел Выбор формата фрагмента.

Оптимизация заголовков управления кэшем

🟢 Включено по умолчанию

Политика кэширования вашего приложения напрямую влияет на то, как часто ЕдиныйАгент может внедрять JavaScript RUM на страницу, используя текущую конфигурацию. Для обеспечения своевременного применения изменений конфигурации функция оптимизации заголовков управления кэшированием изменяет HTTP-заголовки таким образом, что условные запросы приводят к промаху кэша всякий раз, когда изменяется конфигурация RUM, предоставляя ЕдиномуАгенту возможность внедрения. Подробная информация об этих оптимизациях и конкретных изменениях заголовков приведена ниже.

Спецификация оптимизации заголовка управления кэшем

Когда включена оптимизация заголовка управления кэшированием и изменена конфигурация RUM, запросы, которые в противном случае привели бы к ошибке, возвращают 304 Not Modifiedответ 200 OK, предоставляя ЕдиномуАгенту возможность внедрить JavaScript RUM в HTML-код вашего приложения. Если конфигурация RUM не изменена, запросы приводят к ответу 304 Not Modified.

Измененные заголовки

ЕдиныйАгент изменяет следующие заголовки ответа и запроса:

Заголовки ответа
  • ETag
  • Last-Modified
Заголовки запроса
  • If-None-Match
  • If-Modified-Since
  • If-Unmodified-Since1
  • If-Match1

1 Не адаптировано для запросов на определение дальности действия, которые, как правило, исключаются из мониторинга RUM.

Вот как ЕдиныйАгент изменяет заголовки управления кэшированием.

При изменении конфигурации RUM
  • Входящие заголовки If-None-Match и заголовки запроса If-Modified-Since удаляются.
  • Изменения If-Unmodified-Since, внесенные в заголовки If-Match, удаляются.
  • При использовании обоих заголовков ETag и Last-Modified:
    • К заголовку добавляется суффикс ETag.
    • Из заголовка вычитается одна секунда Last-Modified.
  • Если используется только заголовок ETag:
    • К заголовку добавляется суффикс ETag.
  • Если используется только заголовок Last-Modified:
    • Заголовок ETag создан.
    • Из заголовка вычитается одна секунда Last-Modified.
Если конфигурация RUM не изменена
  • Перед обработкой запроса веб-сервером или сервером приложения внесенные в заголовки изменения удаляются, чтобы веб-сервер или сервер приложения не увидел эти изменения.

Когда приложение состоит из нескольких уровней, в которые внесены изменения, изменения в ETag и Last-Modified применяются к каждому уровню.

ЕдиныйАгент не изменяет заголовки Expires и Cache-Control, которые явно определяют время истечения срока действия ресурсов. Для обеспечения своевременных обновлений мы рекомендуем устанавливать более короткие сроки истечения срока действия в этих заголовках.

Отключение оптимизации заголовка управления кэшем

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

Чтобы отключить оптимизацию заголовка управления кэшированием

  1. Перейдите в Веб-приложения.
  2. Выберите приложение, которое хотите настроить.
  3. В правом верхнем углу страницы обзора приложения выберите Дополнительно ( … ) > Редактировать.
  4. В настройках приложения выберите Ввод > Автоматический ввод.
  5. Отключите параметр Оптимизировать значение заголовков управления кэшированием для использования с мониторингом реальных пользователей Ключ-АСТРОМ.
  6. Выберите Сохранить изменения.

Отключение оптимизации заголовков управления кэшированием для ресурсов, не являющихся HTML-файлами

В некоторых случаях ЕдиныйАгент может изменять заголовки управления кэшированием для ресурсов, не являющихся HTML-файлами. Это происходит потому, что изменения заголовков применяются до того, как можно определить точный тип контента. Хотя ЕдиныйАгент исключает определенные ресурсы из оптимизации заголовков управления кэшированием на основе их суффикса URI, учесть все типы контента, не являющиеся HTML-файлами, невозможно.

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

Используйте ручную вставку для страниц приложения с автоматическим внедрением

Если ЕдиныйАгент развернут в ваших группах процессов и для вашей технологии поддерживается автоматическое внедрение, то ЕдиныйАгент по умолчанию автоматически внедряет JavaScript RUM. Но если вы предпочитаете, вы можете вместо этого внедрить его вручную на все или определенные страницы.

Сначала необходимо отключить автоматическое внедрение, как описано в разделе «Отключение внедений для определенных страниц (выше)». Затем, чтобы внедрить JavaScript RUM вручную, необходимо сделать:

  1. Перейдите в Веб-приложения.
  2. Выберите приложение, которое хотите настроить.
  3. В правом верхнем углу страницы обзора приложения выберите Дополнительно ( … ) > Редактировать.
  4. В настройках приложения выберите Внедрение > Внедрение вручную.
  5. Выберите необходимый формат фрагмента и скопируйте предоставленный фрагмент.
  6. Вставьте этот фрагмент кода в свой HTML-код перед любыми другими скриптами.

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

Источник — https://doc.ruscomtech.ru/index.php?title=Настройка_автоматического_внедрения&oldid=6301