Стилевые правки

2025-12-06 19:13:19 +03:00
parent 116134a85e
commit 306eec90e8
3 changed files with 84 additions and 23 deletions
@@ -1,6 +1,4 @@
-# Статусы задач в Airflow
-
-# Статусы задач в Airflow — что означают цвета и как ими пользоваться
+# Статусы задач в Airflow: как понимать и использовать

 ## Почему статусы задач так важны?

@@ -8,56 +6,115 @@

 ## Основные статусы, которые вы увидите каждый день

-В интерфейсе Airflow каждая задача отображается определенным цветом. Вот что означают самые важные статусы:
+В интерфейсе Airflow каждая задача подсвечивается цветом — по нему можно быстро понять, что с ней происходит. Для первых шагов достаточно запомнить несколько базовых статусов, которые удобно разделить на три группы.

-![Статусы задач в интерфейсе Airflow](_attachments/task_status_interface.png)
-
-### Простое объяснение всех статусов
-
-Давайте разберем каждый статус простым языком:
+**1. Всё хорошо**

 **🟢 Успешно (success)** — ваша задача выполнилась без ошибок. Это то, к чему мы стремимся!

+**🟣 Пропущена (skipped)** — задача была намеренно пропущена (часто в ветвящихся пайплайнах).
+
+**2. Есть проблема**
+
 **🔴 Ошибка (failed)** — что-то пошло не так. Задача упала, и вам нужно разбираться в коде.

-**🟡 В очереди (queued)** — задача ждет своей очереди на выполнение. Это нормально, особенно если у вас много задач или мало ресурсов.
+**3. Идёт работа или ожидание**

 **🔵 Выполняется (running)** — задача сейчас активно работает. Просто подождите немного.

-**⚪ Нет статуса (none/no status)** — задача еще не готова к запуску, потому что не выполнены её зависимости.
+**🟡 В очереди (queued)** — задача ждет своей очереди на выполнение. Это нормально, особенно если у вас много задач или мало ресурсов.

 **🟠 Запланирована (scheduled)** — все готово к запуску, Airflow вот-вот начнет выполнение.

-**🟣 Пропущена (skipped)** — задача была намеренно пропущена (часто в ветвящихся пайплайнах).
+**⚪ Нет статуса (none/no status)** — задача еще не готова к запуску, потому что не выполнены её зависимости.

 ### Специальные статусы (встречаются реже)

- **Ошибка в зависимости (upstream_failed)** — предыдущая задача упала, поэтому текущая даже не запускалась
- **Готова к повтору (up_for_retry)** — задача упала, но Airflow попробует запустить её снова (если настроены повторные попытки)
- **Завершена (shutdown)** — задачу принудительно остановили во время выполнения
- **Отложена (deferred)** — задача приостановлена и ждет внешнего события
- **Наблюдение (sensing)** — специальный статус для сенсоров, которые ждут определенных условий
+- **Ошибка в зависимости (upstream_failed)** — предыдущая задача упала, поэтому текущая даже не запускалась.
+- **Готова к повтору (up_for_retry)** — задача упала, но Airflow попробует запустить её снова (если настроены повторные попытки).
+- **Завершена (shutdown)** — задачу принудительно остановили во время выполнения.
+- **Отложена (deferred)** — задача приостановлена и ждет внешнего события.
+- **Наблюдение (sensing)** — специальный статус для сенсоров, которые ждут определенных условий.

 ## Как задача проходит свой путь: пошагово

 Представьте, что у вас есть простая задача. Вот как она проходит свой жизненный цикл:

 1. **Создание** → Статус: "Нет статуса"  
-   Airflow создает задачу, но еще не может её запустить
+   Airflow создает задачу, но еще не может её запустить.

 2. **Готовность** → Статус: "Запланирована"  
-   Все зависимости выполнены, задача готова к работе
+   Все зависимости выполнены, задача готова к работе.

 3. **Ожидание** → Статус: "В очереди"  
-   Задача ждет свободного рабочего места
+   Задача ждет свободного рабочего места.

 4. **Работа** → Статус: "Выполняется"  
-   Задача активно выполняется
+   Задача активно выполняется.

 5. **Завершение** → Статус: "Успешно"  
   Всё прошло отлично!

