observability-debugging-contract

What problem does it solve?

为 AgentHub 定义从前端入口到 Gateway、Orchestrator、子 Agent、LLM Provider、Artifact 与 Tool Call 的全链路可观测性与排障契约，确保任何一次 Run 都能用统一关联 ID 和结构化数据快速定位问题原因，同时严格脱敏避免泄漏敏感信息。

Core Features & Use Cases

• Trace Context & ID 关联：规定 traceparent/tracestate 的跨服务传播与 traceId + requestId + runId 的统一串联规则，覆盖 run/plan/step/agentTask/artifact/toolCall/llmRequest 等关联。
• 结构化日志标准：要求后端服务输出 JSON 结构化日志，规定稳定 event dot.case 命名、基础字段集合与安全错误展示字段（errorCode、safeMessage、durationMs）。
• Span 命名与属性规范：定义推荐 span 名称与 agenthub.* 前缀的自定义属性边界，避免将 prompt/token/用户隐私写入 span attributes。
• Metrics 与错误分类：给出覆盖延迟/流量/错误/饱和度的指标命名与低基数维度要求，并提供稳定错误码分域与用户可见错误策略。
• 脱敏与 Debug Dump：定义日志/trace/metrics/debug dump 的禁止与允许字段，提供可控脱敏的 debug dump 快照范围与关闭策略。
• 分进程与多 Agent 排障路径：明确 Gateway↔Orchestrator 分进程关键事件/字段，支持 2+ Agent、ordered_parallel、fallback、群聊消息关联排障。

Quick Start

Use the observability-debugging-contract skill to standardize your AgentHub run tracing, JSON logging, metrics, error codes, and redacted debug dumps so that Gateway-to-Orchestrator and multi-agent failures can be diagnosed quickly without exposing tokens or prompts.