Шаблон: описание Airflow-триггеров и автоматических процессов

Автоматический процесс в Apache Airflow — это DAG (Directed Acyclic Graph): набор задач с порядком выполнения, политиками повторов и условием старта. Этот шаблон фиксирует контракт «когда и с каким контекстом процесс запускается»: тип триггера (trigger), параметры run, зависимости от данных и смежных систем, ожидания по SLA и поведению при ошибках. Он не заменяет 10.01.01 Шаблон User Story, 10.01.02 Шаблон Use Case и REST/Kafka-спецификации — связывает бизнес-цель (BRD/SRS) с технической оркестрацией и задаёт трассировку к downstream-артефактам раздела 10.01.

1. Назначение

Документ пишет системный аналитик; его читают data engineer, backend-разработчик, DevOps/SRE, QA и владелец домена на этапах проектирования, оценки и приёмки batch-/ETL-процессов.

Шаблон закрывает четыре задачи:

• Контракт триггера — условие старта DAG run (расписание, dataset, event/asset, внешнее событие, цепочка DAG, ручной/API) и контекст запуска: conf, params, logical date.
• Сквозная спецификация процесса во времени — что процесс читает и пишет, от чего зависит, какие побочные эффекты допустимы; детали схем — по ссылке, не дублированием.
• Сценарии и политики — happy path, задержка sensor, partial failure, исчерпание retry, backfill/rerun; идемпотентность и параллелизм (max_active_runs); контракт для downstream при сбое.
• Трассировка требований — связь dag_id с BRD/SRS/User Story, интеграционными спецификациями и NFR; по документу можно составить тест-план на каждый тип триггера.

Правило: один dag_id — один экземпляр шаблона. Кросс-DAG связи — явными ссылками на другие 10.01.10 или на 10.01.08 Шаблон сквозной фичи (BPMN-процесс), если batch — часть end-to-end сценария.

2. Когда использовать

Подходит, если:

• процесс оркестрируется в Apache Airflow (или совместимом планировщике с аналогами DAG/trigger — поля раздела 3 маппятся на эквиваленты: cron → schedule, run params → conf, dataset/event/asset → upstream trigger);
• нужно зафиксировать когда процесс стартует и с какими параметрами, а не только «что делает каждая задача»;
• есть зависимости от расписания, публикации dataset, REST-trigger, другого DAG или sensor внутри DAG (файл, сообщение, статус в БД);
• QA и эксплуатация готовят приёмку по SLA, алертам, backfill и сценариям сбоя;
• batch — часть data pipeline: ETL, витрины, отчёты, синхронизация с внешними системами.

Не подходит или требует дополнения, если:

• сценарий — интерактивный customer journey через UI и синхронные API без batch-оркестрации — используйте 10.01.08 Шаблон сквозной фичи (BPMN-процесс); Airflow-шаблон — ссылка на batch-ветку;
• нужен только HTTP-контракт прикладного trigger-endpoint (обёртка в вашем сервисе) — детали в 10.01.04 Шаблон спецификации REST API; в 10.01.10 — условие вызова и mapping conf. Вызов платформенного Airflow REST API (POST .../dagRuns) — отдельный Contract Ref или internal platform spec; формат контракта — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf), практика вызова — 07.02 Работа с API (практика);
• нужна только схема сообщения или топика — 10.01.06 Шаблон спецификации Producer (Kafka, RabbitMQ) / 10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ); здесь — sensor/post-task notify и ссылка;
• процесс — stream processing (Kafka Streams, Flink) без оркестрации DAG — шаблон не про runtime streaming;
• одна cron-задача без интеграций и без требований к rerun/backfill — достаточно строки в SRS и README репозитория; полный шаблон — при критичности или сложных зависимостях.

Входные условия: бизнес-цель и частота зафиксированы в BRD (04.01 Форматы документов (Vision&Scope, BRD, SRS, FRD)), критичность и SLA согласованы с 10.01.12 Шаблон нефункциональных требований (NFR), роли на manual trigger — в 10.01.11 Шаблон ролевой модели, термины и объекты данных — в 10.01.14 Шаблон глоссария и словаря данных. Перед первым заполнением — 10.04 Чеклист аналитика перед стартом разработки.

