/observability

name: observability
description: Periodic health sweep of the running system via the debug pipeline (cloud logs / k8s / daemon / DB slices). On a real anomaly, open a bug task (--kind work_item) carrying the evidence refs so it re-enters the bugfix loop. A healthy sweep opens NO task — never fabricate a bug.
license: MIT
scope: common
compatibility:
  - claude-code
  - prismer-sdk
allowed-tools:
  - Bash
metadata:
  category: observability

observability

用 **debug pipeline** 巡检运行中的系统（cloud log / k8s / daemon / DB 切片），**异常时开一个 bug task** 把证据带回 bugfix 循环（`apc/05` S10 · 生命周期矩阵**行 11 监控→回流**）。**触发器 = product205 定时任务后端**（已建，缺前端）挂周期巡检——本 skill 是那次巡检真正干的活，不悬空。

**承重纪律**：

• **healthy 扫描不开 task。** 没有异常就报"绿"并停手——**绝不**为了"有产出"造一个假 bug。一个无论系统健不健康都会建 task 的巡检 = 噪声制造机。
• **异常 → bug task 必须带证据 ref。** bug task 的 description 要挂可追溯锚（pod / workspace / task id + debug 切片摘要，或把 bundle 产物 `cloud asset upload` 后引 `asset:<id>`）。空口"系统好像有问题"不是 bug task。
• **oracle 是真 task 行，不是聊天叙述。** "我建了 bug task" 不算数——`cloud task create` 返回的真 id + 回读的 task 行才算。

**什么时候用**：周期巡检（定时任务触发）或收到"系统是不是出问题了"时——先用 debug pipeline 取副作用切片核实，再决定是否回流。

工具契约（签名以此为准，先核后用）

| 命令 | 作用 | 输出/退出码 | | --- | --- | --- | | `npx tsx scripts/debug/admin-observability.ts capabilities [--env=local\|test\|prod]` | canonical Admin v1 discovery；读取 principal、capabilities、schema version 与 opaque contract digest | `0` 成功；不兼容/无权限非零 | | `npx tsx scripts/debug/admin-observability.ts logs --target-kind=service --target-id=prismer-cloud --purpose=<reason> [--since=15m] [--cursor=<opaque>] [--completeness=require-complete\|allow-partial]` | canonical `POST /api/admin/v1/logs:query` 只读快照；命令内部必须先 discovery；cursor 只能原样回传 | 默认 `require-complete`；置信边界完整 `0`，不满足 `3`，请求/合同错误 `1`，用法错误 `2` | | `cloud admin log-targets --kind <service\|sandbox\|daemon> --purpose <reason> [--workspace-id <id>] [--cursor <opaque>]` | daemon-held credential 下发现 DB-resolved logical targets；不接受 namespace/selector | `0` 完整成功；partial projection `2`；请求失败 `1` | | `cloud admin logs --target-kind <kind> --target-id <id> --purpose <reason> [--attach-to-task [taskId]]` | credentialless loopback 查询 service/sandbox/daemon；可经既有 daemon task-attach 把 JSON 证据绑定到 task | `0` 完整成功；partial `2`；失败 `1`；attach 要求 daemon dispatch + `PRISMER_ARTIFACTS_DIR` | | `npx tsx scripts/debug/inventory.ts [--env=local\|test\|prod] [--json]` | 全局索引：running pods / recent workspaces / recent tasks / **recent errors** | 人读 5 段 或 `--json` | | `npx tsx scripts/debug/bundle.ts <workspace\|task\|pod> <id> [--sections=db,system,k8s,daemon] [--stdout] [--since=ISO]` | 复合切片（DB+system-log+k8s+daemon） | 默认写 `./debug-bundle-*.json`，`--stdout` 打屏 | | `npx tsx scripts/debug/snapshot.ts <workspace\|task\|conversation\|container> <id> [--json\|--brief]` | DB 切片（task 终态行/runs/logs/approvals/assets） | 默认 compact，`--json` raw | | `npx tsx scripts/debug/logs.ts [--contains=text] [--since=ISO\|10m\|1h] [--level=...] [--json]` | cloud 进程 pino ring buffer | 每行一条 或 `--json` | | `cloud task create --title <t> --description <d> --kind work_item [--priority high] [--json]` | **开 bug task**（`--kind work_item` 是 board 投影） | 打印 `ID: <taskId>`（`--json` 出整行） | | `cloud task list [--json]` | 回读 task 行确认落库 | 0 成功 |

