search

awsdocs / aws-doc-sdk-examples

Welcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.
Apache License 2.0
9.52k stars 5.62k forks source link

[EPIC] Amazon CloudWatch MVP #4218

Closed rlhagerm closed 9 months ago

rlhagerm commented 1 year ago

CloudWatch documentation references:

To enable billing metrics and statistics for this example, make sure billing alerts are enabled for your account.

Reference implementation of scenario and actions in .NET: /dotnetv3/CloudWatch and in PR 4293

Service actions

Service actions can either be pulled out as individual functions or can be incorporated into the scenario, but each service action must be included as an excerpt in the SOS output.

ListMetrics GetMetricStatistics PutDashboard PutMetricData GetMetricData PutMetricAlarm DescribeAlarms DescribeAlarmsForMetric DescribeAlarmHistory DeleteAlarms PutAnomalyDetector GetMetricWidgetImage DescribeAnomalyDetectors DeleteAnomalyDetector DeleteDashboards

Hello Service

The Hello Service example should demonstrate how to set up the client and make an example call using the SDK.

Hello CloudWatch

Initialize the client and call ListMetrics for at least one namespace, such as “AWS/Billing”. Display the first 5 available metrics.

General info for Hello Service example snippets: This section of the MVP should be a streamlined, simple example with enough detail to be as close to “copy/paste” runnable as possible. This example may include namespaces and other setup in order to focus on getting the user up and running with the new service.

Sample output:

Hello Amazon CloudWatch! Following are some metrics available in the AWS/Billing namespace:

        Metric: EstimatedCharges
        Namespace: AWS/Billing
        Dimensions: ServiceName:AWSSystemsManager, Currency:USD

        Metric: EstimatedCharges
        Namespace: AWS/Billing
        Dimensions: ServiceName:AWSGlue, Currency:USD

Scenario

A scenario runs at a command prompt and prints output to the user on the result of each service action. A scenario can run in one of two ways: straight through printing out progress as it goes, or as an interactive question/answer script.

Working with metrics, dashboards, and alarms

  1. List at least 5 available unique namespaces from CloudWatch. Have the user select a namespace. (ListMetrics)
    1. There is no action for just listing namespaces, but you can list some known namespaces, or alternatively you can list the metrics and then get distinct namespaces from that list.
  2. List available metrics within the selected Namespace. Have the user select a metric. Example: Billing, or Usage metrics for one of the CloudWatch APIs. You will want to test several namespaces because they may act differently. (ListMetrics)
    1. Some metrics may have the same name, so when listing metrics, you should also list their dimensions. See “Usage” namespace as an example.
    2. Use pagination if available.
    3. You may limit to the 10 most recent metrics, in case the namespace has many metrics to show.
  3. Get statistics for the selected metric over the last day. (GetMetricStatistics)
    1. Different metrics support different statistics. Present the user with a list of stats to choose from, such as SampleCount, Average, Sum, Minimum, and Maximum.
    2. Present the stats with timestamps and values, sorted by time.
  4. Let the user get Estimated Billing statistics for their account for the last week. (GetMetricStatistics)
    1. See .NET example for an example query with Period and Dimension definitions.
    2. Present the estimated billing by day, in chronological order.
  5. Create a new dashboard and add 2 metrics to it (Example: SDK Usage and Estimated Billing) (PutDashboard)
    1. See .NET example for an example of metric definitions. You can also create this dashboard in the AWS Console, and use “View Source” to get a JSON definition of a dashboard.
    2. Ensure your cleanup operation gives the user the option to cleanup this dashboard.
    3. Best practice according to the docs is to include a text widget indicating this dashboard was created in code.
  6. List dashboards. (ListDashboards)
    1. Use pagination if available.
  7. Create a new custom metric by adding data for it. (PutMetricData)
    1. Example: create a metric and add 10 random values less than 100 to the metric. Adding data creates the metric.
    2. There is no “cleanup” for a metric, it just expires after a period of having no new data.
  8. Add the custom metric to the dashboard. (PutDashboard)
    1. Use the PutDashboard to update the dashboard. All data will be overwritten, so you should also include your original metric definitions.
  9. Create an alarm for the custom metric, optionally with some actions enabled, such as sending an email. (PutMetricAlarm)
    1. You can create an alarm with a threshhold of 100, so you can trigger the alarm in a later step.
    2. Ensure your cleanup operation gives the user the option to cleanup this alarm.
    3. If sending an email, you can use the default topic like "Default_CloudWatch_Alarms_Topic" but you will need to subscribe to this topic. You can do this in code or have the user or configuration provide the topic name.
  10. Describe current alarms. (DescribeAlarms)
    1. Use pagination if available.
    2. You may limit the list to the most recent 10 updated alarms, in case the account has many alarms to show.
    3. Display the current state and thresholds of each alarm.
  11. Get metric data for the custom metric. (GetMetricData)
    1. See .NET for an example query. You should see some data returned for the custom metric. Data pushed in the last minute may not show up, so you may need to delay this call until data exists.
  12. Push data into the custom metric to trigger the alarm. (PutMetricData)
    1. You will need several (I used 3) consecutive over-threshold data points to trigger the alarm.
  13. Check the alarm state using the action DescribeAlarmsForMetric until the new alarm is in an Alarm state. (DescribeAlarmsForMetric)
  14. Get alarm history for the new alarm. (DescribeAlarmHistory)
    1. Use pagination if available.
    2. Display the state and timestamp for the history items.
  15. Add an anomaly detector for the custom metric. (PutAnomalyDetector)
    1. Ensure your cleanup operation gives the user the option to cleanup this anomaly detector.
    2. You may use the Console to explore some appropriate anomaly settings, or use the .NET for an example.
  16. Describe current anomaly detectors. (DescribeAnomalyDetectors)
    1. Use pagination if available.
  17. Get a metric image for the custom metric. (GetMetricWidgetImage)
    1. The data returned will be a Base64 encoded image, you can display or save as a file and open.
    2. You may use the console to set up graphic parameters in a dashboard, and/or see the .NET MVP for an example.
  18. Cleanup
    1. Delete the anomaly detector. (DeleteAnomalyDetector)
    2. Delete the alarm. (DeleteAlarms)
    3. Delete the new dashboard. (DeleteDashboards)