Граница ответственности аналитика и разработчика:

3. Структура документа

Разделы 3.1–3.12 — оглавление и пояснения полей. Для заполнения скопируйте Приложение A в Confluence, Wiki или репозиторий документации рядом с DAG. Поля с пометкой обяз. нужны для согласования; остальные — по контексту.

3.1. Паспорт процесса (метаданные)

3.2. Бизнес-назначение

3.3. Тип и условие триггера

Укажите один основной тип старта DAG run и дополнительные (если комбинируются). Sensor внутри DAG — не тип старта, а условие продолжения после trigger; фиксируйте отдельно (п. 3.3, последняя строка таблицы).

Различение trigger vs sync: TriggerDagRunOperator / dataset / event создают новый DAG run downstream. ExternalTaskSensor не запускает чужой DAG — блокирует task внутри уже стартовавшего run до завершения upstream за выбранный период. В спецификации не смешивайте эти механизмы в одном поле.

Различение: schedule DAG — «когда стартовать по календарю»; sensor внутри DAG — «продолжить, когда условие истинно». Разные SLA, стоимость workers и риски — фиксируйте отдельно. Технические детали deferrable/poke — в ADR и runbook DE, здесь — timeout, SLA и поведение при fail.

3.4. Входы run (params / conf)

Без задокументированных conf/params и источника истины периода ломаются API-trigger, ручной rerun, цепочки DAG и AC на идемпотентность.

3.5. Выходы и побочные эффекты

3.6. Граф зависимостей

3.7. Сценарии выполнения

В духе 10.01.02 Шаблон Use Case — только сценарии этого DAG, без дублирования всех UC системы. Имена task и операторов в примерах — иллюстрация; в спецификации фиксируйте бизнес-шаги или ссылку на DAG design doc / репозиторий. Детализация SQL, операторов и Connection id — зона data engineer.

3.8. Политики выполнения

3.9. Мониторинг и алерты

SLA только «на весь DAG» при длинном sensor — типичная ошибка: business deadline «данные к 06:00» и sensor timeout 45 min после старта в 02:00 — разные точки отсчёта; зафиксируйте обе.

3.10. Безопасность и доступ

3.11. Критерии приёмки (Acceptance Criteria)

Формулировка AC — 02.04.02 Критерии приёмки (Acceptance Criteria); проверка спецификации — 08.03 Тестирование требований (статическое тестирование).

3.12. ADR и открытые решения

3.13. Чеклист качества перед Review

• Указаны среды и отличия prod vs staging (schedule, API-trigger, dataset/event).
• Timezone, catchup, pause/holidays и поведение при пропуске окна (для schedule).
• Schedule DAG отделён от sensor внутри DAG; trigger downstream (TriggerDagRun/dataset) отделён от sync (ExternalTaskSensor).
• SLA декомпозирован (данные / DAG / sensor).
• Таблица conf/params с примером JSON; источник истины периода согласован с идемпотентностью.
• max_active_runs и политика параллелизма заданы явно.
• Есть сценарий backfill/rerun и правила повторной обработки периода; для P1/P2 — manual rerun → downstream.
• При миграции триггера: окно dual-run, catchup при переключении, impact на downstream (02.05.02 Управление изменениями (Change Control Board)).
• External trigger: тип контракта (прикладной 10.01.04 vs platform API) и Contract Ref.
• Downstream при partial/fail/retry exhausted — явный контракт; согласованность пар выходов (dataset + notify).
• Успех run vs успех бизнес-результата зафиксирован (warnings, skip, soft-fail) и отражён в AC.
• Upstream/downstream без неразрешённых циклов (DAG и через данные).
• Выходы — ссылки на 10.01.03 / 10.01.06–07, без дублирования полных схем.
• По документу можно составить тест-план (08.03 Тестирование требований (статическое тестирование)): trigger каждого типа + fail sensor + retry exhausted.
• Review по процессу — 08.04 Рецензирование и инспекции (техники Фейгана).

