Amazon CloudWatch

2017/07/05 - Amazon CloudWatch - 4 new 1 updated api methods

Changes  We are excited to announce the availability of APIs and CloudFormation support for CloudWatch Dashboards. You can use the new dashboard APIs or CloudFormation templates to dynamically build and maintain dashboards to monitor your infrastructure and applications. There are four new dashboard APIs - PutDashboard, GetDashboard, DeleteDashboards, and ListDashboards APIs. PutDashboard is used to create a new dashboard or modify an existing one whereas GetDashboard is the API to get the details of a specific dashboard. ListDashboards and DeleteDashboards are used to get the names or delete multiple dashboards respectively. Getting started with dashboard APIs is similar to any other AWS APIs. The APIs can be accessed through AWS SDK or through CLI tools.

GetDashboard (new) Link ¶

Displays the details of the dashboard that you specify.

To copy an existing dashboard, use GetDashboard , and then use the data returned within DashboardBody as the template for the new dashboard when you call PutDashboard to create the copy.

See also: AWS API Documentation

Request Syntax

client.get_dashboard(
    DashboardName='string'
)
type DashboardName

string

param DashboardName

The name of the dashboard to be described.

rtype

dict

returns

Response Syntax

{
    'DashboardArn': 'string',
    'DashboardBody': 'string',
    'DashboardName': 'string'
}

Response Structure

  • (dict) --

    • DashboardArn (string) --

      The Amazon Resource Name (ARN) of the dashboard.

    • DashboardBody (string) --

      The detailed information about the dashboard, including what widgets are included and their location on the dashboard. For more information about the DashboardBody syntax, see CloudWatch-Dashboard-Body-Structure .

    • DashboardName (string) --

      The name of the dashboard.

ListDashboards (new) Link ¶

Returns a list of the dashboards for your account. If you include DashboardNamePrefix , only those dashboards with names starting with the prefix are listed. Otherwise, all dashboards in your account are listed.

See also: AWS API Documentation

Request Syntax

client.list_dashboards(
    DashboardNamePrefix='string',
    NextToken='string'
)
type DashboardNamePrefix

string

param DashboardNamePrefix

If you specify this parameter, only the dashboards with names starting with the specified string are listed. The maximum length is 255, and valid characters are A-Z, a-z, 0-9, ".", "-", and "_".

type NextToken

string

param NextToken

The token returned by a previous call to indicate that there is more data available.

rtype

dict

returns

Response Syntax

