Import Amazon CloudWatch Logs and Metrics

CloudWatch Logs

Amazon CloudWatch is a monitoring and logging service for the AWS ecosystem that provides visibility into your cloud resources and applications. This solution enables you to stream CloudWatch logs to Scalyr in real time by creating AWS Lambda Functions using CloudFormation.


1. An application, service, or resource that is currently sending logs to CloudWatch.


1. Use the CloudFormation template to launch stack ->

2. Change the region on the upper right corner of the console if required. CloudFormation must be used in the same region as CloudWatch's log group, so it’s important to ensure that you are logged into the desired region on AWS.

3. Fill in the appropriate parameters for each field:

Field Default Value
AutoSubscribeLogGroups false Automatically subscribe the logGroups defined in LogGroupOptions to the CloudWatch Streamer Lambda function
BaseUrl Base URL of the Scalyr API
Debug false Enable debug logging of each request
LogGroupOptions {} Valid JSON string to customize log delivery
WriteLogsKey Use this or WriteLogsKeyEncrypted. The Scalyr API key that allows write access to Scalyr logs
WriteLogsKeyEncrypted Use this or WriteLogsKey. The encrypted Scalyr API key that allows write access to Scalyr logs

You must set either the WriteLogsKey or WriteLogsKeyEncrypted parameter using your Scalyr logs API key that has write privileges to Scalyr logs.

You can encrypt your Scalyr WriteLogsKey with KMS using aws-cli:

  ~$ aws kms encrypt \
      --key-id <kms_key_id> \
      --plaintext <scalyr_api_key> \
      --output text \
      --query CiphertextBlob \
      --region <cloudwatch_log_group_region>

Simply use the output for the WriteLogsKeyEncrypted parameter.

4. That’s all! You won’t see anything in the Scalyr dashboard until your CloudWatch logGroups have been configured to stream logs to the CloudWatch Streamer Lambda function.

LogGroupOptions Configurations

Scalyr log delivery options are customized by providing a JSON object as a string to the LogGroupOptions parameter. For each logGroup that you want to stream to Scalyr, you'll have to create a Subscription Filter. You can do this through the aws-cli, aws console, or Scalyr CloudWatch Logs Importer.

