docs: add observability plan

docs/observability-plan.md

@@ -0,0 +1,37 @@
+# 项目监控与可观测性方案
+
+本文档梳理了为 XControl 项目添加监控、日志与追踪能力的计划，涵盖 Prometheus 指标、Loki 日志以及 OpenTelemetry 链路追踪。
+
+## 1. 整体监控架构设计
+- 监控栈：Prometheus + Loki + OpenTelemetry Collector。
+- 统一指标、日志、trace 的命名规范。
+- 通过环境变量或配置文件控制监控开关、采样率与导出端点。
+
+## 2. Prometheus Metrics
+- **Go 服务**：使用 `prometheus/client_golang`，在 `gin` 中挂载 `/metrics`，提供请求延迟、状态码、数据库与 Redis 访问指标。
+- **Node/Next.js 前端**：使用 `prom-client`，暴露基础 HTTP 指标及自定义业务计数。
+- **其他语言组件**：根据语言选择对应 SDK 并添加核心指标。
+- 提供 docker-compose/Helm 配置，让 Prometheus 抓取各服务的 `/metrics`。
+
+## 3. Loki LogQL 日志
+- **Go 端**：采用 `slog` 或 `logrus` + Loki hook，输出 JSON 结构化日志并包含 `{job, service, trace_id}` 等标签。
+- **Node 端**：使用 `pino` 或 `winston`，输出 JSON 日志，通过 Loki transport 或 `promtail` 收集。
+- 在所有日志中注入 `trace_id`、`span_id`，便于与 tracing 关联。
+- 更新部署脚本以配置 Loki 接收端或 promtail。
+
+## 4. OpenTelemetry Tracing
+- **Go 服务**：集成 `go.opentelemetry.io/otel`，启用 gin/pgx/redis 自动 instrumentation，使用 OTLP exporter。
+- **Node/Next.js**：引入 `@opentelemetry/api` 与 `@opentelemetry/sdk-node`，启用 HTTP/Fetch 等自动 instrumentation，发送 trace 到 OTel Collector。
+- 其他语言组件按需选择对应 OTel SDK，实现上下文传递。
+- 将 `trace_id`、`span_id` 加入日志，指标中添加 exemplar/label 实现跨链接。
+
+## 5. 部署与配置管理
+- 提供示例配置或环境变量（`PROMETHEUS_ENDPOINT`, `LOKI_URL`, `OTEL_EXPORTER_OTLP_ENDPOINT`）。
+- 编写 docker-compose 或 Kubernetes manifests，将 Prometheus、Loki 与 OTel Collector 纳入基础设施。
+- 更新文档说明如何在本地与生产环境启用监控以及常用查询示例。
+
+## 6. 验证与测试
+- 为关键监控点编写单元或集成测试，保证指标、日志格式正确。
+- 在 CI/CD 流程中增加 lint/test 防止监控代码被破坏。
+- 本地启动后通过 `curl /metrics`、Loki 查询以及 Jaeger/Tempo UI 验证输出。
+