任务实例监控与日志查询 Skill

1. Scenario Description

场景：需要查看 Dataphin 周期任务某个业务日期的实例状态、拉取执行日志，或诊断实例为何未运行/失败。

本 Skill 覆盖实例定位、状态查看、日志拉取、常见未运行原因诊断的完整流程。

Architecture

用户请求 → 确认参数 → list-instances 定位实例
  → get-physical-instance 查看实例详情与状态
  → get-physical-instance-log 拉取 taskrun 日志
  → 根据状态与字段诊断原因

涉及 Dataphin OpenAPI

• ListInstances — 按任务名 + 业务日期查询实例列表
• GetPhysicalInstance — 查询单个实例详情（含状态、暂停标记、阻塞原因、上下游）
• GetPhysicalInstanceLog — 查询实例 taskrun 日志

2. Installation

# 安装 aliyun CLI（>= 3.4.8）
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 安装 dataphin-public 插件
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证
aliyun dataphin-public --help

详见 CLI 安装指南。

3. Environment Variables

凭证与环境变量由父 skill alibabacloud-dataphin-skills 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Credentials Required

Security Rules:

• NEVER 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志）
• NEVER 要求用户在本会话或命令行直接输入 AK/SK
• NEVER 使用 aliyun configure set 写入字面量凭证
• ONLY 使用 aliyun configure list 检查凭证状态

aliyun configure list

检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。

如果没有有效 profile，请在此停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在会话外配置（终端执行 aliyun configure，或在 shell profile 中设置环境变量）
3. 重新运行 aliyun configure list 确认有效后再继续

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

执行前确认 CLI 与插件版本：

aliyun version
aliyun plugin list

5. RAM Policy

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

1. Read ../../ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

本 skill 最小权限见 ../../ram-policies.md。

6. IMPORTANT: Parameter Confirmation

执行查询前必须向用户确认以下参数：

7. 完整命令链

TENANT_ID=<tenant-id>
PROJECT_ID=<project-id>
ENV=PROD
USER_AGENT="AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

# 1) 取真实业务日期（绝对不要依赖会话上下文时间）
TODAY=$(date "+%Y%m%d")
BIZDATE=$(date -v-1d "+%Y%m%d")  # macOS；Linux: date -d "-1 day" "+%Y%m%d"
echo "今天=$TODAY 业务日期(T-1)=$BIZDATE"

# 2) 定位实例（同一业务日期可能有多个 due-time 实例）
aliyun dataphin-public list-instances --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --schedule-type NORMAL --search-text "<task-name>" \
  --min-biz-date $BIZDATE --max-biz-date $BIZDATE \
  --page 1 --page-size 20 \
  --user-agent "$USER_AGENT" --format json \
  | jq '.PageResult.Data[] | {
       InstanceId: .Id,
       NodeName: .NodeInfo.Name,
       BizDate: (.BizDate/1000|todate),
       DueTime: (.DueTime/1000|todate),
       Status: .StatusList,
       Duration,
       StartTime: (if .StartExecuteTime then .StartExecuteTime/1000|todate else null end),
       EndTime: (if .EndExecuteTime then .EndExecuteTime/1000|todate else null end)
     }'

# 3) 查看单个实例详情（含阻塞/暂停/等待原因）
INSTANCE_ID=<上一步返回的 Id>
aliyun dataphin-public get-physical-instance --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --instance-id $INSTANCE_ID \
  --user-agent "$USER_AGENT" --format json \
  | jq '.Instance | {
       Id,
       Name,
       BizDate: (.BizDate/1000|todate),
       DueTime: (.DueTime/1000|todate),
       StatusList,
       SchedulePaused,
       BlockType,
       WaitReason,
       UpStreamList: (.UpStreamList | length),
       DownStreamList: (.DownStreamList | length)
     }'

# 4) 拉取实例日志（taskrun 级）
aliyun dataphin-public get-physical-instance-log --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --instance-id $INSTANCE_ID \
  --user-agent "$USER_AGENT" --format json \
  | jq '.TaskrunLogList[] | {TaskrunId, Status, StartTime, EndTime, Duration, LogContent}'

8. Observability

版本 {version}（Shell 变量 SKILL_VERSION）来自套件 references/manifest.json 的 version 字段，与 session-id 一同继承父技能 §7。直接加载本子技能时先完成父层初始化；所有 CLI / SDK 调用使用父技能名称与同一版本，跨 Shell 调用须重新注入这些值。

本 Skill 属于 alibabacloud-dataphin-skills 套件，继承父 Skill alibabacloud-dataphin-skills 的 session-id，子 Skill 不再重新生成。

所有调用 Alibaba Cloud API 的 aliyun 命令必须携带：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

其中 {session-id} 替换为父 Skill 生成的 32 位小写十六进制字符串。

9. 参数要点

10. 状态诊断

WAIT_SCHEDULE 诊断

aliyun dataphin-public get-physical-instance --dataphin-profile <p> --env $ENV \
  --project-id $PROJECT_ID --tenant-id $TENANT_ID \
  --instance-id $INSTANCE_ID --format json \
  | jq '.Instance | {DueTime: (.DueTime/1000|todate), StatusList, SchedulePaused, BlockType, WaitReason}'

判断逻辑：

• DueTime 未到 + BlockType/WaitReason 为空 → 正常等待，到点自动调度
• DueTime 已过 + 仍为 WAIT_SCHEDULE → 检查 SchedulePaused / BlockType / WaitReason
• SchedulePaused=true → 节点被暂停，需 resume-physical-node
• BlockType/WaitReason 非空 → 按具体原因处理（上游未就绪、资源不足等）

11. 常见报错

12. ✗ 不要做

• ✗ 用调度日填 bizdate：实例按业务日期索引，默认 T-1
• ✗ 未确认 --env 就查询：DEV/PROD 实例隔离
• ✗ 看到 WAIT_SCHEDULE 直接判定异常：先对比 DueTime 和当前时间
• ✗ 未带 --user-agent 调用 aliyun API 命令
• ✗ 硬编码真实 tenant-id / project-id / instance-id

13. 相关命令

• aliyun dataphin-public list-instances — 按任务名 + 业务日期查实例
• aliyun dataphin-public get-physical-instance — 单个实例详情（状态、阻塞、暂停）
• aliyun dataphin-public get-physical-instance-log — taskrun 执行日志
• aliyun dataphin-public list-nodes — 查询节点元数据（含 SchedulePaused）
• aliyun dataphin-public resume-physical-node — 恢复被暂停的节点
• rerun-task-instance — 实例重跑（经套件入口 alibabacloud-dataphin-skills 路由加载）
• pause-task-instance — 实例暂停/恢复（经套件入口路由加载）