Extensions.Logging.Prime 0.1.2

Prime

ASP.NET Core 结构化日志组件，支持应用日志、HTTP 请求日志、异常日志和 EF Core 审计日志，内置 Vue.js 可视化面板。

功能特性

• 应用日志 — 通过 ILogger 接口自动记录，与现有日志代码零侵入集成
• HTTP 日志 — 中间件自动记录请求/响应信息（方法、路径、头、体、状态码、耗时）
• 异常日志 — 自动捕获异常详情（堆栈、请求上下文、请求体）
• 审计日志 — 通过 EF Core ISaveChangesInterceptor 记录数据变更（增/删/改）
• 可视化面板 — 内置 Vue 3 + PrimeVue 前端，嵌入为静态资源，无需独立部署
• 高并发优化 — Channel<T> 异步队列 + 多消费者批量写入 + 自适应批处理 + 数据库原生批量导入
• 备用容错 — 数据库写入失败时自动回退到文件日志，避免静默丢失
• 多数据库支持 — SQL Server / MySQL / PostgreSQL
• 多框架支持 — 同时兼容 .NET 8 / .NET 9 / .NET 10

项目结构

src/
├── Extensions.Logging.Prime                         # 主项目（ILoggerProvider、中间件、面板）
├── Extensions.Logging.Prime.Database                # 数据库层（DbContext、实体、审计拦截器）
├── Extensions.Logging.Prime.Migrations.SqlServer     # SQL Server 迁移
├── Extensions.Logging.Prime.Migrations.MySql         # MySQL 迁移
└── Extensions.Logging.Prime.Migrations.PostgreSQL    # PostgreSQL 迁移

samples/
└── Sample.PrimeApi                                   # 示例项目

快速开始

1. 安装 NuGet 包

dotnet add package Extensions.Logging.Prime

2. 配置日志服务

在 Program.cs 中：

using Extensions.Logging.Prime;
using Extensions.Logging.Prime.Database.Configuration;

var builder = WebApplication.CreateBuilder(args);

builder.Logging.AddPrime(cfg =>
{
    cfg.DbProvider = DatabaseType.PostgreSQL;
    cfg.ConnectionString = builder.Configuration.GetConnectionString("Default")!;
    cfg.PrimeUserName = "prime";      // 面板登录账号
    cfg.PrimePassword = "prime";      // 面板登录密码
    cfg.HttpLogIgnoreRouteMatch = "/swagger";  // 忽略 HTTP 日志记录的路由
});

var app = builder.Build();
app.Run();

启动后访问 http://localhost:xxxx/prime 即可打开日志面板。应用启动时自动执行数据库迁移。

3. 启用审计日志（可选）

在 DbContext 注册时添加审计拦截器：

builder.Services.AddDbContext<AppDbContext>((sp, options) =>
{
    options.UseNpgsql(connectionString);
    options.AddPrimeAuditingInterceptor(sp);  // ← 添加审计拦截器
});

拦截器会自动记录 SaveChanges 中的增/删/改操作，包含操作人、时间、变更内容。

配置项

高并发调优

builder.Logging.AddPrime(cfg =>
{
    cfg.DbProvider = DatabaseType.PostgreSQL;
    cfg.ConnectionString = connectionString;

    // 高并发场景调优
    cfg.QueueCapacity = 20_000;    // 增大队列容量
    cfg.BatchSize = 1000;          // 增大批次
    cfg.BatchIntervalMs = 100;     // 缩短间隔
    cfg.ConsumerCount = 4;         // 增加并行消费者
    cfg.FallbackLogPath = "/var/log/myapp/fallback";  // 自定义备用日志路径
});

架构

ILogger.Log()                    请求线程（同步，无阻塞）
    ↓
Channel<T> TryWrite()            无锁入队，O(1)
    ↓
BackgroundService (N 个消费者)    并行消费
    ├── 自适应批次：队列深度 > 5000 → BatchSize×2
    ├──            队列深度 > 2000 → BatchSize
    ├──            队列深度 > 500  → BatchSize/2
    └──            队列深度 ≤ 500  → BatchSize/4（低延迟）
    ↓
BulkInserter                     原生批量写入数据库
    ├── PostgreSQL → COPY 二进制导入（比 SaveChanges 快 10-50x）
    ├── SQL Server → 批量 INSERT（200 行/批）
    └── MySQL      → 批量 INSERT（2000 行/批）
    └── 失败 → FallbackFileLogger → JSON 文件

批量写入性能对比

日志类型

应用日志（AppLogs）

通过 ILogger 自动记录：

logger.LogInformation("User {UserId} logged in", userId);
logger.LogWarning("Cache miss for key {Key}", key);
logger.LogError(ex, "Failed to process order {OrderId}", orderId);

HTTP 日志（HttpLogs）

中间件自动记录每个 HTTP 请求：

• 请求方法、路径、查询参数、请求头（敏感头已脱敏）、请求体
• 响应状态码、响应头、响应体（超过 1MB 仅记录标记）
• 客户端 IP、连接 ID、TraceId、耗时

静态文件、Swagger 等路由可配置忽略。

异常日志（ExceptionLogs）

当 ILogger.Log 传入异常对象时自动记录：

• 异常类型、消息、堆栈
• 完整 HTTP 请求上下文（方法、路径、头、请求体）

审计日志（SaveChangesAudits）

通过 EF Core 拦截器记录数据变更：

• 操作人（从 HttpContext 获取）
• 操作类型（Insert / Update / Delete）
• 变更内容（序列化的实体快照）
• 开始/结束时间、是否成功、错误信息

面板 API

所有 API 位于 {RouteMatch}/api 路径下，需 Basic 认证。

前端构建

面板前端源码位于 src/Extensions.Logging.Prime/wwwroot，技术栈：Vue 3 + Vite + PrimeVue + Tailwind CSS。

cd src/Extensions.Logging.Prime/wwwroot
npm install
npm run build    # 构建到 dist/ 目录，编译时嵌入为资源

修改前端后需重新 dotnet build 以更新嵌入资源。

技术栈

• 后端：.NET 8 / .NET 9 / .NET 10 / ASP.NET Core / EF Core 9
• 前端：Vue 3 / Vite / PrimeVue / Tailwind CSS
• 数据库：PostgreSQL (Npgsql) / MySQL (Pomelo) / SQL Server
• 依赖：Yitter.IdGenerator（雪花 ID）

License

MIT