CloudWatch Postman

CloudWatch Postman is a Node server that sends data to Amazon CloudWatch. It enables you to serve an API with endpoints that add or update your metrics/your logs on CloudWatch with your AWS credentials.

• For the moment, configuration of this API is set with environment variables.
• Its first purpose is to serve some endpoints so an cliend-side application can call it to send data to CloudWatch.

• Prerequisites
• Quick start
• How to request the API
  • What is a unique access token?
  • When is a unique access token used?
  • How to get a unique access token?
  • How to generate your client token
• API
• Configuration with Dotenv
• Contributing
• Resources

Prerequisites

• Node.js,
• Redis,
• Amazon CloudWatch,
• an AWS IAM account that can call CloudWatch with read and write access.

Quick start

Install the dependencies:

npm install

Choose an CLIENT_SECRET_KEY and an ACCESS_TOKEN_SECRET_KEY. These secret values will be used by CloudWatch Postman to generate tokens to access the API.

Create a .env file with these secrets and your AWS credentials.

Start the app:

npm run serve

Test the API on http://localhost:8080/test.

How to request the API

You can request the API using a unique access token:

+--------------------+                               +--------------------+
|                    | 2. Ask for an access token.   |                    |
|                    | +------- POST /token -------> |                    |
|                    |                               |                    |
|       Client       | <---------------------------+ |                    |
| (your application) | 3. The API returns a valid    |      The API       |
|                    |    access token.              |                    |
|                    |                               | cloudwatch-postman |
|  1. Create your    |                               |                    |
|     client token.  |                               |                    |
|                    |                               |                    |
|                    |                               |                    |
|                    |                               |                    |
|                    |                               |                    |
|                    | 4. Make API calls with the    |                    |
|                    |    valid access token.        |                    |
|                    |                               |                    |
|                    | +---- eg. POST /metric -----> |                    |
|                    |                               |                    |
|                    | (by default, the access token |                    |
|                    |  is valid for one hour)       |                    |
+--------------------+                               +--------------------+

What is a unique access token?

As CloudWatch Postman is firstly meant to be called by a client-side application, unique access tokens can secure a little bit more the API endpoints.

You need to exchange your client token to obtain a unique access token. The latter have a default expiration of one hour.

When is a unique access token used?

Every endpoint, except the POST /token one, needs an accessToken to be requested. We advise you to fetch it on your client-side application as soon as possible if you know that you will need to query the API.

How to get a unique access token?

You can fetch an accessToken on the POST /token endpoint with your client token.

How to generate your client token

This section explains how to generate an client token to request an access token for the API.

You will needs these values:

• the current timestamp,
• a random salt value,
• your CLIENT_SECRET_KEY,

Concatenate these 3 values and hash them with a sha256 algorithm digested in base64. Here is an example in JavaScript:

import crypto from 'crypto'

const data = `${timestamp}${salt}${appSecretKey}`
const hash = crypto.createHash('sha256').update(data).digest('base64')

Then, generate your token:

• concatenate the date, the salt value and the hash with a :: delimiter,
• encode this string in base64.

Here is an example in JavaScript:

Buffer.from([timestamp, salt, hash].join('::')).toString('base64')

Tokens usage

Name	Usage	How to get it	Expiration
Access token	An access token is used for each call to the API endpoints, except POST /token and GET /test. It has to be included in the JSON body of your calls along with your other parameters { accessToken: "aValidAccessToken" }.	You can fetch a valid access token on POST /token with your client token.	By default, an access token has a one hour validity from the moment it is sent to the client.
Client token	The client token is used to fetch a valid access token on POST /token. It has to be included in the JSON body of your call { clientToken: 'yourClientToken'}.	You have to generate your client token on your side.	By default, a client token has a one day validity from the moment it is generated on your side.

API

You can check the existing endpoints of this API in the documentation.

Configuration with Dotenv

You can set some variables with a .env file and start the app with:

npm run serve

Example

# .env
AWS_ACCESS_KEY_ID=***
AWS_SECRET_ACCESS_KEY=***
AWS_REGION=***
CLIENT_SECRET_KEY=***
ACCESS_TOKEN_SECRET_KEY=***

Variables

The following variables can be setup in the .env file:

Variable	Requirement	Description	Default value
AWS_ACCESS_KEY_ID	Required	The AWS IAM user access key id.
AWS_SECRET_ACCESS_KEY	Required	The AWS IAM user secret access key.
AWS_REGION	Required	The CloudWatch region
CLIENT_SECRET_KEY	Required	Your client secret key. You will share it on your consumer app to generate your client token.
ACCESS_TOKEN_SECRET_KEY	Required	Your access token secret key. It is used to generate all the access tokens.
PORT	Optional	The port on which the server is lauched	8080
CORS_ALLOWED_ORIGIN	Optional	A list of domain origins to which you grant the access to your API. Separate each origin with a comma: alice-in-wonderland.io, the-mad-hatter.com, tweedledee-tweedled.um	*

Contributing

Please refer to the contributing documentation.

Resources

• AWS IAM user policies for CloudWatch
• AWS IAM user credentials
• Amazon CloudWatch API for putMetricData
• Amazon CloudWatch Logs API for putLogEvents