AWS.Logger.NLog 3.3.4

AWS 日志 .NET

此仓库包含用于与 Amazon Web Services 集成的流行 .NET 日志框架的插件。插件使用 Amazon CloudWatch Logs 服务将日志数据写入配置的日志组。日志可以使用 AWS CloudWatch 控制台 进行查看和搜索。

查看发布历史请查看 发布变更日志

AWS Lambda

这些包将日志消息批量放入队列，并使用后台线程将消息发送到 CloudWatch 日志。使用后台线程意味着在 AWS Lambda 中使用时，无法保证消息能够被送达。原因是后台线程在一次 Lambda 事件处理完毕后可能会被冻结，而且如果一段时间内没有收到更多的 Lambda 事件，可能永远无法解冻。

当使用 Lambda 时，建议使用 ILambdaContext.Logger.LogLine 或 Amazon.Lambda.Logging.AspNetCore 包。

所需的 IAM 权限

无论使用哪种框架，都必须允许（通过 IAM）提供 AWS 凭证的相关权限。

logs:CreateLogGroup
logs:CreateLogStream
logs:PutLogEvents
logs:DescribeLogGroups

在设置凭据时建议采用最少的权限访问原则。您可以通过在创建策略时引用资源的 ARN（例如日志流）来进一步限制权限范围，将权限限制在特定的资源（如日志流）上。

更多信息和示例 JSON 策略模板，请参阅 AWS 开发者博客上的 Amazon CloudWatch Logs and .NET Logging Frameworks。

可选 IAM 权限

以下 IAM 权限取决于记录器配置的功能。

配置日志流名称

在以下版本之前，这些库遵循 CloudWatch 日志的最佳实践，即生成日志流名称。名称可以通过使用 LogStreamNameSuffix 和 LogStreamNamePrefix 配置属性来定制。

生成名称确保应用程序中的每个进程都有自己的日志流来写入。否则，当某个进程写入相同的流时，维持在该进程内部的 sequenceToken 将变得不同步。这将导致错误和重试，从而影响性能。

2023 年，CloudWatch 日志去除了 SequenceToken 要求，从而消除了需要在多个日志流间分割日志接收以及在不同客户端间协调序列令牌的需求。

以下版本引入了新的 LogStreamName 设置，可以用来指定完整的日志流名称。当设置了此设置后，将忽略 LogStreamNamePrefix 和 LogStreamNameSuffix。

1. AWS.Logger.Nlog - 3.3.0
2. AWS.Logger.Log4net - 3.5.0
3. AWS.Logger.AspNetCore - 3.5.0
4. AWS.Logger.SeriLog - 3.4.0

设置新的日志组保留策略

这些库支持在它们创建的任何 CloudWatch 日志组上设置 日志保留策略。此功能通过使用 NewLogGroupRetentionInDays 配置属性启用。DisableLogGroupCreation 配置属性必须设置为 false。以这种方式的保留策略只适用于这些库直接创建的 新 日志组。默认情况下，不会将保留策略应用于新创建的日志组。

请注意，任何不支持的主题，可通过以下链接查看（以下列出）的 NewLogGroupRetentionInDays 的值都是配置错误，将导致非致命错误应用策略。应用程序和日志记录将继续，但不会应用保留策略。

null, 1, 3, 5, 7, 14, 30, 60, 90, 120, 150, 180, 365, 400, 545, 731, 1096, 1827, 2192, 2557, 2922, 3288, 3653

支持的日志框架

1. NLog
2. Apache log4net
3. ASP.NET Core 日志记录
4. Serilog

NLog

• NuGet 包: AWS.Logger.NLog

NLog 使用目标来接收日志消息。目标可以通过配置文件或代码进行配置。NLog 将自动搜索默认的配置文件 NLog.config。以下是一个配置 AWS 区域和 CloudWatch 日志组的示例配置文件。

<?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"
	  throwConfigExceptions="true">
  <extensions>
    <add assembly="NLog.AWS.Logger" />
  </extensions>
  <targets>
    <target name="aws" type="AWSTarget" logGroup="NLog.ConfigExample" region="us-east-1"/>
  </targets>
  <rules>
    <logger name="*" minlevel="Info" writeTo="aws" />
  </rules>
</nlog>

AWS 凭据将通过标准的 AWS SDK for .NET 凭据搜索路径查找。在这种情况下，它将查找命名为默认的个人资料，搜索环境变量或搜索 EC2 实例上的实例个人资料。要使用特定的 AWS 凭据个人资料，请使用目标上的 profile 属性。

以下是使用代码执行相同配置的示例。

var config = new LoggingConfiguration();

var awsTarget = new AWSTarget()
{
    LogGroup = "NLog.ProgrammaticConfigurationExample",
    Region = "us-east-1"
};
config.AddTarget("aws", awsTarget);

config.LoggingRules.Add(new LoggingRule("*", LogLevel.Debug, awsTarget));

LogManager.Configuration = config;

查看 NLog 示例，了解如何使用 AWS 和 NLog。

Apache log4net

• NuGet 包: AWS.Logger.Log4net

Log4net 配置后端来接收日志消息。后端可以通过配置文件或代码进行配置。要使用配置文件，请将文件添加到您项目中。该文件的名称可以是任何名称，但为了本例，将其称为 log4net.config。确保将 复制到输出目录 设置为复制。以下是一个设置 CloudWatch 日志组和 AWS 区域的示例配置文件。

