核心功能
observability-lgtm 是一套面向 FastAPI 应用开发的本地可观测性解决方案，通过单个 Docker Compose 文件即可完整部署 LGTM 技术栈（Loki 日志存储、Grafana 可视化、Tempo 分布式追踪、Prometheus 指标采集）以及 Alloy 日志代理。开发者只需一次 Python import 即可自动完成应用埋点，实现日志→指标→追踪的三位一体关联。
显著优势
1. 极简部署：预置 docker-compose.yml 与零配置 Grafana 数据源，15 秒内完成全栈启动
2. 开箱即用：内置 FastAPI 专属仪表盘，自动展示请求速率、错误率、P99 延迟、端点分布等关键指标
3. 深度关联：通过 OpenTelemetry 自动注入 trace_id 到日志，Grafana 中点击日志即可跳转对应分布式追踪
4. 零网络外泄：所有组件本地自托管，数据 classification 默认为 LOCAL_ONLY，适合敏感开发环境
5. 热更新支持：Prometheus 支持动态服务注册，新增应用无需重启监控栈
局限性
- 仅适用于本地开发：官方明确不推荐用于生产环境，生产应使用 Grafana Cloud 或 Datadog 等托管方案
- FastAPI 专属：Python 埋点库针对 FastAPI 设计，虽底层栈语言无关，但开箱体验仅限 Python 生态
- 依赖 Docker：无 Docker 环境无法使用
- 端口占用敏感：默认使用 3000/3300/9091/4317/4318/12345，需主动检查冲突并调整配置
适合人群
- 需要快速搭建本地可观测性环境的 FastAPI 开发者
- 希望替代笨重 ELK 栈、追求轻量级方案的个人或团队
- 需在本地关联分析多应用日志-指标-追踪的调试场景
- 对数据隐私敏感、拒绝云服务采集的开发环境
常规风险
- 无认证开发模式：Grafana 默认无登录，多人共享机器存在数据暴露风险
- 持久化数据管理：
docker compose down -v会清空所有历史数据，需定期备份或配置外部卷 - 资源占用：同时运行 5+ 容器对低配机器可能造成内存压力（建议 4GB+ 空闲内存）
- DEBUG 日志过滤：Alloy 默认丢弃 DEBUG 级别日志，排查问题时需手动修改配置