Summary Prerequisites and limitations Architecture Tools Best practices Epics Troubleshooting Related resources Additional information

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

Bibhuti Sahu and Rob Hill (AWS), Amazon Web Services

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.

The .NET application writes log data to the NLog logging framework.
NLog writes the log data to CloudWatch Logs.
You use CloudWatch alarms and custom dashboards to monitor the .NET application.

Tools

AWS services

Amazon CloudWatch Application Insights helps you observe the health of your applications and underlying AWS resources.
Amazon CloudWatch Logs helps you centralize the logs from all your systems, applications, and AWS services so you can monitor them and archive them securely.
AWS Identity and Access Management (IAM) helps you securely manage access to your AWS resources by controlling who is authenticated and authorized to use them.
AWS Tools for PowerShell are a set of PowerShell modules that help you script operations on your AWS resources from the PowerShell command line.

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

Set a retention policy for the target log group. This must be done outside of the NLog configuration. By default, log data is stored in CloudWatch Logs indefinitely.
Adhere to the Best practices for managing AWS access keys.

Epics

Task Description Skills required

Task	Description	Skills 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.	Follow the instructions for your operating system in Installing the AWS Tools for PowerShell. 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

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.

Follow the instructions for your operating system in Installing the AWS Tools for PowerShell.
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

Task	Description	Skills required
Install the NuGet package.	In Visual Studio, choose File, and then choose Open a project or solution. Choose the project where you want to install NLog. In Visual Studio, choose Tools, NuGet Package Manager, Package Manager Console. 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.	Open the `NLog.config` file. For the target `type`, enter `AWSTarget`. 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. For the target `region`, enter the AWS Region where CloudWatch Logs is configured. For the target `profile`, enter the name of the profile that you created previously to store to store the access key and secret key. 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

Task	Description	Skills 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

Issue	Solution
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

Working with log groups and log streams (CloudWatch Logs documentation)
Amazon CloudWatch Logs and .NET Logging Frameworks (AWS blog post)

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>

Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Centralize software package distribution in AWS Organizations by using Terraform

Copy AWS Service Catalog products across AWS accounts and Regions