Введение в API отчетов веб-приложений

Как разработчики могут исправить ошибки и повысить производительность приложений с помощью Reporting API

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

Reporting API — один из наиболее часто используемых механизмов отчетности для веб-приложений, и в этой статье мы подробно обсудим Reporting API, чтобы дать вам лучшее понимание.

Что такое API отчетов?

Reporting API предоставляет единый метод отчетности для всех ваших веб-сайтов, чтобы сообщать о потенциальных нарушениях, таких как нарушения CSP, предупреждения об устаревании и ведение журнала сетевых ошибок.

Он предоставляет согласованные отчеты в виде объектов JavaScript, чтобы помочь разработчикам исправлять ошибки и повышать производительность приложений. Существует 2 основных метода создания отчетов с использованием Reporting API.

1. Отправка отчетов через браузер

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

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

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

Если у вас возникли проблемы с просмотром отчетов на вашем сервере, перейдите на chrome:/net-internals/#reporting. Там вы можете перепроверить, все ли настроено правильно и отчеты отправляются точно.

2. Создание отчетов через WebDriver

Спецификация Reporting API определяет расширение WebDriver для создания тестового отчета, которое позволяет имитировать создание отчетов во время автоматизации. Отчеты, сгенерированные через WebDriver, наблюдают любые зарегистрированные ReportObserver объекты, присутствующие на загруженном веб-сайте.

Механизмы отчетности / конечные точки

Конечная точка — это указанное место, обычно URL-адрес, из которого мы можем получать отчеты. У одной конечной точки есть имя (обычно текст ASCII), URL-адрес и неотрицательное целое число, представляющее количество неудачных запросов. Ниже приведены 2 наиболее часто используемых механизма отчетности.

отчет в заголовок

report-to — это новый HTTP-заголовок, представленный Reporting API. Он используется для указания информации о различных конечных точках для доставки отчетов. Затем отчеты можно получить, запросив эти URL-адреса.

В большинстве случаев политики используют разные заголовки. Таким образом, может быть сложно получить правильный синтаксис report-to. В зависимости от политики правильный синтаксис может быть report-to=main-endpoint или report-to main-endpoint.

После того, как вы настроили заголовок конечных точек отчетов, добавьте директиву report-to к каждому заголовку политики, для которой вы хотите получать отчеты о нарушениях. Вы можете использовать несколько конечных точек для нескольких политик или разные конечные точки для разных политик.

Report-To: {
             "max_age": 100,
             "endpoints": [{
               "url": "https://data.exmp/main"
             }]

Сообщение о наблюдателях

ReportingObserver — это API JavaScript, который может обнаруживать и сообщать о простых предупреждениях на стороне клиента, таких как устаревание и вмешательство.

Объект ReportingObserver создается с помощью конструктора ReportingObserver(), передающего в качестве параметров словарь параметров (позволяет указать категорию отчета) и функцию обратного вызова.

const ReportObserver = new ReportingObserver((reports, observer) => {
  for (const report of reports) {
    // Sending reports.
  }
}, {buffered: true});
ReportObserver.observe();

Отчеты не доставляются на сервер по умолчанию (если вы не укажете это в обратном вызове). Поэтому ReportingObserver не может обнаруживать более важные проблемы, такие как нарушения CSP и сетевые ошибки.

Хотя заголовки ReportingObserver и report-to перекрываются, они обеспечивают существенно разные варианты использования. По сравнению с ReportingObserver, заголовок report-to может уловить больше сообщений об ошибках (сеть, CSP, сбои браузера).

Итак, если вы хотите автоматически сообщать об ошибках или фиксировать ошибки, которые невозможно просмотреть в JavaScript, это идеальное решение.

Как выглядят отчеты?

Браузер использует запрос POST для отправки отчетов. Он содержит заголовок Content-Type: application/reports+json, а тело запроса содержит массив захваченных ошибок.

POST
Content-Type: application/reports+json

Вот данные, которые вы можете найти в отчетах:

Пример отчета

{"age": 20,"body": {"columnNumber": 12,"disposition": "enforce","lineNumber": 11,"message": "CSP VIOLATION","policyId": "csp-violation","sourceFile": "https://demo.site/script.js"},"type": "csp-violation","url": "https://demo.site/","user_agent": "Mozilla/5.0... Chrome/92.0.4504.0"}

Типы отчетов

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

1. Отчет о нарушении CSP

Эти отчеты о нарушениях генерируются при нарушении политик безопасности контента. Он содержит документы JSON, которые отправляются на указанный URI через HTTP-запрос POST.

Вот как определяется образец нарушения CSP.

<script src="script.js"></script>
<!-- CSP VIOLATION -->
<script src="https://demo.com/script.js"></script>

2. Отчет об обесценивании

Это указывает на то, что WebAPI или другая функция браузера, используемая на веб-сайте, будет объявлена устаревшей в будущем выпуске. Это указано в свойстве Report.body с возвращаемым значением DeprecationReportBody.

3. Отчет о вмешательстве

Это указывает на то, что браузер отклонил запрос веб-сайта, возможно, из соображений безопасности или раздражения пользователя. Подобно предупреждению об обесценивании, это также указывается в свойстве Report.body с возвращаемым значением InterventionReportBody.

4. Отчет журнала сетевых ошибок

Спецификация Network Error Logging (NEL) определяет механизм сбора сетевых ошибок на стороне клиента из источника. Он использует заголовок ответа HTTP NEL для сбора сетевых ошибок. Но сначала вам нужно определить заголовок Report-To с коллектором.

Report-To: {
    ...
  }, {
    "group": "network-errors",
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://analytics.provider.com/networkerrors"
    }]
  }


GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}

Заключение

В этой статье я обсудил обзор механизмов отчетности Reporting API и представил различные типы отчетов. Хотя он все еще находится на ранней стадии, у него огромный потенциал, поскольку он позволяет создавать отчеты с помощью браузера.

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

Я надеюсь, что вы нашли это полезным. Спасибо за чтение.

Бит: почувствуйте мощь компонентно-ориентированной разработки

Скажи привет Bit. Это инструмент №1 для разработки приложений на основе компонентов.

С помощью Bit вы можете создать любую часть своего приложения в виде «компонента», который можно компоновать и использовать повторно. Вы и ваша команда можете совместно использовать набор компонентов для более быстрой и последовательной совместной разработки большего количества приложений.

Создавайте и компонуйте «строительные блоки приложения»: элементы пользовательского интерфейса, полные функции, страницы, приложения, бессерверные или микросервисы. С любым стеком JS.
С легкостью делитесь и повторно используйте компоненты в команде.
Быстро обновляйте компоненты в разных проектах.
Делайте сложные вещи простыми: Монорепо, дизайн-системы и микрофронтенды.

Попробуйте Bit бесплатно и с открытым исходным кодом→