To enable Scalyr CloudWatch Logs Importer, you'll set AutoSubscribeLogGroups to true and then provide a JSON string to the LogGroupOptions parameter specifying which logGroups to subscribe to. You can also provide a valid filterPattern and filterName as described in the CloudWatch documentation.

      "/aws/lambda/myfunc_[1-9]": {
            "parser": "my_func_parser"
      "/aws/lambda/other_func_[1-9]": {
            "parser": "other_func_parser",
            "filterName" "error_filter",
            "filterPattern": "ERROR"

LogGroupOptions properties and default values:

Property Default Description
serverHost cloudwatch-{account_id} Specifies the server name
logfile logGroup name from CloudWatch Specifies the log file name
prefix_timestamp false Adds the aws system timestamp to the begining of the line
parser cloudWatchLogs See the Scalyr Documentation
filterName cloudWatchLogs The name of the AWS Subscription Filter
filterPattern "" See the AWS Documentation

Options described in the Scalyr Upload Logs API allow you to define server and log attributes, which are then added to your data as server-level fields. Additionally you can define server-level fields via the attributes property. The example below creates "tier" and "department" fields:

  "log/dev/.*": {
    "attributes": {
      "tier": "dev",
      "department": "mydept"

1. Any omitted properties will use the defaults.

2. Any existing logGroup matching the supplied regex will be subscribed to the CloudWatch Streamer Lambda function as part of the CloudFormation stack deployment.

CloudWatch Metrics

This solution uses AWS's "Assume Role" functionality for authentication. For the documentation of the older access key authentication click here.

This Solution describes how to import metrics from Amazon CloudWatch for use in Scalyr, including a sample alert which triggers when your AWS usage fees grow faster than expected. Scalyr can continuously import CloudWatch metrics, for use in dashboards, alerts, and graphs.


1. AWS provides a feature called IAM (Identity and Access Management), which gives you fine-grained control over access to resources. You should create an IAM role which can only be used to read your CloudWatch metrics. For instructions, see the section Create IAM Role.


Scalyr uses "monitors" to fetch data from other services, including CloudWatch. These steps will guide you through creating a monitor to fetch your CloudWatch metrics.

1. From the navigation bar, click Dashboards, and select Monitors.

2. Click Edit Monitors to open the monitors configuration file.

3. Find the monitors section of the configuration file. If you have never edited this file before, the monitors section will look like this:

  monitors: [
    // {
    //   type:        \"http\",
    //   url:         \"\"
    // },
    // {
    //   type:        \"http\",
    //   url:         \"\"
    // }

4. Add a stanza for your CloudWatch data. If you use multiple AWS regions, add one stanza for each region. For example:


  monitors: [
      type: "cloudwatch",
      region: "us-east-1",
      roleToAssume: "XXX",
      executionIntervalMinutes: 2,
      period: 1,
      metrics: [
        {namespace: "AWS/Billing", metric: "EstimatedCharges", dimensions: {Currency: "USD"}, statistics: "Maximum"},

        {namespace: "AWS/EC2", metric: "CPUUtilization", dimensions: {InstanceId: "i-20e126ce"}, statistics: "Minimum, Maximum"},
        {namespace: "AWS/EC2", metric: "StatusCheckFailed", dimensions: {InstanceId: "i-20e126ce"}},
        {namespace: "AWS/EC2", metric: "StatusCheckFailed_Instance", dimensions: {InstanceId: "i-20e126ce"}},
        {namespace: "AWS/EC2", metric: "StatusCheckFailed_System", dimensions: {InstanceId: "i-20e126ce"}}
      type: "cloudwatch",
      region: "us-west-1",
      roleToAssume: "XXX",
      executionIntervalMinutes: 2,
      period: 1,
      metrics: [
        {namespace: "AWS/EC2", metric: "CPUUtilization", dimensions: {InstanceId: "i-35a646bb"}, statistics: "Minimum, Maximum"},
        {namespace: "AWS/EC2", metric: "StatusCheckFailed", dimensions: {InstanceId: "i-35a646bb"}},
        {namespace: "AWS/EC2", metric: "StatusCheckFailed_Instance", dimensions: {InstanceId: "i-35a646bb"}},
        {namespace: "AWS/EC2", metric: "StatusCheckFailed_System", dimensions: {InstanceId: "i-35a646bb"}}


Fill in the appropriate values for each field:

Field Value
type Always cloudwatch
region The AWS region in which your resources are located, e.g. us-east-1
roleToAssume The ARN of the IAM role you created.
executionIntervalMinutes How often to retrieve data from CloudWatch. Can range from 1 to 5. See API Fees.
period Time resolution of the retrieved data, in minutes. Can range from 1 to 5. You can usually omit this field; the default is 1 minute.
metrics Lists each CloudWatch metric to import. For each metric, specify the namespace, metric name, and dimensions under which the metric is listed in CloudWatch. You can also specify which statistics to import — any or all of "Average", "Sum", "Minimum", "Maximum", or "SampleCount". Finally, you can specify a period here, to customize the time resolution on a metric-by-metric basis.
logAttributes Optional: a set of fields and values to be added to each event recorded by this monitor. For example, specify logAttributes: { tier: 'frontend' } to indicate that this measurement is from a frontend server. You may use any field names you like. (Note that #variable# substitution is not supported in these fields.)

Always use an IAM role with limited permissions. If you haven't already done so, follow the Create IAM Role instructions to create a special role which only has access to your database logs.

See Further Reading for references to sample configuration for importing various metrics from CloudWatch.

5. Click Update File to save your changes. Scalyr will begin fetching new log data at the specified interval.

6. Wait a few minutes, for the initial batch of metrics to be retrieved.

7. In the top navigation bar, click Overview. In the list of servers, you should see an entry for each AWS region from which you are importing metrics. For instance, if you are importing metrics from us-east-1, you should see a listing for "cloudwatch-us-east-1".

Note that AWS only reports the "EstimatedCharges" billing metric occasionally, so if this is the only metric you've listed, you may have to wait for it to appear. It is typically reported every four hours, but we have observed gaps of as much as a day.

Graphing CloudWatch metrics

To generate a graph of a CloudWatch metric, go to the Overview page and click on the link to the "cloudwatch" log. Switch to the Facets tab. Find the "metric" field. If you are importing more than 10 metrics, click the (see all values) link below the listed values.

Next, click on the name of the specific metric you would like to graph. Find the list of values, and click the "graph" link. This should display a graph of that metric.

Note that Scalyr does not import historical data, so when you set up your CloudWatch monitor, at first the graph will only show a few minutes' data.

API Fees

Amazon charges a fee of $0.01 per 1000 Get requests to the CloudWatch API. When Scalyr retrieves metrics from CloudWatch on your behalf, this fee will accumulate on your AWS bill (not your Scalyr bill). We recommend that you set executionIntervalMinutes to 2 in your CloudWatch monitor configuration, meaning that Scalyr will perform a Get request for each metric every 2 minutes. This will result in an AWS fee of $0.216 per metric every 30 days, or around $11/month if you import 50 metrics.

You can save money by increasing executionIntervalMinutes to 5; the only downside is a slight delay in your CloudWatch data appearing in Scalyr. Intervals greater than 5 minutes are not currently supported. If you have any concerns about CloudWatch API fees, please let us know.


If your metrics don't appear, make sure you've waited at least 2 minutes since saving your changes to the Monitors configuration (i.e. since clicking Update File), or longer if you specified a longer period in executionIntervalMinutes. Then return to the Scalyr Overview page and refresh your browser.

If the metrics still don't appear, you may have a configuration error which is preventing Scalyr from retrieving your metrics. To check for error messages, in Scalyr's top navigation bar, click Search. In the Expression box, type tag='cloudwatchMonitor' and click the Search button. Click End to jump to the most recent log messages, and click on an individual message to see details for that message. If the details page includes an "errorMessage" field, then CloudWatch returned an error when Scalyr attempted to retrieve your metrics. Some common error messages:

Cause errorMessage
Incorrect Role configuration Status Code: 403, AWS Service: CloudWatch, AWS Request ID: xxx-xxx-xxx-xxx, AWS Error Code: AccessDenied, AWS Error Message: User: arn:aws:iam::nnnnnnnnnnnn:user/cloudwatch-reader is not authorized to perform: [etc.] on resource: [etc.]
Incorrect Role configuration or incorrect Role ARN Status Code: 403, AWS Service: AWSSecurityTokenService, AWS Request ID: xxx-xxx-xxx-xxx, AWS Error Code: AccessDenied, AWS Error Message: User: arn:aws:iam::913057016266:user/user is not authorized to perform: sts:AssumeRole on resource: arn:aws:iam::nnnnnnnnnnnn:role/RoleName

If you don't see any error messages, you may simply have entered an incorrect value in one of the fields in the Monitors configuration, such as "namespace" or "metric". CloudWatch will not report an error for an incorrect metric namespace, name, or dimension. Double-check your monitor configuration.

Further Reading

The Search overview page describes the tools you can use to search through log data, including CloudWatch metrics. Query Language lists the operators you can use to select specific metrics and values. You can also use metrics in Dashboards and Alerts.

To use CloudWatch to monitor your Amazon AWS usage fees, see Alert on AWS Billing Spikes.

Appendix: Create IAM Role

You can use Amazon IAM to create a role which can only be used to read your CloudWatch metrics. This allows you to grant Scalyr the ability to import the metrics, without opening up any other access to your AWS resources. Create the IAM role as follows:

  1. Log into the Amazon AWS console. From the Services menu, choose "IAM".
  2. Go to the Roles list.
  3. Click "Create role".
  4. Under "Select type of trusted entity" select "Another AWS account".
  5. For "Account ID" enter "913057016266".
  6. Under options check "Require external ID" and enter the value "(Log in to view External Id.)".
  7. Click "Next: Permissions", then "Create policy", this will open in a new tab.
  8. Select the following values:
      Effect: Allow
      Service: CloudWatch
      Actions: check GetMetricStatistics and ListMetrics
  9. Click "Review policy", name it, then click "Create policy".
  10. Return to the create role tab and select your newly created policy and hit "Next".
  11. Skip past adding tags and give your role a name, then hit "Create role".