Serilog.Sinks.AwsCloudWatch 4.2.29

dotnet add package Serilog.Sinks.AwsCloudWatch --version 4.2.29
NuGet\Install-Package Serilog.Sinks.AwsCloudWatch -Version 4.2.29
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.29" />
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.29
#r "nuget: Serilog.Sinks.AwsCloudWatch, 4.2.29"
#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.29

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

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 net5.0 was computed.  net5.0-windows was computed.  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. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos 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.29 1,869 5/20/2024
4.2.25 30,547 4/11/2024
4.2.24 7,063 4/2/2024
4.2.19 20,279 3/18/2024
4.2.17 3,685 3/15/2024
4.1.15 931 3/15/2024
4.1.14 180 3/15/2024
4.0.182 557,711 9/20/2023
4.0.180 485 9/19/2023
4.0.178 612,074 7/12/2023
4.0.171 5,448,309 4/22/2021
4.0.168 555,764 2/11/2021
4.0.167 45,556 2/11/2021
4.0.161 689,418 9/9/2020
4.0.159 1,001,508 2/28/2020
4.0.155 799,987 5/22/2019
4.0.149 229,078 2/22/2019
4.0.145 4,816 2/19/2019
4.0.143 30,849 2/11/2019
4.0.140 230,294 10/15/2018
4.0.138 2,057 10/12/2018
4.0.135 1,752 10/11/2018
4.0.131 135,595 9/4/2018
4.0.125 143,103 7/18/2018
4.0.119 71,033 7/3/2018
3.0.114 137,749 6/22/2018
3.0.110 3,247 6/22/2018
3.0.106 165,090 5/16/2018
3.0.101 25,248 5/3/2018
3.0.97 157,972 2/1/2018
3.0.93 86,975 1/5/2018
3.0.86 17,223 11/6/2017
3.0.77 4,807 10/30/2017
2.0.75 4,538 10/27/2017
2.0.73 47,708 8/14/2017
2.0.67 54,952 5/12/2017
2.0.62 6,809 4/26/2017
2.0.54 12,542 3/9/2017
2.0.51 2,319 2/8/2017
2.0.49 5,696 10/28/2016
2.0.46 1,942 10/12/2016
2.0.45 1,282 10/11/2016
2.0.41 1,531 10/9/2016
2.0.39 1,513 9/15/2016
2.0.0 4,082 6/29/2016
0.1.19 1,653 4/28/2016
0.1.17 1,308 4/28/2016
0.1.13 1,339 3/20/2016
0.1.11 8,121 3/20/2016
0.0.1-beta-8 1,081 3/20/2016