observabilitylisted

# Observability Baseline 团队通用观测基线，覆盖 **应用运行时** 与 **AI agent 自身运行时** 两个维度。各项目具体技术选型由 tech-lead 在项目级 ADR 中固化。 ## 应用运行时 ### 结构化日志（必须） - 后端（FastAPI）：用 `structlog` 或 `loguru`，输出 JSON；关键字段：`ts`、`level`、`request_id`、`user_id`（脱敏）、`event`、`latency_ms` - 前端：错误边界 + Sentry SDK；不在控制台打 `console.log`（用 `logger` 抽象） - 严禁日志包含：完整 token / 密码 / 手机号 / 身份证号 / 完整邮箱（参考 `security.md`） ### 链路追踪（推荐） - 接入 OpenTelemetry SDK；后端 → 前端 traceparent 透传 - 慢请求阈值：HTTP 接口 P95 ≤ 500ms（API），LLM 调用 P95 ≤ 5s（流式响应除外） - LLM 调用必须记录：`model`、`prompt_tokens`、`completion_tokens`、`total_cost_cny`、`cache_hit_ratio` ### 指标（推荐） - HTTP���QPS / 错误率 / P50/P95/P99 延迟 - DB：连接池占用、慢查询计数（>200ms） - LLM：调用次数 / 失败率 / 平均 token 消耗 / 日累计成本 ## AI Agent 运行时（Claude Code 自身） ### 内置 `/usage` 查会话 token / cost / cache hit 时跑 Claude Code 内置 `/usage`（不维护项目级 cost log；release retro §3 摘录该输出，见 `agf:running-release-retro` skill）。 自 2.1.149 起 `/usage` 支持**分类成本拆分**：skills / subagents / plugins / **per-MCP-server** 各自的 cost。这是 Agent Team **角色级 / 工具级成本归因**的最快入口——pool 模式下想知道"哪个 MCP、哪类 skill 在烧钱"直接看 `/usage` 分类，不用自建 log。（`/cost` 与 `/stats` 自 2.1.118 已并入 `/usage`。） ### OpenTelemetry 导出（可选启用） `.claude/settings.json` 在 `env` 块预留了占位（前缀 `_OTEL_EXAMPLE_`），生产启用时复制成正式键名： ```jsonc { "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "OTEL_METRICS_EXPORTER": "otlp", "OTEL_LOGS_EXPORTER": "otlp", "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318", "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf", "OTEL_LOG_USER_PROMPTS": "0" } } ``