-![Жизненный цикл задачи в Airflow](_attachments/task_lifecycle_detailed.png)
+На диаграмме ниже показаны те же этапы, но уже с привязкой к внутренним компонентам Airflow.
+
+```mermaid
+flowchart LR
+    %% Стили
+    classDef component fill:#8BC34A,stroke:#333,stroke-width:1px,color:#fff;
+    classDef state     fill:#ffffff,stroke:#333,stroke-width:1px,color:#000;
+    classDef success   fill:#C8E6C9,stroke:#388E3C,stroke-width:1px,color:#000;
+    classDef sensor    fill:#ffffff,stroke:#8BC34A,stroke-width:1px,color:#000;
+
+    %% Жизненный цикл задачи
+
+    NONE["No status / None"]:::state --> SCH[Scheduler]:::component
+
+    SCH --> SCHEDULED[Scheduled]:::state
+    SCH --> REMOVED[Removed]:::state
+    SCH --> UPSTREAM_FAILED[Upstream failed]:::state
+
+    SCHEDULED --> EX[Executor]:::component
+    EX --> QUEUED[Queued]:::state
+    QUEUED --> WORKER[Worker]:::component
+    WORKER --> RUNNING[Running]:::state
+
+    RUNNING --> SUCCESS[Success]:::success
+    RUNNING --> FAILED[Failed]:::state
+    RUNNING --> SHUTDOWN[Shutdown]:::state
+
+    %% Альтернативные переходы при ретраях
+    FAILED -.-> UP_FOR_RETRY["Up for retry"]:::state
+    SHUTDOWN -.-> UP_FOR_RETRY
+    UP_FOR_RETRY --> SCH
+
+    %% Сенсоры: режим reschedule
+    RUNNING --> UP_FOR_RESCHEDULE["Up for reschedule"]:::sensor
+    UP_FOR_RESCHEDULE --> SCH
+
+    %% Все стрелки чуть толще
+    linkStyle default stroke-width:2px;
+
+    %% Альтернативные переходы (ретраи) — зелёные и ещё чуть толще
+    linkStyle 11 stroke:#4CAF50,stroke-width:2.5px;
+    linkStyle 12 stroke:#4CAF50,stroke-width:2.5px;
+```
+### Легенда к диаграмме состояний задачи
+
+**Зелёные блоки (Component)** — внутренние компоненты Airflow, которые двигают задачу по жизненному циклу:
+
+- **Scheduler** — планировщик, проверяет зависимости задач и решает, что ставить в очередь.
+- **Executor** — исполнитель, получает от Scheduler список задач и распределяет их по воркерам.
+- **Worker** — рабочий процесс (worker), который фактически запускает код оператора.
+
+**Белые блоки (Task stage)** — состояния конкретного запуска задачи (task instance, `TaskInstanceState`). На диаграмме они показывают, через какие шаги проходит задача от появления в DAG до успешного завершения или ошибки. Подробный справочник по всем состояниям есть в документации по ссылке ниже.
+
+**Белые блоки с зелёной рамкой (Task stage only for sensor)** — состояния, характерные только для сенсоров:
+
+- **Up for reschedule (`up_for_reschedule`)** — сенсор в режиме `reschedule`: условие ещё не выполнено, задача «усыплена» и позже будет снова поставлена в расписание без непрерывной работы воркера.
+
+> Официальное описание всех состояний `TaskInstanceState` и их жизненного цикла смотрите в документации Airflow:  
+> [Tasks → Task Instances](https://airflow.apache.org/docs/apache-airflow/stable/core-concepts/tasks.html#task-instances).
+

 ## Что делать, если задача упала?

@@ -75,4 +132,8 @@
 - **Остальные статусы** вы будете изучать по мере необходимости
 - **Цвета в интерфейсе** — это быстрый способ понять состояние вашего пайплайна

-Помните: понимание статусов задач — это как научиться читать дорожные знаки. Сначала кажется много информации, но со временем это становится второй натурой!
+Помните: понимание статусов задач — это как научиться читать дорожные знаки. Сначала кажется много информации, но со временем это становится второй натурой!
+
+> Полный список возможных состояний задач (TaskInstanceState) и их классификацию на терминальные и промежуточные можно посмотреть в официальной документации Airflow:
+> https://airflow.apache.org/docs/apache-airflow/2.9.3/_api/airflow/utils/state/index.html
+