跳到主要内容
版本：3.0.0

日志（Aegis.Core.Logs）

Aegis.Core.Logs 是 Aegis 的日志集成组件。它负责把日志能力接入到 DI 体系里，并基于 ILogger + NLog 提供统一记录方式。当前组件还会把请求链路里的 RequestId 自动写入日志布局，方便跨接口、跨服务排查问题。

组件概览​

字段说明
组件名称日志
真实类库Aegis.Core.Logs
组件定位日志注册与统一日志布局
引入方式安装 NuGet，并在 Component.deps.json 中启用 Logging
组件声明Logging
日志方案ILogger + NLog
核心能力NLog 接入、统一日志布局、请求标识注入

最小可运行路径​

第一步：启用 Logging​

{
  "Components": {
    "Services": [
      "Logging"
    ]
  }
}

第二步：准备 NLog.config​

日志组件本身负责接入 NLog，但具体日志目标、级别和输出方式，仍然通过 NLog.config 控制。

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets async="true">
    <target name="coloredConsole"
            xsi:type="ColoredConsole"
            layout="${longdate}|${pad:padding=5:inner=${level:uppercase=true}}|${message}" />

    <target name="file"
            xsi:type="File"
            archiveAboveSize="102400"
            fileName=".\Logs\${level}\_${shortdate}.log" />
  </targets>

  <rules>
    <logger name="Microsoft.*" maxlevel="Warning" final="true" />
    <logger name="*" minlevel="Debug" writeTo="file" />
    <logger name="*" minlevel="Info" writeTo="coloredConsole" />
  </rules>
</nlog>

第三步：在容器内的类里直接注入 ILogger<T>​

public class TestService : ITestService
{
    private readonly ILogger<TestService> _logger;

    public TestService(ILogger<TestService> logger)
    {
        _logger = logger;
    }
}

组件实际做了什么​

启用 Logging 后，当前组件主要做了两件事：

  • 把 NLog 注册进 ILogger 日志体系
  • 把统一日志布局改成包含 RequestId 的格式

当前日志布局会带上这些信息：

  • 时间
  • 日志级别
  • RequestId
  • 调用位置
  • 日志消息
  • 异常信息

这也是为什么当请求链路里已经有 ActionContext.Current.RequestId 时，日志里会自动带上请求标识。

什么时候最适合配合 Aegis.Core.Logs​

适合场景：

  • 控制器、服务、仓储层统一记录日志
  • 需要按级别落文件、打印控制台或发送远程日志
  • 需要通过 RequestId 关联一次请求的多条日志
  • 需要把日志转发到 Seq 等日志系统

使用日志时最重要的几条规则​

规则一：优先使用 ILogger<T>​

在被 DI 管理的类中，优先直接注入 ILogger<T>。

public class UserService : IUserContract
{
    private readonly ILogger<UserService> _logger;

    public UserService(ILogger<UserService> logger)
    {
        _logger = logger;
    }
}

规则二：记录异常时不要丢失 Exception​

try
{
    // 业务代码
}
catch (Exception ex)
{
    _logger.LogError(ex, "保存用户失败");
    throw;
}

如果只记字符串，不传 Exception，很多堆栈信息会直接丢失。

规则三：请求日志默认偏 Debug​

当前接口请求/响应日志能力更偏 Debug 级别。
如果你的 NLog 规则最低级别提到了 Info 或更高，接口追踪日志可能就不会落下来。

常见日志级别怎么选​

方法级别适用场景
LogTraceTrace框架级极细追踪，一般不建议业务使用
LogDebugDebug调试步骤、请求细节、排查链路
LogInformationInfo正常业务追踪
LogWarningWarn可预期异常、业务告警
LogErrorError已发生异常
LogCriticalFatal严重故障，业务代码中一般不主动使用

控制最低日志级别要看哪里​

除了 NLog.config，你还需要确认应用配置中的 Logging:LogLevel。

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

如果这里最低级别太高，也会影响实际能否看到某些日志。

Seq 怎么接​

当前日志体系仍然可以把 NLog 目标转发到 Seq。
更稳的做法是：

  1. 安装 NLog.Targets.Seq
  2. 在 NLog.config 里注册扩展
  3. 添加 seq target 和对应规则

具体配置方式见：

接入完成后怎么确认成功​

你至少应该确认这些点：

  • Component.deps.json 中已启用 Logging
  • 应用目录下存在可用的 NLog.config
  • 容器内类可以正常注入 ILogger<T>
  • 日志里能看到 RequestId
  • 发生异常时，异常堆栈不会丢失

常见问题​

为什么已经启用 Logging，但完全没有日志​

优先检查：

  1. Component.deps.json 是否包含 Logging
  2. NLog.config 是否真的在运行目录
  3. NLog.config 是否配置了有效 target 和 rule
  4. 当前日志级别是否把日志过滤掉了

为什么日志里没有 RequestId​

最常见原因是当前代码不在 HTTP 请求链路里，或者请求没有经过 Aegis 默认上下文初始化。
例如后台任务、启动初始化器这类场景，本来就不一定有 ActionContext.Current.RequestId。

为什么请求日志看不到​

优先检查日志最小级别。
如果目标规则最低只收 Info，而请求日志是 Debug，那它自然不会写入。

下一步看哪里​