Serilog Sink for AWS CloudWatch

This Serilog Sink allows to log to AWS CloudWatch. It supports .NET Framework 4.5 and .NET Core.

Version and build status

Usage

There are two important aspects for configuring this library. The first is providing the configuration options necessary via the ICloudWatchSinkOptions implementation. And the second is configuring the AWS Credentials. Both of these are required to log to CloudWatch.

CloudWatchSinkOptions

This library provides single extension method which takes in only a ICloudWatchSinkOptions instance and the IAmazonCloudWatchLogs instance.

Configuration via Code First

The preferred approach for configuration is to construct the necessary objects via code and pass them directly to the library extension method.

// name of the log group
var logGroupName = "myLogGroup/" + env.EnvironmentName;

// customer formatter
var formatter = new MyCustomTextFormatter();

// options for the sink defaults in https://github.com/Cimpress-MCP/serilog-sinks-awscloudwatch/blob/master/src/Serilog.Sinks.AwsCloudWatch/CloudWatchSinkOptions.cs
var options = new CloudWatchSinkOptions
{
  // the name of the CloudWatch Log group for logging
  LogGroupName = logGroupName,

  // the main formatter of the log event
  TextFormatter = formatter,
  
  // other defaults defaults
  MinimumLogEventLevel = LogEventLevel.Information,
  BatchSizeLimit = 100,
  Period = TimeSpan.FromSeconds(10),
  CreateLogGroup = true,
  LogStreamNameProvider = new DefaultLogStreamProvider(),
  RetryAttempts = 5
};

// setup AWS CloudWatch client
var client = new AmazonCloudWatchLogsClient(myAwsRegion);

// Attach the sink to the logger configuration
Log.Logger = new LoggerConfiguration()
  .WriteTo.AmazonCloudWatch(options, client)
  .CreateLogger();

Configuration via config file

While not recommended, it is still possible to config the library via a configuration file. There are two libraries which provide these capabilities.

• Serilog.Settings.AppSettings Configuration is done by App.config or Web.config file. Create a concrete implementation of the ICloudWatchSinkOptions interface, and specify the necessary configuration values. Then in the configuration file, specify the following:

  // {Assembly} name is `typeof(YourOptionsClass).AssemblyQualifiedName` and {Namespace} is the class namespace.
  <add key="serilog:write-to:AmazonCloudWatch.options" value="{namespace}.CloudWatchSinkOptions, {assembly}, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

• Serilog.Settings.Configuration Configuration is done by an appsettings.json file (or optional specific override. Create a concrete implementation of the ICloudWatchSinkOptions interface, and specify the necessary configuration values. Then in the configuration file, specify the following:

  // {Assembly} name is `typeof(YourOptionsClass).AssemblyQualifiedName` and {Namespace} is the class namespace.
  {
    "Args": {
      "options": "{namespace}.CloudWatchSinkOptions, {assembly}"
    }
  }

Configuring Credentials

AmazonCloudWatchLogsClient from the AWS SDK requires AWS credentials. To correctly associate credentials with the library, please refer to The Official AWS Reccomendation on C# for credentials management. To reiterate here:

• Preferred => Use IAM Profile set on your instance, machine, lambda function.
• Create a credentials profile with your AWS credentials.
• Use Environment Variables
• Manually construct the credentials via:

  var options = new CredentialProfileOptions { AccessKey = "access_key", SecretKey = "secret_key" };
  var profile = new Amazon.Runtime.CredentialManagement.CredentialProfile("basic_profile", options);
  profile.Region = GetBySystemName("eu-west-1"); // OR RegionEndpoint.EUWest1
  var netSDKFile = new NetSDKCredentialsFile();
  netSDKFile.RegisterProfile(profile);

Troubleshooting

• Cannot find region in config or Cannot find credentials in config AWS configuration is not complete. Refer to the Configuring Credentials section to complete the configuration.

• Errors related to the setup of the Sink (for example, invalid AWS credentials), or problems during sending the data are logged to Serilog's SelfLog. Short version, enable it with something like the following command:

  Serilog.Debugging.SelfLog.Enable(Console.Error);

Contribution

We value your input as part of direct feedback to us, by filing issues, or preferably by directly contributing improvements:

1. Fork this repository
2. Create a branch
3. Contribute
4. Pull request