Loading documentation...
Preparing Ring content
Концепції, цінність і типові сценарії
Концепції, цінність і типові сценарії
Preparing Ring content
Preparing Ring content
Preparing Ring content
Відфільтруйте по Засновник/Розробник у боковому меню документації. Джерела моніторингу — app/api/health, app/api/analytics/*, lib/logger.ts, public/scripts/analytics.js + RingAnalyticsBeacon, і аналітичний UI адміністратора. Окремої сторінки features/analytics немає — ця стаття дає огляд аналітики по всій платформі Ring.
Ring Platform збирає першу сторону телеметрії у таблиці PostgreSQL JSONB, має health endpoint для контейнерів, та структуровані серверні логи. Зовнішній APM (Sentry, Vercel Analytics) інтегрується через змінні середовища, але не обов’язковий для основної роботи.
| Рівень | Механізм | Основний сигнал |
|---|---|---|
| Liveness | GET /api/health (+ HEAD) | Процес живий, попередження щодо оточення, пам’ять |
| UX продуктивність | WebVitalsProvider → POST /api/analytics/web-vitals | LCP, CLS, INP, TTFB, FCP |
| Події продукту | analytics.js + RingAnalyticsBeacon → POST /api/analytics/app | Сесії, завантаження сторінок, кастомні події (analytics_events) |
| Персональні сторінки | recordPersonalPageView → personal_page_view | Унікальні відвідування 24г/7д за ролями на /{username} |
| Клієнтські помилки | POST /api/analytics/errors | Stack trace, компонента, рівень серйозності |
| Панель адміністратора | /admin/analytics | getPlatformAnalytics() включно з personalPages |
| Realtime підключення | /api/tunnel/ping, /api/tunnel/heartbeat | Затримка тунелю / здоров'я сесії |
| Серверні логи | lib/logger.ts | JSON-рядки у stdout (LOG_LEVEL) |
| Опціональна інфраструктура | Docker-профіль monitoring | Prometheus + Grafana (локальний dev) |
Ring-клон поєднує авторизацію, ринкові дані, платежі і сповіщення в реальному часі. Баг часто проявляється як “сайт відкривається, але замовлення не синхронізуються”, а не як червона помилка. Унікальні відвідування персональної сторінки дозволяють зрозуміти, чи отримують власники довіру — при цьому власник сам не накручує собі лічильник.
Використовуйте GET /api/health у балансувальнику навантаження чи онлайн-чекері — якщо 503, це деградація (часто бракує AUTH_SECRET).
Admin → Analytics: кількість користувачів, медіани Web Vitals, останні клієнтські помилки і personalPages (топові профілі, розподіл по ролях).
Той самий workflow: персональна статистика переглядів і пропуск власника.
Наступний крок: відновлення після інцидентів, що помітно через моніторинг.
Див. також: налаштування Web Vitals та performance-операції.
Залежить від: CRON_SECRET, LOG_LEVEL, ANALYTICS_DISABLE_STORAGE, опційний Sentry.
Відфільтруйте по Засновник/Розробник у боковому меню документації. Джерела моніторингу — app/api/health, app/api/analytics/*, lib/logger.ts, public/scripts/analytics.js + RingAnalyticsBeacon, і аналітичний UI адміністратора. Окремої сторінки features/analytics немає — ця стаття дає огляд аналітики по всій платформі Ring.
Ring Platform збирає першу сторону телеметрії у таблиці PostgreSQL JSONB, має health endpoint для контейнерів, та структуровані серверні логи. Зовнішній APM (Sentry, Vercel Analytics) інтегрується через змінні середовища, але не обов’язковий для основної роботи.
| Рівень | Механізм | Основний сигнал |
|---|---|---|
| Liveness | GET /api/health (+ HEAD) | Процес живий, попередження щодо оточення, пам’ять |
| UX продуктивність | WebVitalsProvider → POST /api/analytics/web-vitals | LCP, CLS, INP, TTFB, FCP |
| Події продукту | analytics.js + RingAnalyticsBeacon → POST /api/analytics/app | Сесії, завантаження сторінок, кастомні події (analytics_events) |
| Персональні сторінки | recordPersonalPageView → personal_page_view | Унікальні відвідування 24г/7д за ролями на /{username} |
| Клієнтські помилки | POST /api/analytics/errors | Stack trace, компонента, рівень серйозності |
| Панель адміністратора | /admin/analytics | getPlatformAnalytics() включно з personalPages |
| Realtime підключення | /api/tunnel/ping, /api/tunnel/heartbeat | Затримка тунелю / здоров'я сесії |
| Серверні логи | lib/logger.ts | JSON-рядки у stdout (LOG_LEVEL) |
| Опціональна інфраструктура | Docker-профіль monitoring | Prometheus + Grafana (локальний dev) |
Ring-клон поєднує авторизацію, ринкові дані, платежі і сповіщення в реальному часі. Баг часто проявляється як “сайт відкривається, але замовлення не синхронізуються”, а не як червона помилка. Унікальні відвідування персональної сторінки дозволяють зрозуміти, чи отримують власники довіру — при цьому власник сам не накручує собі лічильник.
Використовуйте GET /api/health у балансувальнику навантаження чи онлайн-чекері — якщо 503, це деградація (часто бракує AUTH_SECRET).
Admin → Analytics: кількість користувачів, медіани Web Vitals, останні клієнтські помилки і personalPages (топові профілі, розподіл по ролях).
Той самий workflow: персональна статистика переглядів і пропуск власника.
Наступний крок: відновлення після інцидентів, що помітно через моніторинг.
Див. також: налаштування Web Vitals та performance-операції.
Залежить від: CRON_SECRET, LOG_LEVEL, ANALYTICS_DISABLE_STORAGE, опційний Sentry.
Відфільтруйте по Засновник/Розробник у боковому меню документації. Джерела моніторингу — app/api/health, app/api/analytics/*, lib/logger.ts, public/scripts/analytics.js + RingAnalyticsBeacon, і аналітичний UI адміністратора. Окремої сторінки features/analytics немає — ця стаття дає огляд аналітики по всій платформі Ring.
Ring Platform збирає першу сторону телеметрії у таблиці PostgreSQL JSONB, має health endpoint для контейнерів, та структуровані серверні логи. Зовнішній APM (Sentry, Vercel Analytics) інтегрується через змінні середовища, але не обов’язковий для основної роботи.
| Рівень | Механізм | Основний сигнал |
|---|---|---|
| Liveness | GET /api/health (+ HEAD) | Процес живий, попередження щодо оточення, пам’ять |
| UX продуктивність | WebVitalsProvider → POST /api/analytics/web-vitals | LCP, CLS, INP, TTFB, FCP |
| Події продукту | analytics.js + RingAnalyticsBeacon → POST /api/analytics/app | Сесії, завантаження сторінок, кастомні події (analytics_events) |
| Персональні сторінки | recordPersonalPageView → personal_page_view | Унікальні відвідування 24г/7д за ролями на /{username} |
| Клієнтські помилки | POST /api/analytics/errors | Stack trace, компонента, рівень серйозності |
| Панель адміністратора | /admin/analytics | getPlatformAnalytics() включно з personalPages |
| Realtime підключення | /api/tunnel/ping, /api/tunnel/heartbeat | Затримка тунелю / здоров'я сесії |
| Серверні логи | lib/logger.ts | JSON-рядки у stdout (LOG_LEVEL) |
| Опціональна інфраструктура | Docker-профіль monitoring | Prometheus + Grafana (локальний dev) |
Ring-клон поєднує авторизацію, ринкові дані, платежі і сповіщення в реальному часі. Баг часто проявляється як “сайт відкривається, але замовлення не синхронізуються”, а не як червона помилка. Унікальні відвідування персональної сторінки дозволяють зрозуміти, чи отримують власники довіру — при цьому власник сам не накручує собі лічильник.
Використовуйте GET /api/health у балансувальнику навантаження чи онлайн-чекері — якщо 503, це деградація (часто бракує AUTH_SECRET).
Admin → Analytics: кількість користувачів, медіани Web Vitals, останні клієнтські помилки і personalPages (топові профілі, розподіл по ролях).
Той самий workflow: персональна статистика переглядів і пропуск власника.
Наступний крок: відновлення після інцидентів, що помітно через моніторинг.
Див. також: налаштування Web Vitals та performance-операції.
Залежить від: CRON_SECRET, LOG_LEVEL, ANALYTICS_DISABLE_STORAGE, опційний Sentry.
Власники бачать у віджеті на персональній сторінці унікальні відвідування за 24г/7д.
degraded — після деплою втрачені важливі змінні; перевірте секрети до postgres.BUILD_DATE / GIT_COMMIT у health JSON якщо вказано).analytics_errors — зламався клієнтський бандл або сторонній скрипт; можна подивитись у адмін-панелі.Визначте, кому приходять тривоги (оператор чи розробник) і що в клоні вважається “падінням”. Ring OSS не має готової інтеграції з PagerDuty; ви самі підключаєте health чек до свого провайдера.
| Маршрут | Метод | Авторизація | Таблиця/Дані |
|---|---|---|---|
/api/analytics/web-vitals | POST | Опціональна сесія | web_vitals |
/api/analytics/web-vitals | GET | Адмін | Запит web_vitals або сумарно ?scope=platform |
/api/analytics/app | POST | Опціональна сесія | analytics_events |
/api/analytics/errors | POST | Опціональна сесія | analytics_errors |
/api/analytics/errors | GET | Адмін | Список помилок |
/api/analytics/device | POST | Потрібна сесія | user_device_telemetry |
/api/analytics/platform-stats | GET | Адмін | Лічильники: users, entities, opportunities |
/api/analytics/navigation | POST | Опціональна сесія | Заглушка — { ok: true }, без збереження |
Реалізація: features/analytics/lib/analytics-db.ts (insertAnalyticsEventBatch, insertWebVitalsRecord, insertAnalyticsErrors). Клієнтські Web Vitals: components/providers/web-vitals-provider.tsx — useReportWebVitals з next/web-vitals буферизує CLS, FCP, LCP, TTFB, INP в один POST із debounce (~1.5с, INP замість FID).
| Компонент | Шлях |
|---|---|
| Тип події | personal_page_view |
| Записувач | features/analytics/lib/personal-page-analytics.ts → recordPersonalPageView |
| Сайт виклику | app/[locale]/[username]/page.tsx — пропускає власника |
| Віджет власника | getPersonalPageViewStats (features/auth/services/personal-page-stats.ts) |
| Адмін | getPersonalPagePlatformStats → PlatformAnalyticsSummary.personalPages |
| Ангажування | personal_page_view агрегується з page_view / app_load / docs_page_view у адмін-UI |
Алгоритм унікальних візитів: Public Profile Pages.
Прописані у data/schema.sql та міграції 017_ring_analytics_schema.sql:
analytics_events — батчі клієнтської телеметрії та серверні personal_page_viewweb_vitals — пакети Core Web Vitalsanalytics_errors — клієнтський лог помилокПри цьому інгест-роути приймають дані, але ігнорують DatabaseService (isAnalyticsStorageDisabled()). Особисті візити також no-op.
Середовище: LOG_LEVEL (debug | info | warn | error; типово info у проді, warn у dev), LOG_SILENT=true для тиші. Вивід — JSON-рядки у stdout; у dev не пише очікувані помилки JWT/SSE.
Закоментовано в env.local.template / docker.env.template:
SENTRY_DSN — інтеграція з Sentry Next.js (не увімкнено за умовчанням)NEXT_PUBLIC_ANALYTICS_ID, VERCEL_ANALYTICS_ID — тільки для Vercel-хостингу| Маршрут | Призначення |
|---|---|
POST /api/tunnel/ping | Аутентифікований pong + timestamp |
POST /api/tunnel/heartbeat | keep-alive з'єднання |
Див. Tunnel protocol.
Маршрути cron (/api/cron/*) не працюють без CRON_SECRET. Наприклад: GET /api/cron/email-analytics запускає pipeline email-analytics.
Сервіси: ring-prometheus (:9090), ring-grafana (:3001). Налаштування: docker/prometheus/prometheus.yml.
Стандартний Prometheus-джоб у конфігу дивиться на /api/metrics, але такий маршрут не реалізовано — фактично скрапить /api/health як JSON (не у форматі Prometheus). Використовуйте цей профіль як стартовий шаблон.
Серверна сторінка: app/[locale]/admin/analytics/page.tsx — потребує isPlatformAdmin, вантажить getPlatformAnalytics('7d'), включаючи personalPages.
Деталі: tunnel-протоколи і heartbeat поведінка.
Власники бачать у віджеті на персональній сторінці унікальні відвідування за 24г/7д.
degraded — після деплою втрачені важливі змінні; перевірте секрети до postgres.BUILD_DATE / GIT_COMMIT у health JSON якщо вказано).analytics_errors — зламався клієнтський бандл або сторонній скрипт; можна подивитись у адмін-панелі.Визначте, кому приходять тривоги (оператор чи розробник) і що в клоні вважається “падінням”. Ring OSS не має готової інтеграції з PagerDuty; ви самі підключаєте health чек до свого провайдера.
| Маршрут | Метод | Авторизація | Таблиця/Дані |
|---|---|---|---|
/api/analytics/web-vitals | POST | Опціональна сесія | web_vitals |
/api/analytics/web-vitals | GET | Адмін | Запит web_vitals або сумарно ?scope=platform |
/api/analytics/app | POST | Опціональна сесія | analytics_events |
/api/analytics/errors | POST | Опціональна сесія | analytics_errors |
/api/analytics/errors | GET | Адмін | Список помилок |
/api/analytics/device | POST | Потрібна сесія | user_device_telemetry |
/api/analytics/platform-stats | GET | Адмін | Лічильники: users, entities, opportunities |
/api/analytics/navigation | POST | Опціональна сесія | Заглушка — { ok: true }, без збереження |
Реалізація: features/analytics/lib/analytics-db.ts (insertAnalyticsEventBatch, insertWebVitalsRecord, insertAnalyticsErrors). Клієнтські Web Vitals: components/providers/web-vitals-provider.tsx — useReportWebVitals з next/web-vitals буферизує CLS, FCP, LCP, TTFB, INP в один POST із debounce (~1.5с, INP замість FID).
| Компонент | Шлях |
|---|---|
| Тип події | personal_page_view |
| Записувач | features/analytics/lib/personal-page-analytics.ts → recordPersonalPageView |
| Сайт виклику | app/[locale]/[username]/page.tsx — пропускає власника |
| Віджет власника | getPersonalPageViewStats (features/auth/services/personal-page-stats.ts) |
| Адмін | getPersonalPagePlatformStats → PlatformAnalyticsSummary.personalPages |
| Ангажування | personal_page_view агрегується з page_view / app_load / docs_page_view у адмін-UI |
Алгоритм унікальних візитів: Public Profile Pages.
Прописані у data/schema.sql та міграції 017_ring_analytics_schema.sql:
analytics_events — батчі клієнтської телеметрії та серверні personal_page_viewweb_vitals — пакети Core Web Vitalsanalytics_errors — клієнтський лог помилокПри цьому інгест-роути приймають дані, але ігнорують DatabaseService (isAnalyticsStorageDisabled()). Особисті візити також no-op.
Середовище: LOG_LEVEL (debug | info | warn | error; типово info у проді, warn у dev), LOG_SILENT=true для тиші. Вивід — JSON-рядки у stdout; у dev не пише очікувані помилки JWT/SSE.
Закоментовано в env.local.template / docker.env.template:
SENTRY_DSN — інтеграція з Sentry Next.js (не увімкнено за умовчанням)NEXT_PUBLIC_ANALYTICS_ID, VERCEL_ANALYTICS_ID — тільки для Vercel-хостингу| Маршрут | Призначення |
|---|---|
POST /api/tunnel/ping | Аутентифікований pong + timestamp |
POST /api/tunnel/heartbeat | keep-alive з'єднання |
Див. Tunnel protocol.
Маршрути cron (/api/cron/*) не працюють без CRON_SECRET. Наприклад: GET /api/cron/email-analytics запускає pipeline email-analytics.
Сервіси: ring-prometheus (:9090), ring-grafana (:3001). Налаштування: docker/prometheus/prometheus.yml.
Стандартний Prometheus-джоб у конфігу дивиться на /api/metrics, але такий маршрут не реалізовано — фактично скрапить /api/health як JSON (не у форматі Prometheus). Використовуйте цей профіль як стартовий шаблон.
Серверна сторінка: app/[locale]/admin/analytics/page.tsx — потребує isPlatformAdmin, вантажить getPlatformAnalytics('7d'), включаючи personalPages.
Деталі: tunnel-протоколи і heartbeat поведінка.
Власники бачать у віджеті на персональній сторінці унікальні відвідування за 24г/7д.
degraded — після деплою втрачені важливі змінні; перевірте секрети до postgres.BUILD_DATE / GIT_COMMIT у health JSON якщо вказано).analytics_errors — зламався клієнтський бандл або сторонній скрипт; можна подивитись у адмін-панелі.Визначте, кому приходять тривоги (оператор чи розробник) і що в клоні вважається “падінням”. Ring OSS не має готової інтеграції з PagerDuty; ви самі підключаєте health чек до свого провайдера.
| Маршрут | Метод | Авторизація | Таблиця/Дані |
|---|---|---|---|
/api/analytics/web-vitals | POST | Опціональна сесія | web_vitals |
/api/analytics/web-vitals | GET | Адмін | Запит web_vitals або сумарно ?scope=platform |
/api/analytics/app | POST | Опціональна сесія | analytics_events |
/api/analytics/errors | POST | Опціональна сесія | analytics_errors |
/api/analytics/errors | GET | Адмін | Список помилок |
/api/analytics/device | POST | Потрібна сесія | user_device_telemetry |
/api/analytics/platform-stats | GET | Адмін | Лічильники: users, entities, opportunities |
/api/analytics/navigation | POST | Опціональна сесія | Заглушка — { ok: true }, без збереження |
Реалізація: features/analytics/lib/analytics-db.ts (insertAnalyticsEventBatch, insertWebVitalsRecord, insertAnalyticsErrors). Клієнтські Web Vitals: components/providers/web-vitals-provider.tsx — useReportWebVitals з next/web-vitals буферизує CLS, FCP, LCP, TTFB, INP в один POST із debounce (~1.5с, INP замість FID).
| Компонент | Шлях |
|---|---|
| Тип події | personal_page_view |
| Записувач | features/analytics/lib/personal-page-analytics.ts → recordPersonalPageView |
| Сайт виклику | app/[locale]/[username]/page.tsx — пропускає власника |
| Віджет власника | getPersonalPageViewStats (features/auth/services/personal-page-stats.ts) |
| Адмін | getPersonalPagePlatformStats → PlatformAnalyticsSummary.personalPages |
| Ангажування | personal_page_view агрегується з page_view / app_load / docs_page_view у адмін-UI |
Алгоритм унікальних візитів: Public Profile Pages.
Прописані у data/schema.sql та міграції 017_ring_analytics_schema.sql:
analytics_events — батчі клієнтської телеметрії та серверні personal_page_viewweb_vitals — пакети Core Web Vitalsanalytics_errors — клієнтський лог помилокПри цьому інгест-роути приймають дані, але ігнорують DatabaseService (isAnalyticsStorageDisabled()). Особисті візити також no-op.
Середовище: LOG_LEVEL (debug | info | warn | error; типово info у проді, warn у dev), LOG_SILENT=true для тиші. Вивід — JSON-рядки у stdout; у dev не пише очікувані помилки JWT/SSE.
Закоментовано в env.local.template / docker.env.template:
SENTRY_DSN — інтеграція з Sentry Next.js (не увімкнено за умовчанням)NEXT_PUBLIC_ANALYTICS_ID, VERCEL_ANALYTICS_ID — тільки для Vercel-хостингу| Маршрут | Призначення |
|---|---|
POST /api/tunnel/ping | Аутентифікований pong + timestamp |
POST /api/tunnel/heartbeat | keep-alive з'єднання |
Див. Tunnel protocol.
Маршрути cron (/api/cron/*) не працюють без CRON_SECRET. Наприклад: GET /api/cron/email-analytics запускає pipeline email-analytics.
Сервіси: ring-prometheus (:9090), ring-grafana (:3001). Налаштування: docker/prometheus/prometheus.yml.
Стандартний Prometheus-джоб у конфігу дивиться на /api/metrics, але такий маршрут не реалізовано — фактично скрапить /api/health як JSON (не у форматі Prometheus). Використовуйте цей профіль як стартовий шаблон.
Серверна сторінка: app/[locale]/admin/analytics/page.tsx — потребує isPlatformAdmin, вантажить getPlatformAnalytics('7d'), включаючи personalPages.
Деталі: tunnel-протоколи і heartbeat поведінка.