调试
- 作者仓库星标 39
- 作者仓库 awesome-omni-skill
- 领域
- 运维部署
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @diegosouzapw · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- Windows
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
第 1 步:识别故障
如果提到特定 DAG:运行 `af runs diagnose <dag_id> <dag_run_id>`(如果提供了 run_id) 如果未指定 run_id,则运行 `af dags stats` 以查找最近的故障 如果未指定 DAG:运行 `af health` 以查找所有 DAG 中的最近故障
第 2 步:获取错误详细信息
确定失败的任务后:使用`af tasks logs <dag_id> <dag_run_id> <task_id>`获取任务日志查找实际异常 - 滚动 Airflow 样板以查找真正的错误对失败类型进行分类:数据问题:丢失数据、架构更改、空值、约束违规
第 3 步:检查上下文
收集其他上下文以了解为什么会发生这种情况:最近的更改:是否有代码部署?检查 git 历史记录(如果可用) 数据量:数据量是否激增?对源表进行快速计数 上游运行状况:上游任务是否成功但产生了意外数据?历史规律:这是一次反复的失败吗?检查之前是否有相同的任务失败
第 4 步:提供可操作的输出
将您的诊断构建为:
# DAG Diagnosis
You are a data engineer debugging a failed Airflow DAG. Follow this systematic approach to identify the root cause and provide actionable remediation.
## Running the CLI
Run all `af` commands using uvx (no installation required):
```bash
uvx --from astro-airflow-mcp af <command>
```
Throughout this document, `af` is shorthand for `uvx --from astro-airflow-mcp af`.
---
## Step 1: Identify the Failure
If a specific DAG was mentioned:
- Run `af runs diagnose <dag_id> <dag_run_id>` (if run_id is provided)
- If no run_id specified, run `af dags stats` to find recent failures
If no DAG was specified:
- Run `af health` to find recent failures across all DAGs
- Check for import errors with `af dags errors`
- Show DAGs with recent failures
- Ask which DAG to investigate further
## Step 2: Get the Error Details
Once you have identified a failed task:
1. **Get task logs** using `af tasks logs <dag_id> <dag_run_id> <task_id>`
2. **Look for the actual exception** - scroll past the Airflow boilerplate to find the real error
3. **Categorize the failure type**:
- **Data issue**: Missing data, schema change, null values, constraint violation
- **Code issue**: Bug, syntax error, import failure, type error
- **Infrastructure issue**: Connection timeout, resource exhaustion, permission denied
- **Dependency issue**: Upstream failure, external API down, rate limiting
## Step 3: Check Context
Gather additional context to understand WHY this happened:
1. **Recent changes**: Was there a code deploy? Check git history if available
2. **Data volume**: Did data volume spike? Run a quick count on source tables
3. **Upstream health**: Did upstream tasks succeed but produce unexpected data?
4. **Historical pattern**: Is this a recurring failure? Check if same task failed before
5. **Timing**: Did this fail at an unusual time? (resource contention, maintenance windows)
Use `af runs get <dag_id> <dag_run_id>` to compare the failed run against recent successful runs.
### On Astro
If you're running on Astro, these additional tools can help with diagnosis:
- **Deployment activity log**: Check the Astro UI for recent deploys — a failed deploy or recent code change is often the cause of sudden failures
- **Astro alerts**: Configure alerts in the Astro UI for proactive failure monitoring (DAG failure, task duration, SLA miss)
- **Observability**: Use the Astro [observability dashboard](https://www.astronomer.io/docs/astro/airflow-alerts) to track DAG health trends and spot recurring issues
### On OSS Airflow
- **Airflow UI**: Use the DAGs page, Graph view, and task logs to inspect recent runs and failures
## Step 4: Provide Actionable Output
Structure your diagnosis as:
### Root Cause
What actually broke? Be specific - not "the task failed" but "the task failed because column X was null in 15% of rows when the code expected 0%".
### Impact Assessment
- What data is affected? Which tables didn't get updated?
- What downstream processes are blocked?
- Is this blocking production dashboards or reports?
### Immediate Fix
Specific steps to resolve RIGHT NOW:
1. If it's a data issue: SQL to fix or skip bad records
2. If it's a code issue: The exact code change needed
3. If it's infra: Who to contact or what to restart
### Prevention
How to prevent this from happening again:
- Add data quality checks?
- Add better error handling?
- Add alerting for edge cases?
- Update documentation?
### Quick Commands
Provide ready-to-use commands:
- To clear and rerun the entire DAG run: `af runs clear <dag_id> <run_id>`
- To clear and rerun specific failed tasks: `af tasks clear <dag_id> <run_id> <task_ids> -D`
- To delete a stuck or unwanted run: `af runs delete <dag_id> <run_id>`
章节与文件索引
按说明文件中的顺序排列。
运行 CLI
第 1 步:识别故障
第 2 步:获取错误详细信息
第 3 步:检查上下文
在阿斯特罗
文件/命令 -> uvx --from astro-airflow-mcp af · af runs diagnose <dag_id> <dag_run_id> · af dags stats · af health · af dags errors · af tasks logs <dag_id> <dag_run_id> <task_id> · af runs get <dag_id> <dag_run_id> · af runs clear <dag_id> <run_id>
内容校验值 -> a4a3508d2f66
当前原文的自动摘译,尚未人工审校。
运行 CLI
使用 uvx 运行所有
af命令(无需安装):在本文档中,af是uvx --from astro-airflow-mcp af的简写。第 3 步:检查上下文
收集其他上下文以了解为什么会发生这种情况:最近的更改:是否有代码部署?检查 git 历史记录(如果可用) 数据量:数据量是否激增?对源表运行快速计数 上游运行状况:上游任务是否成功但产生了意外数据?历史规律:这是一次反复的失败吗?检查之前是否有相同的任务失败
在阿斯特罗
如果您在 Astro 上运行,这些附加工具可以帮助诊断: 部署活动日志:检查 Astro UI 中最近的部署 — 失败的部署或最近的代码更改通常是突然故障的原因 Astro 警报:在 Astro UI 中配置警报以进行主动故障监控(DAG 故障、任务持续时间、SLA 未命中) 可观察性:使用 Astro 可观察性仪表板跟踪 DAG 运行状况趋势并发现重复出现的问题