See the attached sample output from the .NET MVP.

Metadata

In cloudwatch_metadata.yaml:

cloudwatch_Hello cloudwatch_DeleteAlarms cloudwatch_DeleteAnomalyDetector cloudwatch_DeleteDashboards cloudwatch_DescribeAlarmHistory cloudwatch_DescribeAlarms cloudwatch_DescribeAlarmsForMetric cloudwatch_DescribeAnomalyDetectors cloudwatch_GetMetricData cloudwatch_GetMetricStatistics cloudwatch_GetMetricImage cloudwatch_ListDashboards cloudwatch_ListMetrics cloudwatch_PutAnomalyDetector cloudwatch_PutDashboard cloudwatch_PutMetricAlarm cloudwatch_PutMetricData cloudwatch_GetStartedMetricsDashboardsAlarms

SDKs

Acceptance criteria

Sample output from .NET

--------------------------------------------------------------------------------
Welcome to the Amazon CloudWatch example scenario.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
1. Select a CloudWatch Namespace from a list of Namespaces.
        1. AWS/Billing
        2. AWS/Redshift
        4. AWS/RDS
        5. AWS/DynamoDB
        6. AWS/Usage
        7. AWS/TrustedAdvisor
        8. AWS/S3
        9. AWS/States
        10. example-namespace
        11. AWS/Logs
        12. AWS/Events
        13. AWS/SecretsManager
        14. AWS/SNS
Select a namespace by entering a number from the preceding list:
9
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
2. Select a CloudWatch metric from a namespace.
        1. example-custom-metric
Select a metric by entering a number from the preceding list:
1
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
4. Get CloudWatch metric statistics for the last day.
        1. SampleCount
        2. Average
        3. Sum
        5. Minimum
        6. Maximum
