ln-771-logging-configurator

ln-771-logging-configurator

类型： L3 Worker 类别： 7XX 项目引导

为 .NET 和 Python 项目配置结构化 JSON 日志记录。

---

概述

方面	详情
输入	来自 ln-770 的 Context Store
输出	日志配置文件
技术栈	.NET（Serilog）、Python（structlog）

---

阶段 1：接收上下文

从协调器接收 Context Store。

必需上下文：

• STACK：.NET 或 Python
• FRAMEWORK：ASP.NET Core 或 FastAPI
• FRAMEWORK_VERSION：版本号
• PROJECT_ROOT：项目目录路径
• ENVIRONMENT：Development 或 Production

验证：

• 如果未提供 STACK，则从项目文件中检测
• 如果未提供版本，则使用最新稳定版

---

阶段 2：调研当前最佳实践

使用 MCP 工具获取最新文档。

适用于 .NET（Serilog）：

MCP ref: "Serilog ASP.NET Core structured logging configuration"
Context7: /serilog/serilog-aspnetcore

适用于 Python（structlog）：

MCP ref: "structlog Python structured logging configuration"
Context7: /hynek/structlog

需要调研的关键模式：

1. 请求日志中间件
2. 日志增强（关联 ID、用户上下文）
3. 按环境配置日志级别
4. 接收器配置（Console、File、Seq、Elastic）

---

阶段 3：决策点

询问用户的配置偏好。

Q1：日志格式

选项	适用场景
JSON（生产环境推荐）	机器可读，适用于日志聚合系统
美化/彩色（开发环境推荐）	易于阅读，适用于本地调试

Q2：增强字段

字段	描述	默认值
correlationId	跨服务的请求跟踪	✓ 是
userId	已通过身份验证的用户标识符	✓ 是
requestPath	HTTP 请求路径	✓ 是
responseTime	请求耗时，单位为 ms	✓ 是
machineName	服务器主机名	可选
threadId	线程标识符	可选

Q3：日志接收器

接收器	用途
Console	始终启用
File	本地持久化、日志轮转
Seq	结构化日志服务
Elasticsearch	大规模日志聚合

Q4：按环境设置日志级别

级别	Development	Production
默认	Debug	Information
Microsoft.*	Information	Warning
System.*	Information	Warning
应用程序	Debug	Information

---

阶段 4：生成配置

根据技术栈和决策生成文件。

.NET 输出文件

文件	用途
Extensions/LoggingExtensions.cs	服务注册
appsettings.json（更新）	Serilog 配置
appsettings.Development.json（更新）	开发环境覆盖配置

生成流程：

1. 使用 MCP ref 获取当前 Serilog API
2. 生成 LoggingExtensions.cs，其中包含：
   • UseSerilog 配置
   • 请求日志中间件
   • 增强配置
3. 在 appsettings.json 中更新 Serilog 部分

要添加的包：

• Serilog.AspNetCore
• Serilog.Sinks.Console
• Serilog.Sinks.File（如果选择 File 接收器）
• Serilog.Enrichers.Environment（如果选择 machineName）

Python 输出文件

文件	用途
core/logging_config.py	structlog 配置
middleware/logging_middleware.py	请求日志记录

生成流程：

1. 使用 MCP ref 获取当前 structlog API
2. 生成 logging_config.py，其中包含：
   • 处理器链配置
   • 渲染器选择（JSON/Console）
   • 日志级别配置
3. 为 FastAPI 生成 logging_middleware.py

要添加的包：

• structlog
• python-json-logger（如果选择 JSON 格式）

---

阶段 5：验证

验证配置是否正常工作。

验证步骤：

1. **检查导入项：**确保所有包均可用

   • .NET：dotnet list package | grep Serilog
   • Python：pip list | grep structlog

2. 语法检查：

   • .NET：dotnet build --no-restore
   • Python：python -m py_compile core/logging_config.py

3. 测试日志输出：

   • 启动应用程序
   • 发起测试请求
   • 验证日志格式是否与配置一致

预期日志格式：

{
  "timestamp": "2026-01-10T12:00:00.000Z",
  "level": "info",
  "message": "Request completed",
  "correlationId": "abc-123",
  "requestPath": "/api/health",
  "responseTime": 45,
  "statusCode": 200
}

---

返回给协调器

将结果返回给 ln-770：

{
  "status": "success",
  "files_created": [
    "Extensions/LoggingExtensions.cs",
    "appsettings.json"
  ],
  "packages_added": [
    "Serilog.AspNetCore",
    "Serilog.Sinks.Console"
  ],
  "registration_code": "services.AddLoggingServices(configuration);",
  "message": "Configured structured logging with Serilog"
}

---

幂等性

此技能具有幂等性：

• 阶段 1：检查是否已配置日志记录（使用 Grep 搜索 Serilog/structlog）
• 如果已配置：返回 { "status": "skipped", "message": "Logging already configured" }
• 如果未配置：继续配置

---

参考链接

• Serilog.AspNetCore
• structlog 文档
• ASP.NET Core 日志记录

---

关键规则

• 使用 MCP ref/Context7 获取当前 API 信息——不要凭记忆硬编码 Serilog/structlog 配置
• 确保幂等——如果已配置 Serilog 或 structlog，立即返回 status: "skipped"
• 根据环境设置日志级别——开发环境使用 Debug，生产环境使用 Information（默认级别绝不能是 Warning）
• 始终添加关联 ID 丰富信息——分布式追踪必需
• 返回结构化响应——提供 files_created、packages_added、registration_code，供协调器汇总

完成定义

• 已接收并验证 Context Store（技术栈、框架、版本）
• 已通过 MCP 工具调研目标技术栈的最佳实践
• 已收集用户的选择（格式、丰富信息、接收器、日志级别）
• 已生成配置文件（扩展/配置文件 + appsettings 或 Python 模块）
• 已验证语法（dotnet build 或 py_compile）
• 已向 ln-770 协调器返回结构化 JSON 响应

---

**版本：**2.0.0 **最后更新：**2026-01-10