Configure Logging via AWS Cloudwatch Logs

By default, the SimplyE Circulation Manager currently store all log information locally. For deployments using Docker containers, the logs are stored in a "volume" directory on the EC2 Docker host. Prior to version 2.2.11, the SimplyE Circulation Manager supported only one external log management system: Loggly. In version 2.2.11, the native Amazon Web Services product Cloudwatch Logs has been added. Using an external, centralized logging source can make log analysis easier, and eliminates a problem in maintaining previous log files when removing or replacing a Docker container host instance. The document below is an initial description of the configuration of Cloudwatch Logs in a SimplyE Circulation Manager. In the near future it will be fleshed out with additional information for configuring Cloudwatch Logs in your AWS account to receive the logs from your Circulation Manager instances.

Preparing the AWS Account for Cloudwatch Logs

In order to log to AWS Cloudwatch Logs you need to create a IAM role which grants the Circulation Manager application the following AWS IAM actions:
logs:PutLogEvents
logs:DescribeLogStreams

If you want the application to be able to create the log group and streams for you it needs the following AWS IAM actions:
logs:CreateLogGroup
logs:CreateLogStream

Sample IAM Policy

To support these actions, you should add a policy for the IAM Role. It will have the following attributes as a minimum:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "logs:DescribeLogStreams"
      ],
      "Resource": [
        "arn:aws:logs:::*"
      ]
    }
  ]
} 

Authentication with the AWS Cloudwatch service is handled through the Boto3 library. There are a number of ways to configure the credentials so that the instance has access to Cloudwatch Logs. These options are documented in the Boto3 Credentials Documentation. If you are running the Circulation Manager in AWS, the best practice is to configure logging to use an Instance IAM Role.

Configuring the CloudWatch Logs Integration

After you have prepared your AWS account to use an IAM Role for logging, you need to add configuration details to the Circulation Manager.

1. Log in to the Circulation Manager Admin interface. (See the Logging In document for specific steps if you need them.)
2. Click the Logging item in the left sidebar
3. Enter a descriptive name for this Cloudwatch integration into the Name field 4. Click the Protocol drop-down list 5. Select the AWS Cloudwatch Logs item 6. Provide a log group and log stream name as shown 7. You can accept the default 60 seconds for the update interval, or change as needed 8. Click the AWS Region drop-down list 9. Choose the AWS region which corresponds to the one where your Circulation Manager hosts are deployed 10. Let the Circulation Manager create the log group for you 11. When you've completed and reviewed the settings, click the Submit button to save them
12. (A bit of detail here about what to expect and where to find the logs is needed.)