Сборщик — это не агент и не программа, которую устанавливают на сервер. Сборщик — это способ, при котором приложение клиента само отправляет в Pinguva короткую запись о том, что запрос к API был обработан.
Простыми словами:
- пользователь создает токен сборщика в Pinguva;
- разработчик клиента добавляет этот токен в серверную часть продукта;
- после обработки API-запроса сервер клиента отправляет в Pinguva короткую сводку: путь метода, статус, время обработки, источник и признак ошибки;
- Pinguva строит понятные карточки, таблицу и уведомления.
Linux-агент для этого сценария не нужен. Нужен небольшой код в приложении клиента, промежуточном слое или API-шлюзе.
Сборщик нужен, если важно видеть не только контрольный запрос Pinguva, но и реальную работу пользователей и внешних систем:
- сколько запросов принято;
- сколько ответов завершилось ошибкой;
- какой источник создаёт основную нагрузку;
- какой метод начал отвечать заметно медленнее;
- появились ли бизнес-ошибки при формально успешном HTTP-ответе.
Для подключения:
- Откройте
Интеграции и API. - Нажмите
Мониторинг бизнес-API. - Внизу раскройте
Настройки подключения. - Найдите карточку
Токен сборщика. - Если токена ещё нет, нажмите
Создать токен сборщика. - Скопируйте токен или готовый пример сразу после создания.
- Передайте токен разработчику, который обслуживает приложение.
- Разработчик добавляет отправку коротких событий в серверную часть продукта, промежуточный слой или API-шлюз.
Куда добавлять токен:
- в серверную часть приложения, промежуточный слой, API-шлюз или SDK, который видит реальные запросы к API;
- в HTTP-заголовок отправки событий:
Authorization: Bearer <токен сборщика>; - не в публичную часть сайта, не в браузер пользователя и не в открытый JavaScript-код.
Почему токен нельзя вставлять в браузер: пользователь может открыть исходный код страницы и увидеть токен. После этого любой человек сможет отправлять в Pinguva ложные события от имени клиента.
Полное значение токена показывается только один раз. Pinguva хранит только его хеш и короткую маску. Если токен потерян, перевыпустите его: прежнее значение сразу перестанет работать. После перевыпуска токен нужно заменить во всех приложениях, сервисах и устройствах, которые отправляют события в Pinguva.
Пример события:
json { "events": [ { "path": "/api/order.create", "method": "POST", "statusCode": 200, "latencyMs": 142, "caller": "mobile-app", "sourceIp": "203.0.113.10", "businessError": false } ] }
События отправляются в:
text POST /api/business-api/ingest Authorization: Bearer bapi_example
Короткий пример для разработчика:
javascript await fetch("https://app.pinguva.com/api/business-api/ingest", { method: "POST", headers: { "Authorization": "Bearer bapi_ваш_токен", "Content-Type": "application/json" }, body: JSON.stringify({ events: [ { path: "/api/order.create", method: "POST", statusCode: 200, latencyMs: 142, caller: "mobile-app", businessError: false } ] }) });
Этот пример не нужно копировать в сайт или личный кабинет клиента. Его добавляют только в серверный код продукта, где обрабатываются API-запросы.
Сборщику не нужно отправлять:
- тело запроса;
- тело ответа;
- персональные данные;
- пароли и токены клиента;
- произвольные журналы приложения.
Параметры после ? в адресе запроса не сохраняются, чтобы случайно не передавать секреты и персональные данные. IP источника можно передать только если это осознанно разрешено политикой клиента. В текущей аналитике Pinguva по умолчанию использует поле caller и не требует сырой IP-адрес.
Подробная документация для разработчиков и готовые примеры кода сборщика:
- [Документация сборщика API](https://github.com/pinguvacom/pinguva-agent/blob/main/docs/ru/API_COLLECTOR_INTEGRATION.md)
- [Примеры кода сборщика](https://github.com/pinguvacom/pinguva-agent/tree/main/examples/business-api-collector)
Если HTTP-ответ успешный, но бизнес-операция завершилась ошибкой, можно передать:
json { "businessError": true, "businessCode": "order_validation_failed" }