Select a metric statistic by entering a number from the preceding list:
5
        1. Timestamp 1/9/2023 2:21:00 PM Maximum: 13
        2. Timestamp 1/9/2023 2:22:00 PM Maximum: 6
        3. Timestamp 1/9/2023 2:23:00 PM Maximum: 120
        5. Timestamp 1/9/2023 2:24:00 PM Maximum: 120
        6. Timestamp 1/9/2023 2:25:00 PM Maximum: 120
        7. Timestamp 1/9/2023 2:26:00 PM Maximum: 52
        8. Timestamp 1/9/2023 2:27:00 PM Maximum: 120
        9. Timestamp 1/9/2023 2:28:00 PM Maximum: 120
        10. Timestamp 1/9/2023 2:29:00 PM Maximum: 120
        11. Timestamp 1/9/2023 2:30:00 PM Maximum: 120
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
5. Get CloudWatch estimated billing for the last week.
        1. Timestamp 1/3/2023 11:46:00 AM : 0.66
        2. Timestamp 1/4/2023 11:46:00 AM : 0.76
        3. Timestamp 1/5/2023 11:46:00 AM : 0.78
        4. Timestamp 1/6/2023 11:46:00 AM : 1.19
        6. Timestamp 1/7/2023 11:46:00 AM : 1.47
        7. Timestamp 1/8/2023 11:46:00 AM : 1.76
        8. Timestamp 1/9/2023 11:46:00 AM : 2.02
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
5. Create a new CloudWatch dashboard with metrics.

        Dashboard example-new-dashboard was created.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
7. List the CloudWatch dashboards in the current account.
        1. ApplicationInsights-ApplicationInsights-testapp1
        2. customWidgetDebugger-js-us-east-1
        3. example-new-dashboard
        4. test_dashboard_1
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
8. Create and add data for a new custom metric.
        Added metric values for for metric example-custom-metric:
        72,98,31,63,46,70,56,84,73,39
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
9. Add the new custom metric to the dashboard.

        Dashboard example-new-dashboard updated with metric example-custom-metric.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
10. Create a CloudWatch alarm for the new metric.
        Add an email action for topic Default_CloudWatch_Alarms_Topic to alarm example-metric-alarm? (y/n)
y
        Alarm example-metric-alarm added for metric example-custom-metric.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
11. Describe CloudWatch alarms in the current account.
        1. example-metric-alarm
        State: INSUFFICIENT_DATA for example-custom-metric GreaterThanOrEqualToThreshold 100
        2. ApplicationInsights/ApplicationInsights-testapp1/AWS/SNS/NumberOfNotificationsFailed/Default_CloudWatch_Alarms_Topic/
        State: OK for NumberOfNotificationsFailed GreaterThanOrEqualToThreshold 5
        3. ApplicationInsights/ApplicationInsights-testapp1/AWS/SNS/NumberOfNotificationsFailed/ExampleTopic/
        State: INSUFFICIENT_DATA for NumberOfNotificationsFailed GreaterThanOrEqualToThreshold 5
        4. ApplicationInsights/ApplicationInsights-testapp1/AWS/DynamoDB/ConsumedWriteCapacityUnits/Thread/
        State: OK for ConsumedWriteCapacityUnits GreaterThanOrEqualToThreshold 1
        5. ApplicationInsights/ApplicationInsights-testapp1/AWS/DynamoDB/ConsumedReadCapacityUnits/Forum/
        State: OK for ConsumedReadCapacityUnits GreaterThanOrEqualToThreshold 1
        6. ApplicationInsights/ApplicationInsights-testapp1/AWS/DynamoDB/ConsumedWriteCapacityUnits/Forum/
        State: OK for ConsumedWriteCapacityUnits GreaterThanOrEqualToThreshold 1
        7. ApplicationInsights/ApplicationInsights-testapp1/AWS/DynamoDB/ConsumedReadCapacityUnits/Thread/
        State: OK for ConsumedReadCapacityUnits GreaterThanOrEqualToThreshold 1
        9. ApplicationInsights/ApplicationInsights-testapp1/AWS/DynamoDB/SystemErrors/doc-example-work-item-tracker/
        State: OK for  GreaterThanOrEqualToThreshold 1
        10. ApplicationInsights/ApplicationInsights-testapp1/AWS/DynamoDB/ConsumedReadCapacityUnits/doc-example-work-item-tracker/
        State: OK for ConsumedReadCapacityUnits GreaterThanOrEqualToThreshold 1
        11. ApplicationInsights/ApplicationInsights-testapp1/AWS/DynamoDB/ConsumedWriteCapacityUnits/Reply/
        State: OK for ConsumedWriteCapacityUnits GreaterThanOrEqualToThreshold 1
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
12. Get current data for new custom metric.
        Timestamp 1/10/2023 11:40:00 AM Value: 39
        Timestamp 1/10/2023 11:39:00 AM Value: 73
        Timestamp 1/10/2023 11:38:00 AM Value: 84
        Timestamp 1/10/2023 11:37:00 AM Value: 56
        Timestamp 1/10/2023 11:36:00 AM Value: 70
        Timestamp 1/10/2023 11:35:00 AM Value: 46
        Timestamp 1/10/2023 11:34:00 AM Value: 63
        Timestamp 1/10/2023 11:33:00 AM Value: 31
        Timestamp 1/10/2023 11:32:00 AM Value: 98
        Timestamp 1/10/2023 11:31:00 AM Value: 72
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
13. Add metric data to the custom metric to trigger an alarm.
        Added metric values for for metric example-custom-metric:
        101,101,101
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
14. Checking for an alarm state.
        Alarm state found for example-custom-metric.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
