AWS.Logger.AspNetCore 3.5.3

AWS日志.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权限

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

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 设置，可以用来指定完整的日志流名称。当设置了此 setting 时，将忽略 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 配置属性为 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 Logging
4. Serilog

NLog

• NuGet 包： AWS.Logger.Nlog

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

<?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 samples了解如何结合使用AWS和NLog的示例。

Apache log4net

• NuGet包： AWS.Logger.Log4net

Log4net配置appender以接收日志消息。appender可以通过配置文件或代码进行配置。要使用配置文件，请将文件添加到项目中。文件可以命名为任何名称，但为了本示例，将其命名为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凭据搜索路径来查找。在这种情况下，它将查找名为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 samples了解如何结合使用AWS和log4net的示例。

ASP.NET Core Logging

• NuGet包： AWS.Logger.AspNetCore

ASP.NET Core引入了一个新的日志框架，其中提供了发送日志到目的地的提供程序。AWS.Logger.AspNetCore NuGet包提供了一个日志提供程序，它将CloudWatch Logs添加为日志的目的地。

注意：从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<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可以通过配置文件或代码配置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》节点下添加一个《配置文件》。

以下是通过代码执行与上面相同的配置的示例。可以使用WriteTo方法将AWS输出端点添加到日志记录器。

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

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

查看《Serilog样本》以获取如何搭配AWS和Serilog使用的示例。