AWS.Logger.Core 3.3.3

AWS 日志 .NET

此存储库包含与亚马逊云服务集成的流行 .NET 日志框架插件。这些插件使用 Amazon CloudWatch 日志服务将日志数据写入配置的日志组。这些日志可以使用 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 Group设置日志保留策略。此功能通过NewLogGroupRetentionInDays配置属性启用。必须将DisableLogGroupCreation配置属性设置为false。用这种方式配置的保留策略只会应用于直接由这些库创建的新日志组。默认情况下，不会对新创建的日志组应用保留策略。

请注意，NewLogGroupRetentionInDays配置属性的值必须是CloudWatch支持的值，否则将导致应用策略时出现非致命错误。应用程序和日志记录将继续，但由于程序错误，不会应用保留策略。

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 Logging
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 凭据搜索路径进行查找。在这种情况下，将查找一个名为 default 的配置文件，搜索环境变量或搜索 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 凭据搜索路径进行查找。在这种情况下，将查找一个名为 default 的配置文件，搜索环境变量或搜索 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 Logging

• 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 的 ActionLintLoggingBuilder> 中调用 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凭证搜索路径查找。它将查找名为默认值的配置文件、环境变量或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一起使用。