4. Пример заполнения

Сокращённый фрагмент — процесс «Ежедневная загрузка витрины продаж dm_sales» (данные условны).

Паспорт. PROC-ETL-DM-01 · dag_id: etl_dm_sales_daily · v1.0 · Review · Owner: Data Platform · Домен: Sales Analytics · BRD BRD-GOAL-044 · SRS SRS-REQ-112–118 · US US-0891 (10.01.01 Шаблон User Story).

Среды. staging: schedule 0 4 * * *, API-trigger разрешён; prod: 0 2 * * *, API-trigger только sa-etl-backfill, catchup=False.

Business outcome. Витрина dm_sales содержит агрегаты продаж за календарный день T-1; отчёты CFO доступны с 06:30 MSK.

Критичность. P2; задержка готовности данных > 2 ч эскалируется в on-call Data Platform. RPO: 24 ч — 10.01.12 Шаблон нефункциональных требований (NFR) NFR-DATA-015.

Триггер (основной, v1). Schedule: 0 2 * * *, timezone Europe/Moscow, catchup=False, start_date=2024-01-01. Дополнительно: Manual и platform REST API для ad-hoc backfill.

Dataset (v2, ADR-078). После релиза v2 schedule отключается (is_paused или удаление cron); единственный старт — dataset s3://datalake/raw/sales/daily после DAG etl_raw_sales_daily. Окно миграции: 2025-09-01 — 2025-09-07 staging-only dual-run (cron + dataset, mutual exclusion по env var); prod cutover 2025-09-08 00:00 MSK; catchup=False при переключении; downstream report_cfo_daily обновляется в тот же change ticket.

External trigger. Platform Airflow API: POST /api/v1/dags/etl_dm_sales_daily/dagRuns — Contract Ref API-PLATFORM-AIRFLOW-DAGRUNS (internal platform spec, OpenAPI — 03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf)). Не путать с прикладным 10.01.04 Шаблон спецификации REST API. Auth: service account sa-etl-backfill; вызов — 07.02 Работа с API (практика).

DAG sync (не trigger). ExternalTaskSensor на task publish DAG etl_raw_sales_daily за тот же business_date — timeout 45 min; это ожидание upstream, не запуск raw-DAG.

Params / conf:

Пример API conf: {"business_date": "2025-08-20", "full_refresh": false}.

Источник истины периода. business_date в conf — период записи и идемпотентности; logical date run — метка оркестратора. При API backfill с business_date ≠ data_interval_start обрабатывается день из conf; logical date не переопределяет партицию.

Logical date. При schedule без явного conf: business_date = календарный день data_interval_start в MSK. Ключ идемпотентности записи: (business_date, region_id).

Upstream. DAG etl_raw_sales_daily (завершение до 01:30 MSK, тот же business_date); таблица staging.sales_orders — DB-STG-SALES-02 (10.01.03 Шаблон спецификации БД сервиса).