{
    'DashboardEntries': [
        {
            'DashboardName': 'string',
            'DashboardArn': 'string',
            'LastModified': datetime(2015, 1, 1),
            'Size': 123
        },
    ],
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • DashboardEntries (list) --

      The list of matching dashboards.

      • (dict) --

        Represents a specific dashboard.

        • DashboardName (string) --

          The name of the dashboard.

        • DashboardArn (string) --

          The Amazon Resource Name (ARN) of the dashboard.

        • LastModified (datetime) --

          The time stamp of when the dashboard was last modified, either by an API call or through the console. This number is expressed as the number of milliseconds since Jan 1, 1970 00:00:00 UTC.

        • Size (integer) --

          The size of the dashboard, in bytes.

    • NextToken (string) --

      The token that marks the start of the next batch of returned results.

PutDashboard (new) Link ¶

Creates a dashboard if it does not already exist, or updates an existing dashboard. If you update a dashboard, the entire contents are replaced with what you specify here.

You can have up to 500 dashboards per account. All dashboards in your account are global, not region-specific.

To copy an existing dashboard, use GetDashboard , and then use the data returned within DashboardBody as the template for the new dashboard when you call PutDashboard to create the copy.

See also: AWS API Documentation

Request Syntax

client.put_dashboard(
    DashboardName='string',
    DashboardBody='string'
)
type DashboardName

string

param DashboardName

The name of the dashboard. If a dashboard with this name already exists, this call modifies that dashboard, replacing its current contents. Otherwise, a new dashboard is created. The maximum length is 255, and valid characters are A-Z, a-z, 0-9, ".", "-", and "_".

type DashboardBody

string

param DashboardBody

The detailed information about the dashboard in JSON format, including the widgets to include and their location on the dashboard.

For more information about the syntax, see CloudWatch-Dashboard-Body-Structure .

rtype

dict

returns

Response Syntax

{
    'DashboardValidationMessages': [
        {
            'DataPath': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --

    • DashboardValidationMessages (list) --

      If the input for PutDashboard was correct and the dashboard was successfully created or modified, this result is empty.

      If this result includes only warning messages, then the input was valid enough for the dashboard to be created or modified, but some elements of the dashboard may not render.

      If this result includes error messages, the input was not valid and the operation failed.

      • (dict) --

        An error or warning for the operation.

        • DataPath (string) --

          The data path related to the message.

        • Message (string) --

          A message describing the error or warning.

DeleteDashboards (new) Link ¶

Deletes all dashboards that you specify. You may specify up to 100 dashboards to delete. If there is an error during this call, no dashboards are deleted.

See also: AWS API Documentation

Request Syntax

client.delete_dashboards(
    DashboardNames=[
        'string',
    ]
)
type DashboardNames

list

param DashboardNames

The dashboards to be deleted.

  • (string) --

rtype

dict

returns

Response Syntax

{}

Response Structure

  • (dict) --

PutMetricData (updated) Link ¶
Changes (request)
{'MetricData': {'StorageResolution': 'integer'}}

Publishes metric data points to Amazon CloudWatch. CloudWatch associates the data points with the specified metric. If the specified metric does not exist, CloudWatch creates the metric. When CloudWatch creates a metric, it can take up to fifteen minutes for the metric to appear in calls to ListMetrics .

Each PutMetricData request is limited to 40 KB in size for HTTP POST requests.

Although the Value parameter accepts numbers of type Double , CloudWatch rejects values that are either too small or too large. Values must be in the range of 8.515920e-109 to 1.174271e+108 (Base 10) or 2e-360 to 2e360 (Base 2). In addition, special values (for example, NaN, +Infinity, -Infinity) are not supported.

You can use up to 10 dimensions per metric to further clarify what data the metric collects. For more information about specifying dimensions, see Publishing Metrics in the Amazon CloudWatch User Guide .

Data points with time stamps from 24 hours ago or longer can take at least 48 hours to become available for GetMetricStatistics from the time they are submitted.

CloudWatch needs raw data points to calculate percentile statistics. If you publish data using a statistic set instead, you can only retrieve percentile statistics for this data if one of the following conditions is true:

  • The SampleCount value of the statistic set is 1

  • The Min and the Max values of the statistic set are equal

See also: AWS API Documentation

Request Syntax

client.put_metric_data(
    Namespace='string',
    MetricData=[
        {
            'MetricName': 'string',
            'Dimensions': [
                {
                    'Name': 'string',
                    'Value': 'string'
                },
            ],
            'Timestamp': datetime(2015, 1, 1),
            'Value': 123.0,
            'StatisticValues': {
                'SampleCount': 123.0,
                'Sum': 123.0,
                'Minimum': 123.0,
                'Maximum': 123.0
            },
            'Unit': 'Seconds'|'Microseconds'|'Milliseconds'|'Bytes'|'Kilobytes'|'Megabytes'|'Gigabytes'|'Terabytes'|'Bits'|'Kilobits'|'Megabits'|'Gigabits'|'Terabits'|'Percent'|'Count'|'Bytes/Second'|'Kilobytes/Second'|'Megabytes/Second'|'Gigabytes/Second'|'Terabytes/Second'|'Bits/Second'|'Kilobits/Second'|'Megabits/Second'|'Gigabits/Second'|'Terabits/Second'|'Count/Second'|'None',
            'StorageResolution': 123
        },
    ]
)
type Namespace

string

param Namespace

[REQUIRED]

The namespace for the metric data.

You cannot specify a namespace that begins with "AWS/". Namespaces that begin with "AWS/" are reserved for use by Amazon Web Services products.

type MetricData

list

param MetricData

[REQUIRED]

The data for the metric.

  • (dict) --

    Encapsulates the information sent to either create a metric or add new values to be aggregated into an existing metric.

    • MetricName (string) -- [REQUIRED]

      The name of the metric.

    • Dimensions (list) --

      The dimensions associated with the metric.

      • (dict) --

        Expands the identity of a metric.

        • Name (string) -- [REQUIRED]

          The name of the dimension.

        • Value (string) -- [REQUIRED]

          The value representing the dimension measurement.

    • Timestamp (datetime) --

      The time the metric data was received, expressed as the number of milliseconds since Jan 1, 1970 00:00:00 UTC.

    • Value (float) --

      The value for the metric.

      Although the parameter accepts numbers of type Double, CloudWatch rejects values that are either too small or too large. Values must be in the range of 8.515920e-109 to 1.174271e+108 (Base 10) or 2e-360 to 2e360 (Base 2). In addition, special values (for example, NaN, +Infinity, -Infinity) are not supported.

    • StatisticValues (dict) --

      The statistical values for the metric.

      • SampleCount (float) -- [REQUIRED]

        The number of samples used for the statistic set.

      • Sum (float) -- [REQUIRED]

        The sum of values for the sample set.

      • Minimum (float) -- [REQUIRED]

        The minimum value of the sample set.

      • Maximum (float) -- [REQUIRED]

        The maximum value of the sample set.

    • Unit (string) --

      The unit of the metric.

    • StorageResolution (integer) --

returns

None