• `--kind` 合法值**恰好两个**：`work_item`（默认，bug/工作项）/ `goal`。bug 巡检一律 `work_item`。
• **鉴权**：debug pipeline 走 admin RBAC（`--env=local` dev 短路免鉴权；`--env=test|prod` 需 `PRISMER_API_KEY_TEST`/`PRISMER_API_KEY`）。coding agent 的 workdir env **不注入高危凭据**——test/prod 巡检由平台方持凭发起，不在 agent 的 bash 里裸读（`apc/05` §3 凭据可见性边界）。
• **凭据边界**：canonical 命令没有 `--api-key` 参数，也不把 credential 写入 stdout、stderr 或产物；禁止 `env`、`printenv`、shell tracing（`set -x`）和把 Authorization header 拼进命令行。平台执行器在模型不可见边界注入 credential。
• **合同边界**：只调用 `/api/admin/v1/capabilities` 与 `/api/admin/v1/logs:query`，不猜 403、不回退 legacy route、不猜 digest 算法。若平台固定了本次发布 digest，可由执行器注入 `PRISMER_ADMIN_CONTRACT_DIGEST` 做 exact match。

Workflow

1. 先落调用回执（见文末 ACK 块），再做 canonical discovery + Cloud 日志快照

APC 自动巡检默认要求完整结果。先调用 capabilities，再由同一命令进程完成 logs query：

mkdir -p .e2e-tmp/apc/observability
npx tsx scripts/debug/admin-observability.ts capabilities \
  > .e2e-tmp/apc/observability/admin-capabilities.json
npx tsx scripts/debug/admin-observability.ts logs \
  --target-kind=service --target-id=prismer-cloud --since=15m \
  --purpose="periodic APC observability sweep" \
  --completeness=require-complete \
  > .e2e-tmp/apc/observability/admin-service-logs.json
admin_logs_exit=$?

`admin_logs_exit=3` 表示所需置信边界不完整，**不得宣布 healthy**；读取 JSON 中的 `requestId`、`sources[]`、`partial`、`attemptedSourceTiers`、`availableSourceTiers`、 `confidenceBoundary.productionRetainedRequirement`、`contractDigest`、`evidenceHash` 后报告受限结论。 `attemptedSourceTiers` 只说明服务端尝试过某 tier；只有 `availableSourceTiers` 才代表可用证据， retained source 为 `unavailable` 或 `error` 时严禁把它写成 retained evidence。 只有 human 明确做探索性查询时才可传 `allow-partial`，且逐 source outcome 仍必须保留。`1/2` 是请求或 用法失败，同样不能当作“没有 error”。canonical 输出可作为 task-bound evidence，但先确认其中不含凭据； 不要长期保存为 loose file。

生产环境的 `require-complete` 还有强 gate：必须同时看到 `availableSourceTiers` 包含 `retained`、 `confidenceBoundary.productionRetainedRequirement.satisfied=true`、稳定 ordering/continuity、 完整 coverage、`truncated=false`、`mayDuplicate=false`。任一不满足均按退出码 `3` 处理。 分页时只可把响应 `nextCursor` 原样作为下一次 `--cursor=<opaque>`；不得解析、修改或自行生成 cursor。 SLS 当前只提供 offset continuation，服务端会明确标记 `continuity=best-effort`、`mayDuplicate=true` 和 `partial=true`；即使 provider query 返回 Complete 也不得升级成完整证据。Sandbox/Daemon 查询前先用 `cloud admin log-targets` 发现 logical id，禁止把 Pod、namespace 或 label selector 当 target id 猜测。

2. 拉全局索引，覆盖其余信号面

mkdir -p .e2e-tmp/apc/observability
npx tsx scripts/debug/inventory.ts | tee .e2e-tmp/apc/observability/inventory.md; echo "inventory exit=$?"
npx tsx scripts/debug/inventory.ts --json > .e2e-tmp/apc/observability/inventory.json    # 机器形（可选）

**产物落 repo-relative 的 `.e2e-tmp/apc/observability/`（已在 `.gitignore`），不要落 `/tmp`**——判据要**读回**你引用的那一行，`/tmp` 从仓库根不可解析、跑完即毁的证据等于没有证据（同 test204「证据销毁反 pattern」）。**报告前不许删**这批产物。

读