用途：为 Python 应用加入结构化日志、指标与追踪，使生产环境出问题时无需重新部署即可回答“发生了什么、在哪里、为什么”。适用场景包括添加结构化日志、用 Prometheus 实现指标采集、跨服务分布式追踪、在请求链中传递关联 ID、调试生产问题以及构建可观测性看板。
主要能力与核心概念：一是结构化日志，以 JSON 输出并保持字段一致，便于机器查询与告警，本地开发可考虑人类可读格式；二是四大黄金信号，在每个服务边界跟踪延迟、流量、错误与饱和度；三是关联 ID，为单个请求在所有日志与 span 中贯穿唯一 ID，实现端到端追踪；四是有界基数，指标标签值须有界，用户 ID 等无界标签会推高存储成本。
使用方式：可用 structlog 配置 JSON 输出，示例配置包含 TimeStamper、JSONRenderer 等处理器，并在应用启动时初始化。日志字段应保持一致，包含 correlation_id、method、path、user_id 等；日志级别按语义使用：DEBUG 用于开发诊断，INFO 用于请求生命周期与操作，WARNING 用于可恢复异常，ERROR 用于需关注的失败，不应把预期行为记为 ERROR。关联 ID 可在入口生成或读取 X-Correlation-ID 头，通过 ContextVar 与 structlog.contextvars 绑定，并在 FastAPI 中间件中设置与回传响应头，出站请求用 httpx 携带该头向下游传播。
限制与注意：资料未提供具体安装命令、版本要求、Prometheus 与追踪的具体配置代码及完整示例，详细模式见 references/details.md。应避免过度设计、忽视性能与安全、测试覆盖不足及文档不同步。