15. Get alarm history.
        1. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 11:46 AM
        2. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 10:43 AM
        3. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 10:39 AM
        4. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 10:34 AM
        5. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 10:06 AM
        6. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 9:36 AM
        7. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 9:22 AM
        8. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 9:16 AM
        9. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 9:05 AM
        10. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/10/2023 8:27 AM
        12. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/9/2023 3:03 PM
        13. Alarm updated from INSUFFICIENT_DATA to ALARM, time 1/9/2023 2:59 PM
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
16. Add an anomaly detector.
        Added anomaly detector for metric example-custom-metric.
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
17. Describe anomaly detectors in the current account.
        1. example-custom-metric, state PENDING_TRAINING
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
18. Get a metric image from CloudWatch.
        Getting Image data for custom metric.
        File saved as MetricImages_638089480262068710.png.
        Press enter to open the image.

--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
19. Clean up resources.
        Delete dashboard example-new-dashboard? (y/n)
y
        Deleting dashboard.
        Delete alarm example-metric-alarm? (y/n)
y
        Cleaning up alarms.
        Delete anomaly detector? (y/n)
y
        Cleaning up anomaly detector.
--------------------------------------------------------------------------------
ford-at-aws commented 1 year ago

I am confused by this part:

Get statistics for the selected metric over the last day. (GetMetricStatistics)
Different metrics support different statistics. Present the user with a list of stats to choose from, such as SampleCount, Average, Sum, Minimum, and Maximum.
Present the stats with timestamps and values, sorted by time.

Specifically, the Present the stats with timestamps and values, sorted by time.

This is the CLI output you copied:

Select a metric statistic by entering a number from the preceding list:
5
        1. Timestamp 1/9/2023 2:21:00 PM Maximum: 13
        2. Timestamp 1/9/2023 2:22:00 PM Maximum: 6
        3. Timestamp 1/9/2023 2:23:00 PM Maximum: 120
        5. Timestamp 1/9/2023 2:24:00 PM Maximum: 120
        6. Timestamp 1/9/2023 2:25:00 PM Maximum: 120
        7. Timestamp 1/9/2023 2:26:00 PM Maximum: 52
        8. Timestamp 1/9/2023 2:27:00 PM Maximum: 120
        9. Timestamp 1/9/2023 2:28:00 PM Maximum: 120
        10. Timestamp 1/9/2023 2:29:00 PM Maximum: 120
        11. Timestamp 1/9/2023 2:30:00 PM Maximum: 120

Assuming the range is 1 day and you set the Period to 1 day, you will just get 1 single data point and sorting is not required. If I'm understanding this correctly, this example is showing a range of 9 minutes with a 1 minute period. If this is true, perhaps it would be clear to inform the user which period you're using.

rlhagerm commented 1 year ago

If you look at the .NET code, the period is not 1 day, the start and end time have a difference of one day. The period is set to 60 seconds. I have limited the list here, but that's why you see a data point for each minute. You are welcome to add more context to the output for the user. I also recommend looking at the .NET code used to generate the output, it will help you see what parameters were used.

brmur commented 9 months ago

Reached minimum quote of SDK languages.