Configure logging for .NET applications in Amazon CloudWatch Logs by using NLog - AWS Prescriptive Guidance

Configure logging for .NET applications in Amazon CloudWatch Logs by using NLog

Created by Bibhuti Sahu (AWS) and Rob Hill (AWS) (AWS)

Environment: Production

Technologies: Management & governance; DevOps; Websites & web apps

Workload: Microsoft

AWS services: Amazon CloudWatch Logs

Summary

This pattern describes how to use the NLog open-source logging framework to log .NET application usage and events in Amazon CloudWatch Logs. In the CloudWatch console, you can view the application’s log messages in near real time. You can also set up metrics and configure alarms to notify you if a metric threshold is exceeded. Using CloudWatch Application Insights, you can view automated or custom dashboards that show potential problems for the monitored applications. CloudWatch Application Insights is designed to help you quickly isolate ongoing issues with your applications and infrastructure.

To write log messages to CloudWatch Logs, you add the AWS.Logger.NLog NuGet package to the .NET project. Then, you update the NLog.config file to use CloudWatch Logs as a target.

Prerequisites and limitations

Prerequisites

  • An active AWS account.

  • A .NET web or console application that:

    • Uses supported .NET Framework or .NET Core versions. For more information, see Product versions.

    • Uses NLog to send log data to Application Insights.

  • Permissions to create an IAM role for an AWS service. For more information, see Service role permissions.

  • Permissions to pass a role to an AWS service. For more information, see Granting a user permissions to pass a role to an AWS service.

Product versions

  • .NET Framework version 3.5 or later

  • .NET Core versions 1.0.1, 2.0.0, or later

Architecture

Target technology stack  

  • NLog

  • Amazon CloudWatch Logs

Target architecture

Architecture diagram of NLog writing log data for a .NET application to Amazon ClodWatch Logs.
  1. The .NET application writes log data to the NLog logging framework.

  2. NLog writes the log data to CloudWatch Logs.

  3. You use CloudWatch alarms and custom dashboards to monitor the .NET application.

Tools

AWS services

Other tools

  • Logger.NLog is an NLog target that records log data to CloudWatch Logs.

  • NLog is an open-source logging framework for .NET platforms that helps you write log data to targets, such as databases, log files, or consoles.

  • PowerShell is a Microsoft automation and configuration management program that runs on Windows, Linux, and macOS.

  • Visual Studio is an integrated development environment (IDE) that includes compilers, code completion tools, graphical designers, and other features that support software development.

Best practices

Epics

TaskDescriptionSkills required

Create an IAM policy.

Follow the instructions in Creating policies using the JSON editor in the IAM documentation. Enter the following JSON policy, which has the least-privilege permissions necessary to allow CloudWatch Logs to read and write logs.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "logs:CreateLogGroup", "logs:CreateLogStream", "logs:GetLogEvents", "logs:PutLogEvents", "logs:DescribeLogGroups", "logs:DescribeLogStreams", "logs:PutRetentionPolicy" ], "Resource": [ "*" ] } ] }
AWS administrator, AWS DevOps

Create an IAM role.

Follow the instructions in Creating a role to delegate permissions to an AWS service in the IAM documentation. Select the policy that you created previously. This is the role CloudWatch Logs assumes to perform logging actions.

AWS administrator, AWS DevOps

Set up AWS Tools for PowerShell.

  1. Follow the instructions for your operating system in Installing the AWS Tools for PowerShell.

  2. Use the AWS Tools for PowerShell cmdlets to store your access key and secret key in a profile. For instructions, see Managing Profiles in the AWS Tools for PowerShell documentation.

General AWS
TaskDescriptionSkills required

Install the NuGet package.

  1. In Visual Studio, choose File, and then choose Open a project or solution.

  2. Choose the project where you want to install NLog.

  3. In Visual Studio, choose Tools, NuGet Package Manager, Package Manager Console.

  4. Install the AWS.Logger.NLog NuGet package by entering the following command.

    Install-Package AWS.Logger.NLog -Version 3.1.0
App developer

Configure the logging target.

  1. Open the NLog.config file.

  2. For the target type, enter AWSTarget.

  3. For the target logGroup, enter the name of the log group that you want to use. If the log group doesn't already exist, a new log group with the provided name is automatically created.

  4. For the target region, enter the AWS Region where CloudWatch Logs is configured.

  5. For the target profile, enter the name of the profile that you created previously to store to store the access key and secret key.

  6. Save and close the NLog.config file.

For a sample configuration file, see the Additional information section of this pattern. When you run your application, NLog will write the log messages and send them to CloudWatch Logs.

App developer
TaskDescriptionSkills required

Validate logging.

Follow the instructions in View log data sent to CloudWatch Logs in the CloudWatch Logs documentation. Validate that log events are being recorded for the .NET application. If log events are not being recorded, see the Troubleshooting section in this pattern.

General AWS

Monitor the .NET application stack.

Configure monitoring in CloudWatch as needed for your use case. You can use CloudWatch Logs Insights, CloudWatch Metrics Insights, and CloudWatch Application Insights to monitor your .NET workload. You can also configure alarms so that you can receive alerts, and you can create a custom dashboard for monitoring the workload from a single view.

General AWS

Troubleshooting

IssueSolution

Log data doesn’t appear in CloudWatch Logs.

Make sure that the IAM policy is attached to the IAM role that CloudWatch Logs assumes. For instructions, see the Set up access and tools section in the Epics section.

Related resources

Additional information

The following is a sample NLog.config file.

<?xml version="1.0" encoding="utf-8" ?> <configuration> <configSections> <section name="nlog" type="NLog.Config.ConfigSectionHandler, NLog" /> </configSections> <startup> <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" /> </startup> <nlog> <extensions> <add assembly="NLog.AWS.Logger" /> </extensions> <targets> <target name="aws" type="AWSTarget" logGroup="NLog.TestGroup" region="us-east-1" profile="demo"/> </targets> <rules> <logger name="*" minlevel="Info" writeTo="aws" /> </rules> </nlog> </configuration>