AWSCloudWatchLogs

Latest Version: 1.0.0

You can use AWS CloudWatch Logs to monitor and store your log files from Amazon Elastic Compute Cloud (EC2) instances, AWS CloudTrail, and other sources. You can then retrieve the associated log data from CloudWatch Logs. This class can be used to perform CloudWatch log actions via an Electric Imp.

You can view the library’s source code on GitHub. Click here to see information on the available versions of this library.

Note The AWSCloudWatchLogs library uses AWSRequestV4 for all requests. Therefor the AWSRequestV4 library must also be included in your agent code.

To include this library add the following lines to the top of your agent code:

#require "AWSRequestV4.class.nut:1.0.2"
#require "AWSCloudWatchLogs.agent.lib.nut:1.0.0"

Class Usage

Constructor: AWSCloudWatchLogs(region, accessKeyId, secretAccessKey)

Parameters

Parameter	Type	Required	Description
region	String	Yes	AWS region
accessKeyId	String	Yes	AWS access key ID
secretAccessKey	String	Yes	AWS secret access key

Example

#require "AWSRequestV4.class.nut:1.0.2"
#require "AWSCloudWatchLogs.agent.lib.nut:1.0.0"

const AWS_CLOUDWATCH_LOGS_ACCESS_KEY_ID = "YOUR_KEY_ID";
const AWS_CLOUDWATCH_LOGS_SECRET_ACCESS_KEY = "YOUR_KEY";
const AWS_CLOUDWATCH_LOGS_REGION = "YOUR_REGION";

logs <- AWSCloudWatchLogs(AWS_CLOUDWATCH_LOGS_REGION, AWS_CLOUDWATCH_LOGS_ACCESS_KEY_ID, AWS_CLOUDWATCH_LOGS_SECRET_ACCESS_KEY);

Class Methods

action(actionType, actionParams, callback)

This method performs a specified action (eg. create log group) with any required parameters (actionParams) for the specified action type.

Parameters

Parameter	Type	Description
actionType	Constant	The type of the CloudWatch logging action that you wish to perform (see ‘Action Types’, below)
actionParams	Table	A table of action-specific parameters
callback	Function	A callback function that takes one parameter: a Callback Response Table

Callback Response Table

The response table general to all functions contains the following keys:

Key	Type	Description
body	String	The JSON-encoded CloudWatch response in a function-specific structure
statuscode	Integer	The HTTP status code
headers	Table	See ‘Headers’, below

Headers

The headers table, contains the following keys:

Key	Type	Description
x-amzn-requestid	String	The AWS request ID
connection	String	The connection status
date	String	The date and time at which the response was sent
content-length	String	The length of the content in bytes

Action Types

Action Type	Description
AWS_CLOUDWATCH_LOGS_ACTION_CREATE_LOG_GROUP	Creates a log group with the specified name
AWS_CLOUDWATCH_LOGS_ACTION_CREATE_LOG_STREAM	Creates a log stream for the specified log group
AWS_CLOUDWATCH_LOGS_ACTION_DELETE_LOG_GROUP	Deletes a log group with the specified name
AWS_CLOUDWATCH_LOGS_ACTION_DELETE_LOG_STREAM	Deletes the specified log stream and all the archived log events associated with it
AWS_CLOUDWATCH_LOGS_ACTION_PUT_LOG_EVENTS	Uploads a batch of log events to a specified log stream

Specific actions of the types listed above are configured by passing information into action()’s actionParams parameter as a table with action type-specific keys.

AWS_CLOUDWATCH_LOGS_ACTION_CREATE_LOG_GROUP

This action creates a log group with the specified name. For more details please see the AWS documentation.

Action Parameters

Parameter	Type	Required	Description
logGroupName	String	Yes	The name of the log group you are creating
tags	Table	No	The key-value pairs to use for the tags. Default: `null`

Example

const HTTP_RESPONSE_SUCCESS = 200;
local groupParams = { "logGroupName": "testLogGroup",
                      "tags": { "Environment": "test" } };

