Overview

Several third-party tools are available to manage and display the metrics produced by Kill Bill. However, one popular tool available directly from AWS is CloudWatch. This package enables you to monitor and display whatever metrics you may find useful from the Kill Bill collection, including metrics that show the performance and resource use of Kill Bill and Kaui themselves, and metrics describing the infrastructure on which these systems run. CloudWatch is included automatically in the Kill Bill CloudFormation option, but it can be used with the other AWS options as well.

In this guide we discuss the use of CloudWatch to manage metrics produced by single-tier and multi-tier implementations on Amazon Web Services (AWS). The latest Amazon Machine Image (AMI) for Kill Bill is preconfigured to direct the Kill Bill metrics to CloudWatch and work with them in the way that best suits your needs. These instructions apply to the Kill Bill AMI version 2021.9 or later.

To set up CloudWatch to manage the metrics available from Kill Bill, there are five steps:

  1. Edit a configuration file to enable the use of CloudWatch.

  2. Install the AWS X-Ray daemon

  3. Create an IAM policy

  4. Create an IAM role

  5. Attach the role to your EC2 instance(s)

Edit the Configuration File

To authorize the sending of the Kill Bill metrics to CloudWatch, it is necessary to edit just one line in this file:

/var/lib/tomcat/bin/setenv2.sh

This file contains configuration information for tomcat, which manages the KillBill web applications.

This is a small file. The line to be edited is:

-Dcom.killbill.cloudwatch.enable=false

This should be changed to:

-Dcom.killbill.cloudwatch.enable=true

After editing the file, go to your AWS EC2 dashboard and reboot the instance so the new configuration file will be read. If you have more than one instance, follow the same procedure for each one.

Install the X-Ray daemon

AWS X-Ray is a service that collects and analyzes data from your applications. A daemon is a process that runs in the background to do a job whenever it is needed. The X-Ray daemon uploads application metrics to X-Ray in batches to be processed. X-Ray then forwards this data to CloudWatch for display.

To setup the daemon, log in to your EC2 instance and run the following commands:

curl https://s3.dualstack.us-east-1.amazonaws.com/aws-xray-assets.us-east-1/xray-daemon/aws-xray-daemon-3.x.deb -o /home/ubuntu/xray.deb
sudo dpkg -i /home/ubuntu/xray.deb

If you have more than one instance, repeat these commands on each one.

Create an IAM Policy

This step creates a policy, or a set of permissions, that is required to access the Kill Bill metrics.

  1. From the EC2 Dashboard, Type "IAM" in the search field at the upper left. Select the IAM Dashboard.

  2. From the left menu, choose Policies, then select Create Policy.

  3. On the page that appears, select the JSON tab. You should see:

    create iam policy

  4. Next, copy the following lines between the square brackets:

            {
                "Effect": "Allow",
                "Action": [
                    "ec2:DescribeTags",
                    "cloudwatch:PutMetricData",
                    "xray:GetSamplingRules",
                    "xray:GetSamplingTargets",
                    "xray:GetSamplingStatisticSummaries",
                    "xray:PutTraceSegments",
                    "xray:PutTelemetryRecords",
                    "logs:CreateLogGroup",
                    "logs:CreateLogStream",
                    "logs:DescribeLogGroups",
                    "logs:DescribeLogStreams",
                    "logs:PutLogEvents"
                ],
                "Resource": "*"
            }
  5. Choose Next:Tags. Then on the next page, click Next:Review.

  6. Now give your policy a name, such as "CloudWatch_Policy". Then click Create Policy.

Your policy will be created.

Create an IAM Role

A role is an identity that has specific permissions defined by a policy. A role can be used to define the permissions for an EC2 instance.

  1. Return to the IAM Dashboard.

  2. From the left menu, choose Roles, then select Create Role. You should see:

    create iam role

  3. Under Common Use Cases, select EC2. Then click Next.

  4. On the next page, select the policy you created. Then click Next.

  5. Give your role a name, such as "CloudWatch_Role". Then click Create Role.

Your role will be created.

Attach Role to EC2 Instance

The last step is to associate your role with your instance(s).

  1. Go to your EC2 Dashboard and select Instances.

  2. Select your instance. If you have more than one select only one.

  3. Select Actions/Security/Modify IAM Role.

  4. From the dropdown list choose the role you just created.

  5. Click Save.

If you have multiple instances, repeat these steps for each one. You may use the same role for all your instances.

Test the Installation

To test your installation, Go to the Cloudwatch console. After a short delay, you should see a set of available metrics. There should be well over 1,000 in your list.

Congratulations. Your CloudWatch integration is complete!

Using CloudWatch

CloudWatch is managed from the CloudWatch console. AWS provides full documentation. If you select All metrics from the left-hand menu, you will see all your available metrics in groups. You can create various types of graphs, collect them into dashboards, set alarms, and perform various other useful actions.