<?xml version="1.0" encoding="utf-8" ?>
<log4net>
  <appender name="AWS" type="AWS.Logger.Log4net.AWSAppender,AWS.Logger.Log4net">

    <LogGroup>Log4net.ConfigExample</LogGroup>
    <Region>us-east-1</Region>
    
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%-4timestamp [%thread] %-5level %logger %ndc - %message%newline" />
    </layout>
  </appender>

  <root>
    <level value="DEBUG" />
    <appender-ref ref="AWS" />
  </root>
</log4net>

AWS 凭据将通过标准的 AWS SDK for .NET 凭据搜索路径查找。在这种情况下，它将查找命名为默认的个人资料，搜索环境变量或搜索 EC2 实例上的实例个人资料。要使用特定的 AWS 凭据个人资料，请在前端节点下添加一个 Profile。

在应用程序启动期间添加以下代码，以使 log4net 读取配置文件。

// log4net is configured in the log4net.config file which adds the AWS appender.
XmlConfigurator.Configure(new System.IO.FileInfo("log4net.config"));

以下是使用代码执行相同配置的示例。

static void ConfigureLog4net()
{
    Hierarchy hierarchy = (Hierarchy)LogManager.GetRepository();
    PatternLayout patternLayout = new PatternLayout();

    patternLayout.ConversionPattern = "%-4timestamp [%thread] %-5level %logger %ndc - %message%newline";
    patternLayout.ActivateOptions();

    AWSAppender appender = new AWSAppender();
    appender.Layout = patternLayout;

    // Set log group and region. Assume credentials will be found using the default profile or IAM credentials.
    appender.LogGroup = "Log4net.ProgrammaticConfigurationExample";
    appender.Region = "us-east-1";

    appender.ActivateOptions();
    hierarchy.Root.AddAppender(appender);

    hierarchy.Root.Level = Level.All;
    hierarchy.Configured = true;
}

查看 Log4net 示例，了解如何使用 AWS 和 log4net。

ASP.NET Core 日志记录

• NuGet 包: AWS.Logger.AspNetCore

ASP.NET Core 引入了一个新的 日志框架，该框架已配置提供程序以将日志发送到目的地。AWS.Logger.AspNetCore NuGet 包提供了一个日志提供程序，它将 CloudWatch 日志作为日志的目的地。

注意：从 AWS.Logger.AspNetCore 的 2.0.0 版本开始，此库针对 netstandard2.0，并且已升级到 ASP.NET Core 2.1 版本的依赖项。对于 Microsoft 已经宣布停止支持的较旧版本的 .NET Core，请使用 2.0.0 版本之前的版本。

此存储库中的 Web 示例 展示了如何配置此提供程序。

配置在 appsettings.json 文件中设置。在 2.0.0 版本之前的版本中，使用 AWS.Logging 作为配置节根。从 2.0.0 版本开始，库已切换到使用标准的 Logging 配置节根。为了向后兼容，如果 Logging 节不包含 LogGroup，则库将回退到 AWS.Logging。

"Logging": {
  "Region": "us-east-1",
  "LogGroup": "AspNetCore.WebSample",
  "IncludeLogLevel": true,
  "IncludeCategory": true,
  "IncludeNewline": true,
  "IncludeException": true,
  "IncludeEventId": false,
  "IncludeScopes": false,
  "LogLevel": {
    "Default": "Debug",
    "System": "Information",
    "Microsoft": "Information"
  }
}

在典型的 ASP.NET Core 应用程序中，Program.cs 文件包含一个 CreateWebHostBuilder 方法。要包含 AWS.Logger.AspNetCore，请调用 ConfigureLogging，并将传递给 ConfigureLogging 的 Action<ILoggingBuilder> 中的 AddAWSProvider。这将查找添加到依赖项注入系统中的 IConfiguration 中的配置信息。

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging =>
        {
            logging.AddAWSProvider();

            // When you need logging below set the minimum level. Otherwise the logging framework will default to Informational for external providers.
            logging.SetMinimumLevel(LogLevel.Debug);
        })
        .UseStartup<Startup>();

Serilog

• NuGet 包: AWS.Logger.SeriLog

可以使用连接器配置Serilog接收日志消息，无论是通过配置文件还是通过代码。要使用配置文件与Serilog配合，请按照这里的说明安装所需的扩展和NuGet软件包。在json文件中，确保在Using数组中有AWS.Logger.SeriLog。在Serilog节点下设置LogGroup和Region，并在WriteTo节点下添加 AWSSeriLog作为连接器。以下是一个示例。

{
  "Serilog": {
    "Using": [
      "AWS.Logger.SeriLog"
    ],
    "LogGroup": "Serilog.ConfigExample",
    "Region": "us-east-1",
    "MinimumLevel": "Information",
    "WriteTo": [
      {
        "Name": "AWSSeriLog"
      }
    ]
  }
}

将以下代码添加到配置日志使用json文件读取。

var configuration = new ConfigurationBuilder()
.AddJsonFile("appsettings.json")
.Build();

var logger = new LoggerConfiguration()
.ReadFrom.Configuration(configuration)
.CreateLogger();

AWS凭证将使用标准的.NET凭证搜索路径查找。它将寻找名为default的配置文件、环境变量或EC2实例上的实例配置文件。要使用除默认以外的其他配置文件，请在Serilog节点下添加一个Profile。

下面是通过代码进行相同配置的示例。可以使用WriteTo方法将AWS连接器添加到日志记录器。

AWSLoggerConfig configuration = new AWSLoggerConfig("Serilog.ConfigExample");
configuration.Region = "us-east-1";

var logger = new LoggerConfiguration()
.WriteTo.AWSSeriLog(configuration)
.CreateLogger();

查看Serilog示例，了解如何一起使用AWS和Serilog。