Downstream. DAG report_cfo_daily (dataset s3://datalake/mart/dm_sales/published); Consumer CONS-ANALYTICS-012 (10.01.07 Шаблон спецификации Consumer (Kafka, RabbitMQ)) — событие «dm_sales ready» только после task publish_dataset success.

Downstream при fail / согласованность выходов. Partial или failed DAG: dataset не публикуется; Kafka-событие не отправляется; недопустима комбинация «dataset published, Kafka fail». report_cfo_daily использует последнюю успешную партицию; алерт #data-alerts. Idempotency notify: ключ (business_date, event_type) в PROD-ETL-001.

Успех run vs business success. Run считается бизнес-успешным только если validate passed и business outcome (T-1 в dm_sales) достигнут. Task success при warnings в load — run green, но алерт #data-quality; downstream dataset не публикуется до ручного подтверждения owner.

Happy path. 02:00 schedule trigger → sensor «staging за T-1 complete» (timeout 45 min, poke 5 min, SLA sensor: готовность staging до 02:45) → load → validate → publish dataset → notify Kafka → success; downstream стартует по dataset event.

Partial failure. Task validate failed → retry 3×, interval 10 min → при exhausted: DAG failed, алерт Slack #data-alerts, dm_sales не обновляется, downstream не триггерится.

Manual rerun. Clear DAG с business_date; после success — обязательный перезапуск report_cfo_daily за тот же период (TriggerDagRun или dataset republish). Роль ETL_ADMIN (10.01.11 Шаблон ролевой модели) → Airflow role Op на prod.

Политики. max_active_runs=1; retries=3; execution_timeout validate=30 min.

SLA (декомпозиция). (1) Данные T-1 в dm_sales: 06:00 MSK. (2) DAG end (включая publish): 05:30 MSK. (3) Sensor staging: 02:45 MSK.

AC. (1) Schedule run в staging: sensor success до 04:45, DAG success до 05:30 MSK при нормальном upstream. (2) Platform API-trigger с валидным conf создаёт run с тем же business_date в записи. (3) Повторный run за тот же business_date не дублирует строки в dm_sales и не шлёт второе Kafka-событие. (4) Sensor timeout → failed DAG, dataset не published, алерт за ≤ 5 min. (5) Partial validate fail → downstream report_cfo_daily не стартует. (6) Load с warnings, validate skipped — run может быть green, но dataset и Kafka не публикуются (не business success).

5. Связанные артефакты

Границы с соседними шаблонами — в разделе 2 («Не подходит»). В 10.01.10 фиксируйте условие trigger, conf mapping и Contract Ref; детали контрактов — в специализированных артефактах.

На входе (upstream)

На выходе (downstream)

Типичный порядок работы аналитика

1. Из BRD/SRS — business outcome, частота, критичность → выбор типа триггера.
2. Согласование с data engineer: upstream/downstream, dataset vs cron, идемпотентность → ADR при нестандартном выборе (02.05.01 Управление зависимостями между требованиями для цепочки DAG).
3. Таблица conf/params, источник истины периода, сценарии (happy, sensor timeout, backfill, downstream при fail).
4. Contract Ref на БД, API (03.05.03 Спецификации контрактов (OpenAPI, AsyncAPI, Protobuf)), Kafka — параллельная детализация в соседних шаблонах.
5. AC + NFR-срез; review с dev/SRE: тест-план по типам trigger.
6. При изменении триггера или conf — обновление матрицы и downstream DAG specs (02.05.02 Управление изменениями (Change Control Board) при формальном change control).

6. Связи с другими разделами базы

Теория, не дублируемая выше — для углубления и моделирования:

• Event-driven цепочки dataset/event и downstream — 03.05.06 Event-Driven Architecture
• Диаграмма потоков данных для upstream/downstream — 03.04.02 Диаграмма потоков данных (DFD)
• Диаграмма деятельности для сценариев выполнения — 03.02.02 Диаграмма деятельности (Activity Diagram)
• Поставка и версионирование DAG через CI/CD — 05.04 DevOps и непрерывная поставка — влияние на анализ, 07.06 CICD и конвейеры — влияние на требования
• Управление рисками (пропуск окна, двойная запись, миграция триггера) — 08.05 Управление рисками на этапе анализа

7. Источники и дополнительные материалы

Официальная документация Apache Airflow (stable); dataset-aware scheduling — с версии 2.4+.

Спецификации и документация

• Apache Airflow — Concepts: DAGs — https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dags.html
• Apache Airflow — Concepts: DAG Runs — https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/dag-run.html
• Apache Airflow — Concepts: Tasks — https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html
• Apache Airflow — Params — https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/params.html
• Apache Airflow — Cron & timetables — https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/cron.html
• Apache Airflow — Dataset-aware scheduling — https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/datasets.html
• Apache Airflow — Event-based scheduling — https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/event-scheduling.html
• Apache Airflow — Deferrable operators & triggers — https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/deferring.html
• Apache Airflow — Sensors — https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/sensors.html
• Apache Airflow — TriggerDagRunOperator — https://airflow.apache.org/docs/apache-airflow/stable/howto/operator/trigger.html
• Apache Airflow — REST API Reference (Stable) — https://airflow.apache.org/docs/apache-airflow/stable/stable-rest-api-ref.html (операция создания DAG run: POST .../dagRuns)
• Apache Airflow — Authoring and scheduling (раздел документации) — https://airflow.apache.org/docs/apache-airflow/stable/authoring-and-scheduling/index.html

Приложение A. Пустой шаблон (скопировать в документ процесса)

# Спецификация Airflow-процесса: {Название}
 
| Поле | Значение |
|------|----------|
| Process ID | |
| dag_id | |
| Версия / статус / дата | |
| Owner | |
| Домен / сервис | |
| BRD / SRS / US | |
| Ссылка на код DAG | |
| Среды (dev/staging/prod) | |
 
## Бизнес-назначение
 
| Поле | Значение |
|------|----------|
| Business outcome | |
| Частота / окно выполнения | |
| Критичность (Tier) | |
| KPI процесса | |
| Pause / maintenance / holidays | |
 
## Триггер и условия старта
 
| Поле | Значение |
|------|----------|
| Тип триггера (основной) | Schedule / Dataset / Event or Asset / External / DAG chain (trigger) / Manual |
| Комбинация триггеров / mutual exclusion | |
| Schedule (cron, timezone, catchup) | |
| Dataset URI / producer | |
| Event / Asset (имя, producer, семантика) | |
| External trigger (кто, Contract Ref, auth) | |
| DAG chain — trigger downstream (upstream dag_id, conf mapping) | |
| DAG sync — ExternalTaskSensor (upstream dag_id, task, период, timeout) | |
| Manual trigger (роли, сценарии) | |
| Sensor внутри DAG (условие, timeout, SLA) | |
| Окно миграции триггера | |
 
## Параметры run (conf / params)
 
| Имя | Тип | Обяз. | Default | Источник | Описание |
|-----|-----|-------|---------|----------|----------|
| | | | | | |
 
**Пример JSON conf:** `{ }`
 
| Поле | Значение |
|------|----------|
| logical date semantics | |
| Источник истины периода | |
| Совместимость conf и версии DAG | |
 
## Выходы и побочные эффекты
 
| Поле | Значение |
|------|----------|
| Артефакты данных (Contract Ref) | |
| API / уведомления (Contract Ref) | |
| Идемпотентность записи | |
| Идемпотентность side effects | |
| Downstream при fail / partial | |
| Согласованность пар артефактов (dataset + notify + …) | |
| Side effects | |
| Успех run vs успех бизнес-результата | |
 
## Зависимости
 
| Поле | Значение |
|------|----------|
| Upstream (данные, DAG, системы) | |
| Downstream (потребители, trigger/dataset) | |
| Диаграмма (ссылка) | |
| Запрет циклов | |
 
## Сценарии
 
| Сценарий | Описание |
|----------|----------|
| Happy path | |
| Задержка sensor | |
| Partial failure | |
| Retry exhausted | |
| Backfill / rerun | |
| Manual rerun | |
 
## Политики выполнения
 
| Поле | Значение |
|------|----------|
| max_active_runs | |
| Pool / queue / priority | |
| Retries / retry_delay | |
| execution_timeout | |
| Catchup policy | |
 
## Мониторинг и алерты
 
| Поле | Значение |
|------|----------|
| SLA — окно данных | |
| SLA — завершение DAG | |
| SLA — sensor / критичные task | |
| Метрики для приёмки | |
| Каналы алертов | |
| Runbook | |
 
## Безопасность
 
| Поле | Значение |
|------|----------|
| Роли на trigger (домен + Airflow RBAC) | |
| Secrets / Connections (имена) | |
| Аудит manual/API run | |
 
## Критерии приёмки
 
- [ ] 
- [ ] 
 
## ADR и изменения
 
| Поле | Значение |
|------|----------|
| Decision log (ссылки на ADR) | |
| Open questions | |
| История изменений | |