logs.action(AWS_CLOUDWATCH_LOGS_ACTION_CREATE_LOG_GROUP, groupParams, function(response) {
  if (response.statuscode == HTTP_RESPONSE_SUCCESS) {
    server.log("Created a log group successfully");
  } else {
    server.log("Failed to create log group. error: " + http.jsondecode(response.body).message);
  }
});

AWS_CLOUDWATCH_LOGS_ACTION_CREATE_LOG_STREAM

This action creates a log stream for the specified log group. For more details please see the AWS documentation.

Action Parameters

Parameter	Type	Required	Description
logGroupName	String	Yes	The name of the existing log group
logStreamName	String	Yes	The name of the log stream you are creating

Example

local params = { "logGroupName": "testLogGroup",
                 "logStreamName": "testLogStream" };

logs.action(AWS_CLOUDWATCH_LOGS_ACTION_CREATE_LOG_STREAM, params, function(response) {
  if (response.statuscode == HTTP_RESPONSE_SUCCESS) {
    server.log("Created a log stream successfully");
  } else {
    server.log("Failed to create log stream. error: " + http.jsondecode(response.body).message);
  }
});

AWS_CLOUDWATCH_LOGS_ACTION_DELETE_LOG_GROUP

This action deletes a log group with the specified name. For more details please see the AWS documentation.

Action Parameters

Parameter	Type	Required	Description
logGroupName	String	Yes	The name of the log group you want to delete

Example

local deleteParams = { "logGroupName": "testLogGroup" };

logs.action(AWS_CLOUDWATCH_LOGS_ACTION_DELETE_LOG_GROUP, deleteParams, function(response) {
  if (response.statuscode == HTTP_RESPONSE_SUCCESS) {
    server.log("Deleted log group successfully");
  } else {
    server.log("Failed to delete log group. error: " + http.jsondecode(response.body).message);
  }
});

AWS_CLOUDWATCH_LOGS_ACTION_DELETE_LOG_STREAM

This action deletes the specified log stream and permanently deletes all of the archived log events that have been associated with the log stream. For more details please see the AWS documentation.

Action Parameters

Parameter	Type	Required	Description
logGroupName	String	Yes	The name of the log group
logStreamName	String	Yes	The name of the log stream you are deleting from the log group

Example

local params = { "logGroupName": "testLogGroup",
                 "logStreamName": "testLogStream" };

logs.action(AWS_CLOUDWATCH_LOGS_ACTION_DELETE_LOG_STREAM, deleteParams, function(response) {
  if (response.statuscode == HTTP_RESPONSE_SUCCESS) {
    server.log("Deleted log stream successfully");
  } else {
    server.log("Failed to delete log stream. error: " + http.jsondecode(response.body).message);
  }
});

AWS_CLOUDWATCH_LOGS_ACTION_PUT_LOG_EVENTS

This action uploads a batch of log events to the specified log stream. For more details please see the AWS documentation.

Action Parameters

Parameter	Type	Required	Description
logEvents	Array of tables	Yes	An array of log event tables. Each event table must contain the keys message and timestamp. The values of both keys must be strings. The value of message is the log message. The value of timestamp should be formatted as milliseconds since the Unix Epoch (milliseconds counted since Jan 1, 1970 00:00:00 UTC)
logGroupName	String	Yes	The name of the log group
logStreamName	String	Yes	The name of the log stream
sequenceToken	String	No	The sequence token. Default: `null`

Example

local now = date();
local ms = format("%06d", now.usec).slice(0,3);
local ts = format("%d%s", time(), ms);

local putLogParams = { "logGroupName": "testLogGroup",
                       "logStreamName": "testLogStream",
                       "logEvents": [{ "message": "log",
                                       "timestamp": ts }] };

logs.action(AWS_CLOUDWATCH_LOGS_ACTION_PUT_LOG_EVENTS, putLogParams, function(response) {
  if (response.statuscode) {
    server.log("successfully put a log in a stream");
  } else {
    server.log("failed to put a log in a stream");
  }
});

Release History

The Electric Imp Dev Center documents the latest version of the library. For past versions, please see the Electric Imp public GitHub repos listed below.

Version	Source Code	Notes
1.0.0	GitHub	Initial release

License

The AWSCloudWatchLogs library is licensed under the MIT License.