AWS.Logger.SeriLog 3.4.3

AWS Logging .NET

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

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

AWS Lambda

这些包使用后台线程将日志消息批处理到队列中，并将消息发送到 CloudWatch Logs。使用后台线程意味着在 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 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 Log Groups 设置 日志保留策略。此功能通过使用 NewLogGroupRetentionInDays 配置属性启用。必须不将 DisableLogGroupCreation 配置属性设置为 true。以这种方式配置的保留策略只应用于由这些库直接创建的 新 日志组。

注意，任何不是 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 凭据将使用标准的 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 Log 日志组和 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 凭据配置文件，请在 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 的调用，并将 Action 传递到 ConfigureLogging 中调用 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 文件中，确保 AWS.Logger.SeriLog 在 Using 数组中。在 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实例上的实例配置文件。为了使用非默认配置文件，请在节点下添加一个。

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

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

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

查阅了解如何一起使用AWS和Serilog的示例。