agent-observability

用途：为 LLM 驱动的智能体与 API 建立完整可观测性栈，用于可靠性与调试。主要能力：定义核心指标，包括端到端延迟、单次 LLM 调用延迟与工具调用延迟（Histogram）；Token 用量（prompt、completion、缓存及每请求分布）；成本估算；工具调用次数；错误与重试；在途请求数。使用方式：以 Prometheus 客户端命名约定定义指标（如 agent_request_duration_seconds、llm_prompt_tokens_total、llm_cost_dollars_total、llm_errors_total、llm_retries_total、agent_active_requests）。使用 OpenTelemetry Python SDK 初始化追踪（TracerProvider、BatchSpanProcessor、OTLPSpanExporter），用 traced_llm_call 包装补全调用记录模型、token、耗时与结束原因，用 traced_tool 装饰器包装工具函数记录耗时与状态，并通过 inject/extract 在服务间传播 trace 上下文。内容还涉及结构化日志、Grafana 仪表盘、成本跟踪、Langfuse/Helicone 集成、SLO 定义、调试工作流与追踪中的 PII 脱敏。适用场景：多步工具调用的自主智能体、LLM 后端 API、RAG 管线、多智能体编排、批量推理任务。限制：指引针对真实环境执行，操作前需确认目标、影响范围与回滚计划；未经明确批准不得部署到生产；本文档仅为文档导入，上游脚本与模板未打包；示例命令如 git status && git diff --stat、kubectl diff -f manifest.yaml 仅供参考。