Межі експлуатації для операторів
Цей посібник визначає операторський контракт Durable Workflow v2. Він допомагає вирішити, яка діагностика блокує розгортання, а яка є рекомендаційною, які відомості про черги належать до Waterline чи телеметрії worker, як перевіряти відновлення проєкцій та експорт і які форми розгортання охоплюють задокументовані межі експлуатації.
Описані процедури розгортання й відновлення стосуються вбудованого Laravel і самостійно розгорнутого Server. Durable Workflow Cloud є окремим керованим сервісом: Cloud відповідає за зберігання стану runtime, розміщення в одному регіоні, резервні копії та відновлення, а клієнти керують клієнтами SDK і worker через URL runtime namespace. Не використовуйте цей посібник для підключення Server до Cloud. Цю межу клієнта описує керований runtime Cloud.
Джерела істини
Використовуйте ці поверхні разом:
| Поверхня | Призначення | Клас контракту |
|---|---|---|
php artisan workflow:v2:doctor --strict | Перевірка можливостей бекенду до трафіку v2 чи оновлень | Блокувальний |
GET /waterline/api/v2/health | Поточна готовність джерела рушія та блокувальні й рекомендаційні перевірки v2 | Блокувальний за status = error, рекомендаційний за status = warning |
GET /waterline/api/stats | Надійні підсумки парку, backlog, факти циклу repair, відхилення проєкцій, сумісність worker | Рекомендаційний і для benchmark |
php artisan workflow:v2:rebuild-projections ... | Перегляд і виправлення відхилень проєкцій | Обслуговування |
php artisan workflow:v2:backfill-command-contracts ... | Перегляд і backfill старих знімків контрактів команд | Обслуговування |
php artisan workflow:v2:history-export ... і маршрути експорту історії Waterline | Replay, передавання архіву та матеріали інциденту | Перевірка |
Дії архівування Waterline й archive() площини керування | Переходи життєвого циклу закритих виконань | Життєвий цикл |
| Метрики, трасування й журнали SDK worker | Затримка schedule-to-start, успішність poll, sticky-cache та власна телеметрія застосунку | Телеметрія runtime |
Контракт оператора щодо надійного стану належить runtime, який володіє виконанням. Waterline відображає цей контракт із вбудованого пакета workflow або самостійного Server через PHP SDK. Телеметрія worker залишається джерелом істини для затримки й поведінки процесів усередині ваших worker.
Відповідність поверхонь формам розгортання
Маршрути Waterline з таблиці вище доступні в обох формах його розгортання.
Вбудований режим читає надійний стан хоста Laravel у процесі. Сервісний режим
запускає опублікований образ Waterline та читає один namespace самостійного
Server через PHP SDK. Автентифікований API Server і CLI dw доступні
безпосередньо як із Waterline, так і без нього:
| Питання оператора | Waterline (вбудований чи сервісний режим) | Власна поверхня самостійного Server |
|---|---|---|
| Готовність джерела рушія та блокувальні й рекомендаційні перевірки | GET /waterline/api/v2/health | GET /api/system/health (автентифікація адміністратора, control-plane v2); dw server:health для життєздатності й dw server:info для топології, протоколу й безпечності розгортання |
| Надійні підсумки парку, backlog, repair, сумісність worker, відхилення проєкцій | GET /waterline/api/stats | GET /api/system/operator-metrics and dw system:operator-metrics |
| Деталі вибраного виконання й експорт історії | GET /waterline/api/instances/... і /waterline/api/.../history-export | GET /api/workflows/{workflowId}, /runs/{runId} і /runs/{runId}/history/export (див. довідник API Server) |
| Операторські команди (cancel, terminate, repair, archive, signal/update/query) | POST /waterline/api/instances/.../{cancel|terminate|repair|archive} і маршрути signal/update/query | POST /api/workflows/{workflowId}/{cancel|terminate|repair|archive} and POST /api/system/repair/pass |
| Виявлення топології та ідентичності вузла | Вбудований режим: php artisan workflow:v2:doctor --json (об'єкт topology); сервісний: власна поверхня підключеного Server | GET /api/cluster/info, GET /api/health, GET /api/ready (або dw server:info) |
Сімейства полів і назви контрактів нижче однакові незалежно від поверхні читання. Інсталяція Waterline обмежена налаштованими runtime і namespace. Вона не об'єднує вбудовані виконання з виконаннями під керуванням Server.
Датований знімок доказів 2.0
Цей знімок розділяє поведінку, виміряну на випущених артефактах, і процедури, які продукт підтримує, але оператор має відпрацювати у власному середовищі. Успішний рядок стосується задокументованих сценарію 2.0 й топології, а не довільного середовища чи більшого розгортання.
Поточний перелік доказів:
| Доказ і дата (UTC) | Безпосередньо виміряний результат | Межа |
|---|---|---|
| Тренування failover одного регіону, 2026-07-28 | Термінальне завершення між вузлами, втрата одного API вузла, переривання й відновлення MySQL, переривання Redis із переходом на опитування бази, втрата й повторне отримання lease worker, перезапуск єдиного планувальника. Перевірки втрати й дублікатів пройшли на кожному етапі. | Два API вузли за спільним endpoint, один MySQL, один шар прискорення Redis, один worker черги й один процес планувальника/обслуговування в одному регіоні. Переривання бази й Redis стосувалися контейнерів, а не promotion керованого провайдера. |
| Матриця перезапуску timer, 2026-07-28 | Сплячі workflow завершилися після перезапуску worker і Server з одним плануванням та спрацюванням timer на виконання й без дубліката команди replay. | Відновлення надійних timer і replay на тестовій топології опублікованого Server, без довільного стану процесу чи зовнішніх побічних ефектів. |
| Матриця runtime activity, 2026-07-29 | Відновлення результату після перезапуску worker, повторні спроби й тайм-аути, спостереження heartbeat і скасування, надійний запис термінального результату й ідемпотентна обробка завершення через потрібні поверхні продукту. | Поведінка рушія на рівні activity. Ідемпотентність зовнішніх побічних ефектів залишається відповідальністю застосунку. |
| Матриця життєвого циклу workflow, 2026-07-29 | Термінальні успіх і помилка, політики повторного запуску й повторного використання ID workflow, тайм-аути й повторні спроби, неперервність історії та запобігання повторним побічним ефектам через PHP, Python, Rust, CLI, API, історію й Waterline. | Коректність життєвого циклу перевірених сценаріїв, без benchmark доступності чи пропускної здатності. |
Підтримувані лінії релізів описані в контракті сумісності. Відпрацюйте задокументовану процедуру відновлення на своєму розгортанні, перш ніж заявляти про перемикання після збою для конкретної топології.
Виміряна гарантія й підтримувана процедура
| Збій чи результат | Безпосередньо доведено датованими доказами | Підтримувана процедура оператора | Не встановлено цими доказами |
|---|---|---|---|
| Втрата одного API вузла | Тренування зупинило один із двох API вузлів, звернулося до решти через спільний endpoint, зберегло підтверджений стан і завершило виконання. | Вилучіть несправні вузли через /api/ready, повторіть перервані запити клієнта, перевірте топологію й реєстрацію worker перед поверненням трафіку. | Втрата всього парку, ізоляція зони доступності чи довільне розділення мережі. |
| Переривання бази даних | Обидва API вузли стали неготовими, надійний стан зберігся, новий worker отримав завдання після завершення lease, виконання завершилося, повторне завершення було відхилено. | Спочатку відновіть базу для запису, дочекайтеся готовності, відгородіть старого власника завдання, перевірте репрезентативне виконання й відновіть трафік. Promotion керованої бази потребує fencing провайдера та доказів RPO і часу в наборі відновлення. | Promotion керованої бази, підтверджені записи під час split-brain чи RPO/RTO поза виміряним локальним перериванням. |
| Переривання Redis | Готовність повідомила про погіршення прискорення, опитування бази зберегло надійний стан, повторення запиту poll не створило дубліката lease, готовність відновилася після повернення Redis. | Використовуйте Redis як прискорення, допускайте готовність із warning, відновіть Redis після надійного сховища та перевірте повернення затримки poll до базового рівня. | Два primary Redis, поведінка кешу під час розділення мережі чи час promotion провайдера. |
| Перезапуск чи втрата worker | Доказ failover повторно отримав і завершив орендований workflow після втрати worker. Новіша матриця activity довела надійне відновлення результату після перезапуску й ідемпотентне завершення. | Дочекайтеся завершення lease чи виконайте drain worker, запустіть сумісну заміну, перевірте реєстрацію й отримання черги та зберігайте ідемпотентність зовнішніх ефектів. | Відновлення недовговічного локального стану процесу чи зовнішні ефекти exactly-once. |
| Перезапуск Server чи планувальника | Матриця timer завершила сплячі workflow після перезапуску Server без дублікатів команд timer. Доказ failover зберіг прогрес після втрати одного API вузла й перезапуску єдиного планувальника. | Відновіть сховище, поверніть ролі Server до готовності, підтвердьте рівно одного планувальника/процес обслуговування, перевірте реєстрацію worker і репрезентативне завершення. | Одночасна втрата всіх вузлів Server і сховища, багаторегіональний failover чи постійна робота дублікатів планувальника. |
| Повторне доставлення | Етапи відновлення бази й втрати worker записали одне логічне завершення та відхилили дублікат HTTP 409. Погіршення Redis повернуло початковий lease без нового дубліката. Матриця activity окремо пройшла перевірку ідемпотентного завершення. | Використовуйте сталі ідентичності запитів і завдань, дотримуйтеся відмов старим спробам і робіть побічні ефекти activity ідемпотентними. | Універсальна гарантія exactly-once доставлення чи побічних ефектів поза надійним рушієм. |
| Термінальне завершення | Workflow між вузлами, після втрати API, відновлення бази й втрати worker досягли completed. Новіша матриця життєвого циклу пройшла завершення, помилку, скасування, terminate, тайм-аут і retry. | Перевірте вибране виконання та докази його історії/експорту перед архівуванням чи оголошенням відновлення завершеним. | Завершення форм навантаження, інтеграцій чи комбінацій збоїв, які не перевірялися. |
Найбільший поточний тест навантаження
Найбільший налаштований тест навантаження Server запускає 1 000 workflow із паралельністю запуску 8 та 8 одночасними worker опитування протягом 120 секунд. Він вимагає щонайменше 98% успішних запусків workflow й перевіряє доступність endpoint, очищення ключів кешу, покриття вибірки та обмежене споживання ресурсів.
Це коротка перевірка коректності, а не тривалий production benchmark. Вона не визначає універсальної пропускної здатності, затримки, пам'яті чи максимальної паралельності. Визначте їх benchmark і тривалим тестом для точної топології, набору worker, бази даних, кешу й релізу, які експлуатуватимете.
Явно поза охопленням
Докази 2.0 не охоплюють:
- розділення мережі
- навмисне зміщення годинника
- роботу в кількох регіонах
- поведінку split-brain
Ці експерименти не є передумовами релізу 2.0. Вони потрібні лише для відповідних заяв про розділення мережі, зміщення часу, кілька регіонів чи split-brain. Підтримувані межі релізу 2.0 охоплюють опубліковану топологію, її набір відновлення та поведінку, виміряну задокументованими сценаріями. Непідтримувані сценарії chaos не слід подавати як докази непридатності задокументованих процедур одного регіону.
Підтримувані топології
Durable Workflow v2 підтримує ці операторські форми. Назви першої колонки
відповідають topology.current_shape, опублікованим /api/cluster/info та
маніфестом топології ролей Server.
Так операторський контракт узгоджується з контрактом виявлення вашої автоматизації.
Форма оператора (topology.current_shape) | Підтримуваний операторський контракт | Основні області відмов | Очікування відновлення й failover |
|---|---|---|---|
embedded, один вузол | Waterline, маршрути площини керування, здоров'я, rebuild, експорт і архів працюють з одного процесу застосунку з однією надійною базою й одним кешем. | Процес Laravel, надійна база й кеш одного хоста. | Втрата хоста чи бази є повним перериванням сервісу. Спочатку відновіть надійний стан, поверніть вузол застосунку до готовності й перевірте реєстрацію worker перед трафіком. |
embedded, невеликий кластер одного регіону | Спільна база й кеш для координації пробудження, однакова сумісність і конфігурація workflow на вузлах. Активні вузли мають бути в одному датацентрі чи регіоні для обмеженої затримки пробудження черг і timer. | Спільна база, кеш/координація пробудження, маршрутизація балансувальника та єдина роль планувальника чи обслуговування. | Втрата вузла зменшує місткість, а не коректність. Втрата бази блокує надійний трафік. Втрата лише Redis погіршує прискорення й дає warning готовності, а опитування бази зберігає коректність. Failover планувальника й оновлення залишаються явними процедурами оператора. |
Розгортання standalone_server | Використовуйте матрицю самостійного розгортання, потім ті самі відмінності здоров'я, статистики, експорту, архіву й черг через /api/system/... і /api/workflows/... чи окремий сервіс Waterline (див. відповідність поверхонь вище). | Спільні база й Redis, контейнери API, незалежно масштабовані worker, необов'язковий спостерігач Waterline та єдиний планувальник/процес обслуговування. | API контейнери є замінними вузлами процесів, Waterline є замінним спостерігачем стану Server. База, Redis і єдиний планувальник визначають порядок відновлення. Спочатку відновіть сховище, перевірте /api/ready, /api/cluster/info і реєстрацію worker, потім повертайте трафік. |
split_control_execution | Контракт як у standalone_server, але кожна роль ізольована у власному класі процесу (ingress_node, control_plane_node, scheduler_node, matching_node, execution_node). Метрики, здоров'я й команди застосовуються на вузлах. Направляйте адміністративні читання на вузол потрібної ролі. | Кожна роль має свій клас процесу, тому топологія ролей Server визначає перший збій підсистеми. Спільні база, Redis і вибори єдиного планувальника залишаються областями відмов усього парку. | Порядок відновлення як у standalone_server, але перевіряйте topology.current_shape, topology.current_process_class і topology.current_roles кожного вузла перед готовністю. Маршрути повертають 503 topology_role_unavailable на неправильному класі вузла. |
split_control_execution є тим самим операторським контрактом, що й
standalone_server, із класами процесів окремих ролей у topology.shape_assignments.
Це не окремий рушій чи продукт. Решта посібника застосовується до обох форм,
якщо розділ не називає конкретну роль. Топологія ролей Server
визначає словник ролей, межі повноважень і шлях міграції.
Сервісний режим Waterline є розгортанням спостерігача, а не новою топологією
Server. Додавання чи видалення Waterline не змінює topology.current_shape,
доступність власних API чи CLI Server або runtime, що володіє виконанням.
Опублікуйте порядок відновлення, частоту резервних копій, очікувану затримку перемикання та прив'язку поведінки до регіону в інструкції своєї топології. Контракт продукту визначає факти для вимірювання, а контракт розгортання фіксує прийнятні час відновлення, ручні дії та області відмов.
Перелік областей відмов за формою
Таблиця топологій вище дає коротке зведення. Складіть інструкцію відповідно до цих докладніших моделей втрат:
- Вбудований Laravel, один вузол: один процес застосунку одночасно володіє ролями площини керування, matching, проєкцій, планувальника й виконання. Втрата процесу повністю перериває надійні команди, просування workflow, запуск schedule та читання оператором до відновлення готовності того самого застосунку зі збереженим надійним сховищем.
- Вбудований Laravel, невеликий кластер одного регіону: втрата звичайного вузла має зменшити лише частину HTTP місткості та місткості worker, тоді як решта вузлів отримують роботу зі спільного надійного сховища. Основні межі коректності парку: спільна база даних, спільний шлях пробудження через кеш і вузол, що зараз володіє єдиною роллю планувальника чи обслуговування.
- Самостійний Server (
standalone_server): втратаserver_http_nodeзупиняє приймання запитів і команди площини керування лише на цьому вузлі. Здорові worker можуть завершувати орендовану роботу, а інші API вузли обслуговують запити. Втратаworker_nodeмає збільшити backlog, вік черги чи попередження сумісності лише для відповідних областей(connection, queue, compatibility). Втратаscheduler_nodeпризупиняє нові запуски schedule й проходи обслуговування без скасування активних workflow. Втрата бази даних є збоєм усього парку. Втрата лише Redis зберігає надійне опитування бази даних, погіршуєlong_poll_wake_accelerationі збільшує затримку виявлення до підключення Redis. - Server із розділеними ролями (
split_control_execution): кожна роль працює у власному класі процесу:ingress_node,control_plane_node,scheduler_node,matching_node,execution_node. Втрата класу погіршує лише його роль: ingress зупиняє зовнішній HTTP на межі, control-plane швидко відхиляє операторські команди, поки орендована робота триває, matching переходить на прямий пошук готових завдань, scheduler призупиняє schedule й записує пропущені запуски, execution накопичує готові завдання без втрати надійного стану. Втрата бази даних залишається збоєм усього парку. Втрата лише Redis погіршує прискорення з тим самим переходом на опитування бази й попередженням готовності, що й уstandalone_server.
Якщо ваше розгортання спирається на інші припущення, опишіть цю топологію окремою інструкцією з перевіреним контрактом, замість незмінного застосування посібника для самостійної експлуатації.
Опублікований набір відновлення за топологією
Топології вище готові до production лише після публікації відповідного набору відновлення в інструкції розгортання:
| Топологія | Факти, які має опублікувати оператор |
|---|---|
embedded, один вузол | Графік резервних копій бази, очікування збереження кешу, точна ревізія застосунку й знімок env/config для відновлення, максимально прийнятне відставання даних і докази останнього успішного тренування відновлення. |
embedded, невеликий кластер одного регіону | Усе з набору одного вузла, а також поточний власник планувальника/обслуговування, наслідки втрати звичайного вузла порівняно зі спільною базою чи кешем та кроки failover для координації пробудження. |
Розгортання standalone_server | Частота копій бази й Redis, зафіксований образ/digest Server, розташування матеріалів автентифікації, очікуваний failover для server_http_node, worker_node, scheduler_node, останні докази перевірки /api/ready і /api/cluster/info та повторної реєстрації worker після відновлення. |
Розгортання split_control_execution | Усе з набору standalone_server, очікування масштабування й відмов кожного класу ingress_node, control_plane_node, scheduler_node, matching_node, execution_node та правила маршрутизації клієнтів за 503 topology_role_unavailable від неправильного класу вузла. |
Якщо набір відсутній, застарілий чи не перевірений, вважайте топологію придатною лише для розробки незалежно від кількості вузлів.
Перевірте фактичну ідентичність топології до використання базових показників
Для самостійного Server і розгортання з розділеними ролями підтвердьте
ідентичність вузла, яку повідомляє сам продукт, перш ніж тлумачити сигнали
черги, планувальника чи збоїв ролей. GET /api/cluster/info є джерелом істини:
| Поле | Призначення |
|---|---|
topology.current_shape | Підтверджує, чи вузол оголошує embedded, standalone_server або split_control_execution. |
topology.current_roles | Підтверджує логічні ролі цього вузла. |
topology.supported_shapes | Підтверджує форми розгортання, публічно підтримувані збіркою Server. |
topology.shape_assignments | Зіставляє підтримувані форми із задокументованими наборами ролей класів процесів для порівняння поточного набору з топологією. |
Використовуйте ці поля як першу перевірку зміни топології під час розгортання:
- У формі самостійного Server вузли API мають надалі повідомляти набір ролей
api_ingress,control_plane,matching,history_projection, вузли планувальника мають повідомлятиscheduler, а worker мають повідомлятиexecution_plane. - У формі з розділеними ролями перевірте відповідність
current_rolesкожного вузла задокументованому набору вshape_assignmentsдо тлумачення backlog чи затримки планувальника як проблеми worker. - Якщо
current_rolesвідхиляються від плану розгортання, базові показники черг і відновлення після збоїв залишаються сумнівними до виправлення ідентичності вузла.
Вбудовані інсталяції не публікують /api/cluster/info. Для локального огляду
топології пакета виконайте php artisan workflow:v2:doctor --json і перевірте
об'єкт topology. Він публікує ту саму схему топології ролей та
current_shape, current_process_class, current_roles, execution_mode
і вкладене зведення matching_role вбудованого застосунку.
Блокувальна й рекомендаційна діагностика
Durable Workflow v2 розрізняє блокувальну й рекомендаційну діагностику.
| Рівень | Значення | Типова дія оператора |
|---|---|---|
| Блокувальний | Поточні конфігурація чи готовність небезпечні для трафіку v2 | Зупиніть розгортання, виправте передумову й повторіть перевірку |
| Рекомендаційний | Поверхня доступна, але похідні факти потребують rebuild, backfill чи ручної перевірки | За можливості продовжуйте трафік, потім виправте названу поверхню |
| Здоровий | Поточних проблем поверхні не знайдено | Продовжуйте звичайну роботу |
Застосовуйте це правило до випущених поверхонь:
workflow:v2:doctor --strictблокує роботу, коли проблеми можливостей бекенду мають рівеньerror. Наприклад, непідтримуваний драйвер черги в режимі queue або кеш без блокувань. Інформаційна діагностика черги в режимі poll є рекомендаційною.GET /waterline/api/v2/healthповертає:status = ok, якщо операторська поверхня v2 готова й поточні перевірки узгоджені.status = warning, якщо поверхня доступна для читання, але певні факти потребують відновлення, backfill чи виправлення перед повною довірою.status = errorз HTTP503, якщо міст джерела рушія не готовий або блокувальна проблема можливостей робить поверхню v2 недоступною.
GET /waterline/api/statsпублікує надійні операторські факти. Використовуйте поля JSON для діагностики в панелях і скриптах, а не як endpoint збору метрик.
Перевірки коректності й прискорення
Кожна перевірка здоров'я v2 має category зі значенням correctness чи
acceleration. Знімок публікує зведення за категоріями, щоб оператор міг
відповісти на два окремі питання без повторного агрегування перевірок.
- Перевірки коректності описують справність надійного пошуку готових завдань,
актуальності проєкцій, backfill контрактів команд, зберігання історії,
сумісності worker та можливостей бекенду.
status = errorу цій категорії означає ризик для безпечного отримання завдань чи стану, якому довіряє оператор. Розгортання слід зупинити до усунення проблеми. - Перевірки прискорення описують своєчасність необов'язкового поширення
сигналів пробудження. Надійне опитування забезпечує коректність, тому
status = warningприскорення означає можливе збільшення затримки пробудження між вузлами без втрати доступності завдань.
Кожен запис checks містить category, а знімок додає зведення categories
для швидкого огляду обох питань у панелях:
{
"status": "warning",
"categories": {
"correctness": {"status": "ok", "check_count": 8},
"acceleration": {"status": "warning", "check_count": 1}
}
}
Погіршення acceleration стосується лише прискорення: перевірте здоров'я
кешу чи бекенду пробудження, але не блокуйте трафік, що залежить лише від
надійного пошуку готових завдань. Погіршення correctness є блокувальним
сигналом. long_poll_wake_acceleration є канонічною перевіркою прискорення
й ніколи не перевищує warning. Усі інші перевірки належать до коректності.
Семантика здоров'я черг
Здоров'я черг розділене між надійним станом черги й телеметрією worker/runtime.
Надійні факти черги
Для надійного стану завдань використовуйте статистику панелі й огляди черг Waterline:
| Факт | Значення |
|---|---|
operator_metrics.backlog.runnable_tasks | Надійні завдання, готові до отримання зараз. |
operator_metrics.backlog.delayed_tasks | Надійні завдання, що ще очікують available_at. |
operator_metrics.backlog.leased_tasks | Надійні завдання, отримані worker. |
operator_metrics.backlog.tasks_added_last_minute | Окремі рядки надійних завдань, створені за останні 60 секунд. Це надходження до надійної черги, а не лічильник спроб транспорту. |
operator_metrics.backlog.tasks_dispatched_last_minute | Окремі рядки надійних завдань, чий останній успішний last_dispatched_at припав на останні 60 секунд. Порівнюйте з tasks_added_last_minute для виявлення перевищення надходження над доставленням. |
operator_metrics.starts.pending_runs, operator_metrics.starts.pending_commands, operator_metrics.starts.ready_tasks, operator_metrics.starts.oldest_pending_start_at, operator_metrics.starts.max_pending_ms | Надійний backlog запусків workflow. Відокремлює прийняті запуски, які ще не стали активною роботою завдань workflow, від звичайної затримки черги worker. |
operator_metrics.tasks.oldest_ready_due_at, operator_metrics.tasks.max_ready_due_age_ms | Найстаріше придатне завдання та його вік готовності до доставлення. Машиночитана пара затримки backlog для найстарішого готового завдання. |
operator_metrics.tasks.dispatch_overdue, operator_metrics.tasks.oldest_dispatch_overdue_since, operator_metrics.tasks.max_dispatch_overdue_age_ms | Готові надійні завдання без успішного пробудження dispatch і вік найстарішого. Виявляє погіршення прискорення notifier окремо від звичайного росту черги. |
operator_metrics.backlog.unhealthy_tasks | Надійні завдання з помилками dispatch/claim, простроченим dispatch чи lease. |
operator_metrics.backlog.repair_needed_runs | Відкриті виконання без надійного шляху продовження. |
operator_metrics.tasks.oldest_lease_expired_at, operator_metrics.tasks.max_lease_expired_age_ms | Найстаріший прострочений lease і його вік. Основний індикатор віку застряглих lease та ризику дублікатів. |
operator_metrics.backlog.oldest_compatibility_blocked_started_at, operator_metrics.backlog.max_compatibility_blocked_age_ms | Найстаріше блокування маршрутизації сумісності й його вік: робота збережена, але жоден сумісний worker не має права її отримати. |
| Активні й застарілі poller | Чи зареєстровані worker продовжують heartbeat черги. |
| Поточні lease | Які завдання workflow чи activity зараз орендовані та чи lease прострочений. |
Ці факти описують лише надійний потік завдань workflow та activity.
Для докладного огляду окремої черги замість загальних підсумків парку використовуйте
маршрути видимості черг Server. Вони показують вік backlog, стан poller,
поточні lease, бюджети допуску та stats.tasks_added_last_minute і
stats.tasks_dispatched_last_minute. Порівнюйте надходження й доставлення
окремої черги, щоб знайти чергу з ростом backlog або без доступної місткості
worker. Для загального порівняння використовуйте пару
operator_metrics.backlog.* вище.
GET /waterline/api/v2/health надає той самий огляд черг у
queue_visibility.* для налаштованого namespace. Ці сімейства полів є
типізованим контрактом здоров'я черг:
| Сімейство полів | Значення |
|---|---|
queue_visibility.available, queue_visibility.reason | Чи Waterline може показати локальну видимість черг налаштованого namespace і причина недоступності. |
queue_visibility.task_queues[].stats.approximate_backlog_count, queue_visibility.task_queues[].stats.approximate_backlog_age | Кількість backlog черги й вік найстарішої надійної роботи. |
queue_visibility.task_queues[].stats.tasks_added_last_minute, queue_visibility.task_queues[].stats.tasks_dispatched_last_minute | Надходження й доставлення надійної роботи черги за останні 60 секунд. Виявляє гарячу чергу серед здорових підсумків парку. |
queue_visibility.task_queues[].stats.pollers.active_count, queue_visibility.task_queues[].stats.pollers.stale_count, queue_visibility.task_queues[].stats.pollers.stale_after_seconds | Здорові й застарілі poller черги та використаний поріг застарілого heartbeat. |
queue_visibility.task_queues[].stats.workflow_tasks.*, queue_visibility.task_queues[].stats.activity_tasks.* | Локальні кількості готових, орендованих завдань і прострочених lease окремо для workflow й activity. |
queue_visibility.task_queues[].repair.candidates, dispatch_failed, expired_leases, dispatch_overdue | Тиск repair черги: завдання, які вже потребують виправлення, мають помилку dispatch, прострочені lease чи потребують повторного dispatch. |
queue_visibility.task_queues[].repair.oldest_dispatch_failed_at, max_dispatch_failed_age_ms, oldest_lease_expired_at, max_lease_expired_age_ms, oldest_dispatch_overdue_since, max_dispatch_overdue_age_ms | Вік найстаріших помилки dispatch, простроченого lease й простроченого dispatch надійного завдання. |
coordination_alerts[] того самого payload GET /waterline/api/v2/health
є операторським зведенням локальних фактів черг і списку перевірок здоров'я.
Використовуйте його як готове до сповіщення зведення попереджень і помилок,
а докази шукайте у відповідних записах queue_visibility чи checks.
Локальний стан допуску черги є основним сигналом слотів і poller цієї черги.
saturated означає, що живі worker є, але всі зареєстровані слоти орендовані.
throttled означає, що ліміт lease чи доставлення на сервері навмисно стримує
нову роботу. no_slots означає, що worker зареєстровані, але оголошують нульову
місткість для цього виду завдань. no_active_workers означає відсутність
здорових poller черги, а unavailable означає, що налаштований захист
допуску з блокуванням зараз не може довести безпечність.
Використовуйте operator_metrics.starts.*, якщо нові запуски workflow
застрягають, хоча звичайна затримка черги нормальна. Ці факти відокремлюють
борг допуску запусків і створення першого завдання від отримання роботи worker.
Навантаження poller і бюджети допуску
Якщо потік черги погіршується, використовуйте маршрути деталей черги чи
dw task-queue:describe, щоб розрізнити нестачу місткості worker,
навмисне обмеження сервера й повну відсутність живих poller:
| Стан черги | Значення | Тлумачення |
|---|---|---|
accepting | Worker мають вільні слоти, ліміти сервера не вичерпані. | Здоровий базовий стан. |
saturated | Усі зареєстровані слоти worker орендовані. | Тиск на місткість worker. |
throttled | Ліміт активних lease чи швидкості доставлення сервера навмисно стримує чергу. | Рекомендаційний, якщо ліміт очікуваний і backlog не перевищує опублікованого базового рівня. |
no_slots | Активні worker зареєстровані, але не оголошують слотів цього виду завдань. | Блокувальний для черги. |
no_active_workers | Немає здорового poller черги. | Блокувальний для черги. |
unavailable | Черга не може отримати блокування для налаштованого шляху допуску. | Блокувальний до відновлення залежності допуску. |
Використовуйте ці стани разом із фактами потоку черги:
tasks_added_last_minute > tasks_dispatched_last_minuteразом ізsaturatedозначає, що надійне надходження перевищує місткість worker.- Такий самий дисбаланс разом із
throttledозначає явне обмеження сервера. Оцінюйте його за призначеним контрактом ліміту, а не необмеженою пропускною здатністю. - Зростання віку найстарішого готового завдання разом із
no_active_workersчи застарілими poller означає втрату здорових отримувачів завдань. Це слід вважати збоєм маршрутизації відповідної області.
Форма розгортання ролі matching
Використовуйте operator_metrics.matching_role.*, щоб підтвердити фактичний
контракт matching/dispatch поточного вузла:
| Факт | Значення |
|---|---|
operator_metrics.matching_role.queue_wake_enabled | Чи вузол ще запускає широкий шлях пробудження poll усередині worker за подіями циклу worker черги. |
operator_metrics.matching_role.shape | in_worker, якщо вузол володіє цим шляхом, dedicated, якщо проходи wake/repair мають працювати окремим процесом workflow:v2:repair-pass --loop. |
operator_metrics.matching_role.task_dispatch_mode | Режим доставлення готових завдань вузла: queue або poll. |
operator_metrics.matching_role.partition_primitives | Зафіксовані осі маршрутизації в порядку: connection, queue, compatibility, namespace. |
operator_metrics.matching_role.backpressure_model | Межа надійного допуску, яку застосовує рушій. Поточна v2 повідомляє lease_ownership. |
Ці поля належать вузлу, а не всьому парку. Під час розгортання змішаних форм читайте знімок кожного вузла чи pod, який переводите, щоб підтвердити перенесення matching до тлумачення змін backlog чи poller як стану worker.
Телеметрія worker і SDK
Використовуйте метрики, трасування й журнали worker для:
- Затримки
schedule_to_startworkflow й activity - Успішності poll та поведінки sync/eager-dispatch
- Розміру sticky-cache та витіснення записів
- Навантаження CPU, пам'яті, потоків і циклу подій worker
- Власних метрик застосунку з activity чи коду worker
Синхронні query, інструменти живого налагодження та інші виклики площини керування без надійних завдань позначайте окремо в панелях. Вони не входять до надійного backlog завдань і не змінюють лічильники відновлення Waterline.
Сумісність worker і здоров'я розгортання
operator_metrics.workers публікує факти сумісності, що визначають здатність
активного парку worker безпечно виконувати потрібний контракт workflow:
| Факт | Значення |
|---|---|
operator_metrics.workers.required_compatibility | Маркери сумісності, які worker має оголосити для отримання роботи namespace. |
operator_metrics.workers.active_workers | Кількість окремих живих worker за heartbeat сумісності. |
operator_metrics.workers.active_worker_scopes | Кількість областей (connection, queue), які покривають ці worker. |
operator_metrics.workers.active_workers_supporting_required | Worker, чия оголошена сумісність покриває потрібні маркери. |
operator_metrics.workers.fleet | Список активних worker за областю з worker_id, connection, queue, оголошеними supported, прапорцем supports_required, джерелом heartbeat source (database чи cache) та recorded_at. |
Використовуйте зведені кількості для виявлення стану розгортання, у якому
частина worker не може безпечно отримувати потрібну роботу. Переглядайте
fleet для визначення конкретних (connection, queue) без покриття.
Операторська панель Waterline показує той самий парк у панелі сумісності
worker, тому не потрібно вручну запитувати метрики.
Коли active_workers_supporting_required дорівнює нулю для namespace,
Waterline показує діагностику no_compatible_worker_for_task на відповідних
виконаннях. Супровідна перевірка worker_compatibility повертає warning
у correctness за тієї самої умови. Це переводить зведення correctness
у warning, щоб прогалина парку була видимою одразу, а не лише в списку перевірок.
Потік drain/resume, узгоджений із цими фактами під час розгортання build-id, описано в розгортанні збірок worker через build ID. Контракт прив'язки для цієї діагностики описано в сумісності й маршрутизації worker.
Семантика сповіщень
Пороги сповіщень залежать від розгортання. Опублікуйте власні числові базові показники віку черг, затримки відновлення, покриття worker та часу відновлення. Сповіщайте, якщо наведений контракт порушений довше за одне нормальне вікно repair чи watchdog вашої топології.
| Сімейство сповіщень | Джерело | Тлумачення | Умова ескалації | Відповідь оператора |
|---|---|---|---|---|
| Блокувальна готовність | workflow:v2:doctor --strict, GET /waterline/api/v2/health | Блокувальне | doctor --strict повертає помилку або endpoint здоров'я повертає status = error / HTTP 503 | Зупиніть розгортання чи перенесення трафіку, виправте передумову й повторіть перевірки готовності й сумісності. |
| Покриття сумісними worker | operator_metrics.workers.*, worker_compatibility health check, run diagnostic no_compatible_worker_for_task | Блокувальне | active_workers_supporting_required = 0 для namespace чи потрібної області (connection, queue) | Виконайте drain несумісних worker, зареєструйте сумісні й перевірте очищення correctness перед новим отриманням завдань. |
| Затримка надійної черги | Огляди черг Waterline, operator_metrics.backlog.*, телеметрія schedule_to_start worker | Блокувальне за тривалого стану, рекомендаційне за короткого | Вік найстарішого готового завдання чи schedule-to-start тривало перевищує базовий рівень топології за наявності сумісних worker | Додайте місткість worker, перевірте ліміти допуску черги та просування scheduler чи matching. |
| Тиск poller і насичення допуску | Маршрути деталей черг, dw task-queue:describe, status черги, застарілі poller й швидкості додавання/доставлення | Блокувальне для no_active_workers, no_slots, unavailable, рекомендаційне для навмисного throttled | Черга тривало saturated зі зростанням віку найстарішої роботи й розриву додавання/доставлення або переходить у no_active_workers, no_slots, unavailable поза плановим обслуговуванням | Додайте слоти worker, відновіть відсутню групу poller чи підтвердьте правильну роботу ліміту сервера й залежності блокування перед масштабуванням. |
| Backlog запусків workflow | operator_metrics.starts.*, телеметрія запуску площини керування, schedule_to_start перших завдань worker | Блокувальне за тривалого стану, рекомендаційне за короткого | pending_commands, ready_tasks чи max_pending_ms тривало перевищують базовий рівень за наявності сумісних worker і місткості черг | Перевірте шлях запуску наскрізно: перетворення команд у надійні завдання, своєчасне створення першого завдання matching/dispatch, відокремлення боргу запуску від загальної затримки worker перед масштабуванням. |
| Відхилення проєкцій і борг repair | run_summary_projection / selected_run_projections health checks, operator_metrics.repair.* | Рекомендаційне | Попередження відхилень тривають довше планового вікна rebuild або найбільший вік кандидата зростає | Перегляньте rebuild/repair, виконайте виправлення, підтвердьте зникнення попередження й повернення віку до базового рівня. |
| Шторм повторних спроб чи помилок | operator_metrics.backlog.unhealthy_tasks, надійна діагностика виконань, телеметрія помилок worker | Рекомендаційне, з переходом у блокувальне за перешкоджання надійному прогресу | Помилки dispatch/claim, прострочені lease чи вичерпання retry тривало перевищують базовий рівень топології | Перевірте сімейство помилкових завдань, порівняйте телеметрію worker з надійними фактами помилок і вирішіть щодо drain трафіку чи ізоляції черги. |
| Погіршення прискорення пробудження | long_poll_wake_acceleration і зведення категорії acceleration | Рекомендаційне | Попередження прискорення триває після вікна обслуговування кешу чи notifier | Перевірте кеш і поширення пробудження. Вважайте це збоєм коректності лише за одночасного погіршення correctness. |
Мета: сповіщати про ризик надійного контракту, а не про кожен тимчасовий сигнал. Сповіщення черг і worker стають блокувальними лише за загрози операторському контракту фактичної топології.
Очікування щодо rebuild, repair і restore
Якщо операторська поверхня повідомляє про відхилення, виконуйте перевірки в такому порядку:
-
Перевірте
GET /waterline/api/v2/health.- Попередження
run_summary_projectionіselected_run_projectionsозначають доступність Waterline, але потребу відновлення фактів списку чи деталей. command_contract_snapshotsозначає, що старі виконання потребують backfill контракту WorkflowStarted для довіри до оголошених форм signal, update чи query.durable_resume_pathsозначає, що відкриті виконання потребують відновлення до використання їхнього спроєктованого наступного джерела продовження.
- Попередження
-
Перегляньте роботу проєкцій:
php artisan workflow:v2:rebuild-projections --needs-rebuild --dry-run -
Відновіть відповідні проєкції:
php artisan workflow:v2:rebuild-projections --needs-rebuild -
Перегляньте роботу backfill контрактів команд:
php artisan workflow:v2:backfill-command-contracts --dry-run -
Виконайте backfill контрактів, якщо поточний клас workflow досі доступний:
php artisan workflow:v2:backfill-command-contracts -
Використовуйте
--prune-staleлише після навмисного видалення надійних рядків процедурою retention для видалення проєкцій, чиї виконання або рядки історії більше не існують.
operator_metrics.repair.* публікує охоплення проходів циклу відновлення.
За кількістю кандидатів, вибраних записів, найбільшим віком кандидата та
навантаженням на межу сканування оцінюйте відповідність роботи базовому рівню
чи потребу дослідження місткості.
Перевірка експорту й архіву
Експорт історії й архівування мають різні призначення:
- Експорт історії створює артефакт replay, налагодження чи архіву.
- Архівування позначає закрите виконання як архівне для вилучення з активних оглядів парку.
- Prune видаляє проєкції чи надійні рядки після завершення строку retention.
Використовуйте цю послідовність перевірки:
-
Експортуйте вибране виконання:
php artisan workflow:v2:history-export <workflow-instance-id> --run-id=<workflow-run-id> --output=storage/app/workflow-history/run.json --pretty -
Перевірте наявність очікуваного ID виконання, версії схеми й налаштованих метаданих приховування даних.
-
Архівуйте закрите виконання лише після збереження експорту в місці, передбаченому інструкцією.
-
Зберігайте архівні, але ще не видалені виконання для розслідування інцидентів.
-
Видаляйте надійні рядки завданням retention, потім відновіть/очистіть проєкції через
workflow:v2:rebuild-projections --prune-stale.
Відповідні маршрути експорту історії й архівування Waterline наведені в довіднику операторського API Waterline.
Контракт резервних копій і аварійного відновлення
Резервні копії й аварійне відновлення входять до меж експлуатації. Для кожної підтримуваної топології опублікуйте й відпрацюйте:
- Надійний набір резервних копій: база даних, образ Server чи застосунку, файл середовища runtime чи конфігурація, розташування матеріалів автентифікації та точні примітки топології чи відновлення для повторного підключення worker.
- Цілі відновлення: максимально прийнятне відставання відновлених даних, очікувана затримка перемикання та право оголосити трафік знову безпечним.
- Порядок відновлення: надійне сховище, кеш, bootstrap чи міграції, єдина роль планувальника чи обслуговування, готовність API, реєстрація worker.
- Перевірку:
/api/readyчи/waterline/api/v2/health,/api/cluster/infoза наявності, одну репрезентативну реєстрацію worker та один експорт історії з відновленого стану. - Прохід виправлення: відновлення проєкцій, backfill контрактів за потреби та повернення метрик черг, сумісності й відновлення до базового рівня перед оголошенням середовища здоровим.
Кілька регіонів і split-brain залишаються поза підтримуваними межами експлуатації 2.0. Посібник самостійного розгортання зберігає архітектуру active/passive та матеріали інструкцій лише для оцінювання із підтримкою. Він не встановлює гарантій самостійної реплікації, failover, failback, RPO чи RTO. Поточний контракт керованого runtime Cloud розміщує кожен namespace в одному керованому регіоні й також не обіцяє багаторегіональної реплікації чи регіональних failover і failback.
Частота тренувань відновлення також належить до публічного операторського контракту. Щонайменше відпрацьовуйте задокументовану послідовність:
- до першого production розгортання топології
- після зміни механізму резервних копій, схеми/bootstrap, моделі автентифікації чи топології
- регулярно за опублікованим графіком у тій самій інструкції, що й частота резервних копій
Якщо немає дати останнього успішного тренування, тривалості відновлення та доказів перевірки, резервні копії й DR для цієї топології залишаються непідтвердженою заявою.
Межі benchmark
Durable Workflow v2 публікує виміри для benchmark вашого середовища. Зафіксуйте базові показники в тестовому чи canary середовищі, перш ніж production трафік почне залежати від них:
| Вимір | Базові показники | Джерело |
|---|---|---|
| Здоров'я проєкцій | Сталий needs_rebuild = 0, тривалість rebuild після навмисного відхилення й час очищення застарілих/осиротілих записів | /waterline/api/v2/health, /waterline/api/stats, workflow:v2:rebuild-projections |
| Навантаження черг | Вік backlog і найстарішого готового завдання, готові й відкладені завдання, швидкість додавання й доставлення, вік простроченого dispatch, застарілі poller, стан допуску (accepting, saturated, throttled, no_slots, no_active_workers) | Статистика й черги Waterline, operator_metrics.backlog.* / operator_metrics.tasks.* |
| Затримка запуску workflow | Прийняті команди запуску, що очікують першого завдання, найстаріший очікуваний запуск і отримання першого завдання після допуску | operator_metrics.starts.* і телеметрія schedule_to_start worker |
| Затримка schedule-to-start | Очікування workflow й activity від постановки до початку | Метрики SDK worker |
| Пробудження масових timer | Час поширення пробудження й затримка видимості готового завдання від запланованого спрацювання за сплеску timer | Телеметрія worker і перевірки координації пробудження в одному регіоні |
| Вартість проходу repair | Кандидати, вибрані записи, найбільший вік кандидата й відсутнього виконання, навантаження сканування | operator_metrics.repair.* |
| Навантаження історії | Кількість подій, розмір історії й рекомендовані пороги continue-as-new | operator_metrics.history.* |
Це виміри benchmark, а не універсальні обіцянки затримки. Опублікуйте прийнятні діапазони для своєї топології.
Докази тривалого тесту
Самих знімків benchmark недостатньо. Перш ніж вважати топологію надійною для тривалого трафіку, зберігайте докази тривалого тесту, що показують дотримання заявлених меж у часі.
Щонайменше включіть:
- форму навантаження: топологія, образ Server чи ревізія застосунку, build ID worker, розташування черг, бекенди кешу й бази даних, репрезентативна суміш запусків workflow, timer, activity, query та експортів
- вікно тесту: початок і кінець та тривалість, що охоплює хоча б одне звичайне вікно repair, один прохід retention чи архівування за потреби та характерну зміну трафіку бізнес-циклу цього середовища
- стабільність надійних черг: вік backlog, готових завдань і backlog запусків, співвідношення додавання й доставлення завдань і кількості застарілих poller в межах опублікованого базового рівня топології
- стабільність коректності: без тривалого
status = errorвідGET /waterline/api/v2/health, непоясненого ростуoperator_metrics.repair.*і постійних прогалин сумісності вoperator_metrics.workers.* - стабільність процесів і кешу: обмежені пам'ять, CPU, навантаження циклу подій чи потоків worker та розмір/кількість записів кешу без монотонного росту за сталого навантаження
- докази відновлення: час останньої успішної резервної копії та тренування відновлення, тривалість відновлення й команди перевірки готовності
Зберігайте набір там, де оператори можуть отримати інструкцію розгортання. Заявлені числа benchmark, семантику сповіщень чи час відновлення без відповідного тривалого тесту вважайте попередніми, а не перевіреними доказами меж експлуатації.
Наскрізний контрольний список оператора
Використовуйте цей список після оновлень і перед довірою до нового середовища:
- Виконайте
php artisan workflow:v2:doctor --strict. - Перевірте
GET /waterline/api/v2/healthі визначте станok,warningчиerror. - Прочитайте
GET /waterline/api/stats: backlog, repair, історія, контракти команд, сумісність worker та відхилення проєкцій. - За повідомлення про відхилення перегляньте відновлення проєкцій чи backfill контрактів.
- Експортуйте репрезентативне виконання та перевірте шлях артефакту архіву/replay.
- Підтвердьте зникнення архівних виконань з активних оглядів парку зі збереженням надійних рядків до очищення retention.
- Відпрацюйте послідовність restore чи failover з інструкції розгортання й перевірте відповідність виміряної затримки опублікованому очікуванню топології.