Serilog.Sinks.AwsCloudWatch 4.2.25

dotnet add package Serilog.Sinks.AwsCloudWatch --version 4.2.25
NuGet\Install-Package Serilog.Sinks.AwsCloudWatch -Version 4.2.25
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Serilog.Sinks.AwsCloudWatch" Version="4.2.25" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Serilog.Sinks.AwsCloudWatch --version 4.2.25
#r "nuget: Serilog.Sinks.AwsCloudWatch, 4.2.25"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Serilog.Sinks.AwsCloudWatch as a Cake Addin
#addin nuget:?package=Serilog.Sinks.AwsCloudWatch&version=4.2.25

// Install Serilog.Sinks.AwsCloudWatch as a Cake Tool
#tool nuget:?package=Serilog.Sinks.AwsCloudWatch&version=4.2.25

Serilog Sink for AWS CloudWatch

This Serilog Sink allows to log to AWS CloudWatch.

Version and build status

NuGet version

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.

Installation

dotnet add package Serilog.Sinks.AwsCloudWatch

CloudWatchSinkOptions

This library provides an 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,
    QueueSizeLimit = 10000,
    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 Fluent Code First

Call the extension method passing the configuration values that you wish to make use of.

  // setup AWS CloudWatch client
  var client = myAppConfigRoot.GetAWSOptions().CreateServiceClient<IAmazonCloudWatchLogs>();

  // Attach the sink to the logger configuration
  Log.Logger = new LoggerConfiguration()
    .WriteTo.AmazonCloudWatch(
		"myLogGroup/" + env.EnvironmentName, 
		batchSizeLimit = 100,
		queueSizeLimit = 10000,
		batchUploadPeriodInSeconds = 15,
		createLogGroup = true,
		maxRetryAttempts = 3
		cloudWatchClient = 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:
  
  <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}"
    }
  }

Alternatively you may configure the library without creating a concrete instance of the ICloudWatchSinkOptions interface however this will cause the AWS Service client to follow the credential rules in the official AWS SDK documentation. You may configure any of the passed values in the Extension method.

  {
    "Serilog": {
        "Using": [ "Serilog.Sinks.AwsCloudWatch" ],
        "MinimumLevel": "Verbose",
        "WriteTo": [            
            {
                "Name": "AmazonCloudWatch",
                "Args": {
                    "logGroup": "your-app",
                    "logStreamPrefix": "environment/component",
                    "restrictedToMinimumLevel": "Verbose"
                }
            }
        ]
    }
  }

or using XML:

  <add key="serilog:using:AwsCloudWatch" value="Serilog.Sinks.AwsCloudWatch" />
  <add key="serilog:write-to:AmazonCloudWatch.logGroup" value="your-app" />
  <add key="serilog:write-to:AmazonCloudWatch.logStreamPrefix" value="environment/component" />
  <add key="serilog:write-to:AmazonCloudWatch.restrictedToMinimumLevel" value="Verbose" />

Configuring Credentials

AmazonCloudWatchLogsClient from the AWS SDK requires AWS credentials. To correctly associate credentials with the library, please refer to The Official AWS Recommendation 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
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (14)

Showing the top 5 NuGet packages that depend on Serilog.Sinks.AwsCloudWatch:

Package Downloads
Serilog.Sinks.AwsCloudWatch.Extensions

Configuration extension for the AwsCloudWatch Serilog sink

Informatique.Base.Core

Base classed used in Project in Core

CBORD.Omni.Domain

Package Description

LShared.Frameworks

Package Description

Lyte.Libraries.Web

Lyte Standard Web Library

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
4.2.25 3,024 4/11/2024
4.2.24 4,347 4/2/2024
4.2.19 13,338 3/18/2024
4.2.17 2,407 3/15/2024
4.1.15 879 3/15/2024
4.1.14 164 3/15/2024
4.0.182 475,135 9/20/2023
4.0.180 480 9/19/2023
4.0.178 566,791 7/12/2023
4.0.171 5,287,673 4/22/2021
4.0.168 540,758 2/11/2021
4.0.167 45,555 2/11/2021
4.0.161 682,366 9/9/2020
4.0.159 992,586 2/28/2020
4.0.155 797,038 5/22/2019
4.0.149 228,704 2/22/2019
4.0.145 4,814 2/19/2019
4.0.143 30,841 2/11/2019
4.0.140 225,512 10/15/2018
4.0.138 2,053 10/12/2018
4.0.135 1,743 10/11/2018
4.0.131 133,738 9/4/2018
4.0.125 140,702 7/18/2018
4.0.119 70,085 7/3/2018
3.0.114 132,739 6/22/2018
3.0.110 3,238 6/22/2018
3.0.106 164,733 5/16/2018
3.0.101 25,235 5/3/2018
3.0.97 157,184 2/1/2018
3.0.93 86,706 1/5/2018
3.0.86 17,190 11/6/2017
3.0.77 4,802 10/30/2017
2.0.75 4,500 10/27/2017
2.0.73 47,539 8/14/2017
2.0.67 54,894 5/12/2017
2.0.62 6,806 4/26/2017
2.0.54 12,539 3/9/2017
2.0.51 2,316 2/8/2017
2.0.49 5,693 10/28/2016
2.0.46 1,938 10/12/2016
2.0.45 1,279 10/11/2016
2.0.41 1,528 10/9/2016
2.0.39 1,497 9/15/2016
2.0.0 4,078 6/29/2016
0.1.19 1,650 4/28/2016
0.1.17 1,307 4/28/2016
0.1.13 1,336 3/20/2016
0.1.11 8,118 3/20/2016
0.0.1-beta-8 1,080 3/20/2016