AWS.Logger.Log4net 3.5.3

AWS Logging .NET

此存储库包含与 Amazon Web Services 集成的流行 .NET 日志框架的插件。插件使用 Amazon CloudWatch 日志服务将日志数据写入配置的日志组。日志可以通过 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和.NET日志框架。

可选IAM权限

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

配置日志流名称

以下版本之前，这些库遵循CloudWatch Logs的最佳实践，即自动生成日志流名称。名称可以通过使用LogStreamNameSuffix和LogStreamNamePrefix配置属性添加后缀或前缀进行自定义。

生成名称确保应用程序中的每个进程都有自己的日志流来写入。否则，当其中一个进程向同一流写入时，进程内维护的sequenceToken将不同步。这会产生错误和重试，导致性能问题。

2023年CloudWatch Logs取消了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。以这种方式配置的保留策略只会应用于由这些库直接创建的新日志组。默认情况下，不会将保留策略应用于新创建的日志组。

请注意，并非所有由 CloudWatch 支持的 （可在此处找到并以下列出）所支持的 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 SDK for .NET 凭据搜索路径找到 AWS 凭据。在这种情况下，它将寻找名为默认配置文件，搜索环境变量或在 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 SDK for .NET 凭据搜索路径找到 AWS 凭据。在这种情况下，它将寻找名为默认配置文件，搜索环境变量或在 EC2 实例上搜索实例配置文件。要使用特定的 AWS 凭证配置文件，请向 appender 节点下添加 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 之前的版本。

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

配置设置在 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 中调用 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可以通过sinks配置以通过配置文件或代码接收日志消息。要使用与Serilog的配置文件，请按照此处的说明安装必要的扩展和NuGet包。在json文件中，确保AWS.Logger.SeriLog在Using数组中。在Serilog节点下设置LogGroup和Region，并在WriteTo节点下添加AWSSeriLog作为sinks。以下是一个例子。

{
  "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凭证搜索路径查找。它将搜索名为默认值的配置文件、环境变量或在EC2实例上的实例配置文件。为了使用默认值之外的配置文件，请在Serilog节点下添加一个Profile。

以下是通过代码完成上述配置的示例。可以通过使用WriteTo方法将AWS sink添加到日志记录器。

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

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

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