From bd9a67d776b2587705729d06374d3443f0a43113 Mon Sep 17 00:00:00 2001
From: MSuMshk <2039814060@qq.com>
Date: Tue, 2 Dec 2025 13:31:10 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9EOpenTelemetry?=
 =?UTF-8?q?=E6=8E=A5=E5=85=A5=E6=8C=87=E5=BC=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Document/11_SystemTodo.md            |  2 +-
 Document/14_OpenTelemetry接入指引.md | 40 ++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 Document/14_OpenTelemetry接入指引.md

diff --git a/Document/11_SystemTodo.md b/Document/11_SystemTodo.md
index d37014e..076085d 100644
--- a/Document/11_SystemTodo.md
+++ b/Document/11_SystemTodo.md
@@ -21,7 +21,7 @@
 - [x] 商户/门店/商品/订单/支付/配送等实体与仓储实现完成，提供 CRUD + 查询。
 - [x] 系统参数、默认租户、管理员账号、基础字典的种子脚本可重复执行。
 
-## 3. 稳定性与质量
+## 3. 稳定性与质量(低优先级)
 - [ ] Dictionary/Identity/Storage/Sms/Messaging/Scheduler 的 xUnit+FluentAssertions 单元测试框架搭建。
 - [ ] WebApplicationFactory + Testcontainers 拉起 Postgres/Redis/RabbitMQ 的集成测试模板。
 - [ ] .editorconfig、.globalconfig、Roslyn 分析器配置仓库通用规则并启用 CI 检查。
diff --git a/Document/14_OpenTelemetry接入指引.md b/Document/14_OpenTelemetry接入指引.md
new file mode 100644
index 0000000..bdfcd50
--- /dev/null
+++ b/Document/14_OpenTelemetry接入指引.md
@@ -0,0 +1,40 @@
+# 14_OpenTelemetry 接入指引
+
+> 现状：Admin/Mini/User API 已集成 OTel 埋点，可导出到 Collector/控制台/文件日志，默认关闭 OTLP 导出。
+
+## 1. 依赖与版本
+- NuGet：`OpenTelemetry.Extensions.Hosting`、`OpenTelemetry.Instrumentation.AspNetCore`、`OpenTelemetry.Instrumentation.Http`、`OpenTelemetry.Instrumentation.EntityFrameworkCore`、`OpenTelemetry.Instrumentation.Runtime`、`OpenTelemetry.Exporter.OpenTelemetryProtocol`、`OpenTelemetry.Exporter.Console`。
+- 当前 EF Core instrumentation 由 NuGet 回退到 `1.10.0-beta.1`（会提示 NU1603/NU1902），待可用时统一升级到稳定版以消除告警。
+
+## 2. 程序内配置（Admin/Mini/User API）
+- Resource：`ServiceName` 分别为 `TakeoutSaaS.AdminApi|MiniApi|UserApi`，`ServiceInstanceId = Environment.MachineName`。
+- Tracing：开启 ASP.NET Core、HttpClient、EF Core（禁用 SQL 文本）、Runtime；采样器默认 `ParentBased + AlwaysOn`。
+- Metrics：开启 ASP.NET Core、HttpClient、Runtime。
+- Exporter：
+  - OTLP（可选）：读取 `Otel:Endpoint`，非空时启用。
+  - Console：`Otel:UseConsoleExporter`（默认 Dev 开启，Prod 关闭）。
+- 日志：Serilog 输出 Console + 文件（按天滚动，保留 7 天），模板已包含 TraceId/SpanId（通过 Enrich FromLogContext）。
+
+## 3. appsettings 配置键
+```json
+"Otel": {
+  "Endpoint": "",                 // 为空则不推 OTLP，例如 http://otel-collector:4317
+  "Sampling": "ParentBasedAlwaysOn",
+  "UseConsoleExporter": true      // Dev 默认 true，Prod 建议 false
+}
+```
+- 环境变量可覆盖：`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_ENDPOINT` 等。
+
+## 4. Collector/后端接入建议
+- Collector 监听 4317/4318（gRPC/HTTP OTLP），做采样/脱敏/分流，再转发 Jaeger/Tempo/ELK/Datadog 等。
+- 生产注意：限制导出 SQL 文本（已关闭）、对敏感字段脱敏，必要时在 Collector 做 TraceIdRatioBased 采样以控量。
+
+## 5. 验证步骤
+1) 开启 `Otel:UseConsoleExporter=true`，本地运行 API，观察控制台是否输出 Span/Metric。  
+2) 配置 `Otel:Endpoint=http://localhost:4317` 并启动 Collector，使用 Jaeger/Tempo UI 或 `curl http://localhost:4318/v1/traces` 验证链路。  
+3) 文件日志：查看 `logs/admin-api-*.log` 等，确认包含 TraceId/SpanId。
+
+## 6. 后续工作
+- 待 NuGet 源更新后，升级到稳定版 OTel 包并消除 NU1603/NU1902 告警。  
+- 如需采集日志到 ELK，可直接用 Filebeat/Vector 读取 `logs/*.log` 推送，无需改代码。  
+- 如需控制采样率或关闭某些 instrumentation，调整 appsettings 中的 Sampling/开关后重启即可。