A:初版
This commit is contained in:
jimmy committed
1 parent
237cbd8788
commit
ab3721912d
102 files changed
+7929
-20
No files matched your search
@@ -0,0 +1,101 @@
|
||||
# Sharp.Log
|
||||
|
||||
面向“快速集成”的日志整合层：基于 `Microsoft.Extensions.Logging` 抽象，内置 Serilog 预设，实现一行接入，默认即用（Console + 按日滚动文件，结构化 JSON，丰富上下文）。
|
||||
|
||||
- 目标：不重造日志框架，仅做预设与桥接，减少样板代码
|
||||
- 适用：控制台应用、Worker、ASP.NET Core（含中间件）
|
||||
|
||||
## 特性
|
||||
- 一行集成：`builder.Logging.AddSharpLog()`，无配置也可用
|
||||
- 输出：Console（可彩色）、文件（按日滚动、保留数量、异步写）
|
||||
- 结构化：文本模板/JSON；支持模板+参数与异常详情
|
||||
- 上下文丰富：`Application/Environment/Machine/Process/Thread/TraceId/SpanId`
|
||||
- 过滤：全局最小级别与按分类覆盖
|
||||
- ASP.NET：`UseSharpRequestLogging()` 统一请求日志（开始/结束/异常）
|
||||
- 配置驱动：支持 `appsettings.json:SharpLog` 与环境变量绑定
|
||||
|
||||
## 快速开始
|
||||
1) 引用项目（或 NuGet 包）
|
||||
2) 在应用入口添加一行：
|
||||
|
||||
```csharp
|
||||
// 控制台/Worker 通用
|
||||
var host = Host.CreateDefaultBuilder(args)
|
||||
.ConfigureLogging(b => b.AddSharpLog())
|
||||
.Build();
|
||||
|
||||
// ASP.NET Core
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
builder.Logging.AddSharpLog(); // 一行集成
|
||||
var app = builder.Build();
|
||||
app.UseSharpRequestLogging(); // 可选：请求日志
|
||||
app.Run();
|
||||
```
|
||||
|
||||
无需任何 `appsettings.json`，即可获得：
|
||||
- Console 文本输出
|
||||
- 文件 JSON 输出：`logs/app-.log`（按天滚动，保留 30 个文件，异步写）
|
||||
- 丰富上下文属性
|
||||
|
||||
## 可选配置（appsettings.json）
|
||||
```json
|
||||
{
|
||||
"SharpLog": {
|
||||
"UseSerilog": true,
|
||||
"UseConsole": true,
|
||||
"ConsoleJson": false,
|
||||
"MinLevel": "Information",
|
||||
"Overrides": {
|
||||
"Microsoft": "Warning",
|
||||
"System": "Warning"
|
||||
},
|
||||
"File": {
|
||||
"Enabled": true,
|
||||
"Path": "logs/app-.log",
|
||||
"Rolling": "Day",
|
||||
"RetainedFileCountLimit": 30,
|
||||
"FileSizeLimitBytes": null,
|
||||
"Buffered": true,
|
||||
"Shared": false,
|
||||
"Json": true
|
||||
},
|
||||
"Enrich": {
|
||||
"Enabled": true,
|
||||
"WithThreadId": true,
|
||||
"WithProcessId": true,
|
||||
"WithMachineName": true,
|
||||
"WithEnvironmentName": true,
|
||||
"Application": null,
|
||||
"WithActivityTrace": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
环境变量示例：
|
||||
- `SHARPLOG__MINLEVEL=Warning`
|
||||
- `SHARPLOG__FILE__RETAINEDFILECOUNTLIMIT=7`
|
||||
|
||||
## API 概览
|
||||
- `ILoggingBuilder AddSharpLog(Action<SharpLogOptions>? configure = null)`
|
||||
- `IApplicationBuilder UseSharpRequestLogging()`
|
||||
- 选项：`SharpLogOptions`、`FileOptions`、`EnrichOptions`、`RollingInterval`
|
||||
|
||||
## 常见问题
|
||||
- 需要清空默认 Provider 吗？
|
||||
- 如需仅使用 Sharp.Log，请在调用方执行 `builder.Logging.ClearProviders()`，然后 `AddSharpLog()`。
|
||||
- 一定要 Serilog 吗？
|
||||
- 默认启用（文件/JSON/丰富器等依赖）。如不想使用，可在配置中设置 `UseSerilog=false`，保留框架自带 Console（建议不要 `ClearProviders()`）。
|
||||
- 与分布式追踪兼容吗？
|
||||
- 兼容。自动注入 `Activity.TraceId/SpanId`；若使用 OpenTelemetry，日志会带 Trace 关联信息。
|
||||
|
||||
## 目录
|
||||
- `Options/` 选项模型
|
||||
- `Internal/` Serilog 配置与 Enricher
|
||||
- `Extensions/` 集成扩展
|
||||
- `Middleware/` 请求日志中间件
|
||||
|
||||
```
|
||||
日志要简单可靠：一行接入，默认即用，可配更强。
|
||||
```
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
# 使用说明
|
||||
|
||||
本指南说明如何在不同类型项目中以“最少代码”集成 Sharp.Log，并按需进行配置与扩展。
|
||||
|
||||
## 1. 控制台/Worker 应用
|
||||
```csharp
|
||||
using Microsoft.Extensions.Hosting;
|
||||
using Microsoft.Extensions.Logging;
|
||||
using Sharp.Log.Extensions;
|
||||
|
||||
var host = Host.CreateDefaultBuilder(args)
|
||||
.ConfigureLogging(b => b.AddSharpLog()) // 一行集成，默认 Console + 文件(JSON)
|
||||
.Build();
|
||||
|
||||
var logger = host.Services.GetRequiredService<ILogger<Program>>();
|
||||
logger.LogInformation("Hello from Sharp.Log");
|
||||
|
||||
await host.RunAsync();
|
||||
```
|
||||
|
||||
## 2. ASP.NET Core 应用
|
||||
```csharp
|
||||
using Sharp.Log.Extensions;
|
||||
using Sharp.Log.Middleware;
|
||||
|
||||
var builder = WebApplication.CreateBuilder(args);
|
||||
builder.Logging.AddSharpLog(); // 一行集成
|
||||
|
||||
var app = builder.Build();
|
||||
app.UseSharpRequestLogging(); // 可选：自动请求日志
|
||||
app.MapGet("/", () => Results.Ok("ok"));
|
||||
app.Run();
|
||||
```
|
||||
|
||||
## 3. 可选配置（appsettings.json）
|
||||
添加 `SharpLog` 配置节（可省略）。
|
||||
```json
|
||||
{
|
||||
"SharpLog": {
|
||||
"MinLevel": "Information",
|
||||
"Overrides": { "Microsoft": "Warning" },
|
||||
"UseSerilog": true,
|
||||
"UseConsole": true,
|
||||
"ConsoleJson": false,
|
||||
"File": {
|
||||
"Enabled": true,
|
||||
"Path": "logs/app-.log",
|
||||
"Rolling": "Day",
|
||||
"RetainedFileCountLimit": 30,
|
||||
"Json": true
|
||||
},
|
||||
"Enrich": {
|
||||
"Enabled": true,
|
||||
"WithThreadId": true,
|
||||
"WithProcessId": true,
|
||||
"WithMachineName": true,
|
||||
"WithEnvironmentName": true,
|
||||
"WithActivityTrace": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
环境变量覆盖示例：
|
||||
- `SHARPLOG__MINLEVEL=Warning`
|
||||
- `SHARPLOG__FILE__PATH=/var/logs/app-.log`
|
||||
- `SHARPLOG__FILE__RETAINEDFILECOUNTLIMIT=7`
|
||||
|
||||
## 4. 常见定制
|
||||
- 仅文件输出（关闭 Console）：
|
||||
```csharp
|
||||
builder.Logging.AddSharpLog(o => { o.UseConsole = false; });
|
||||
```
|
||||
- 只文本不 JSON（文件）：
|
||||
```csharp
|
||||
builder.Logging.AddSharpLog(o => { o.File.Json = false; });
|
||||
```
|
||||
- 提升最小级别到 Warning：
|
||||
```csharp
|
||||
builder.Logging.AddSharpLog(o => { o.MinLevel = LogLevel.Warning; });
|
||||
```
|
||||
- 指定应用名（默认读取入口程序集名）：
|
||||
```csharp
|
||||
builder.Logging.AddSharpLog(o => { o.Enrich.Application = "MyApp"; });
|
||||
```
|
||||
|
||||
## 5. 与现有 Provider 协作
|
||||
- 默认不清空 Provider；若希望仅用 Sharp.Log，可在应用中先执行 `ClearProviders()` 再调用 `AddSharpLog()`。
|
||||
- 如将 `UseSerilog` 设为 `false`，不会注入 Serilog Provider，请保留框架自带 Console Provider（不要 `ClearProviders()`）。
|
||||
|
||||
## 6. 请求日志中间件
|
||||
启用后会记录：请求开始、结束（状态码与耗时）、异常。
|
||||
```csharp
|
||||
app.UseSharpRequestLogging();
|
||||
```
|
||||
|
||||
## 7. 结构化与上下文
|
||||
日志条目自动包含：
|
||||
- `Application`、`Environment`、`MachineName`、`ProcessId`、`ThreadId`
|
||||
- `TraceId`、`SpanId`（来自 `Activity.Current`）
|
||||
|
||||
你可使用 `BeginScope` 传入业务上下文：
|
||||
```csharp
|
||||
using var scope = logger.BeginScope(new Dictionary<string, object>{ ["UserId"] = userId });
|
||||
logger.LogInformation("User {UserId} logged in", userId);
|
||||
```
|
||||
|
||||
## 8. 测试建议
|
||||
- 在测试中为文件输出设置临时目录：
|
||||
```csharp
|
||||
builder.Logging.AddSharpLog(o =>
|
||||
{
|
||||
o.UseConsole = false;
|
||||
o.File.Path = Path.Combine(tempDir, "app-.log");
|
||||
o.File.Json = false;
|
||||
});
|
||||
```
|
||||
|
||||
如需更多示例，请参考本仓库的测试项目 `test/Log.Test`。
|
||||
|
||||
Reference in new issue
Block a user