Merge pull request #9106 from kdaily/cloudwatch-cli-docs-v3-v2

add examples for CloudWatch CLI commands
aws · Nov 26, 2024 · c111761 · c111761
2 parents ec14fc2 + c9d26de
commit c111761
Show file tree

Hide file tree

Showing 27 changed files with 576 additions and 0 deletions.
diff --git a/awscli/examples/cloudwatch/delete-anomaly-detector.rst b/awscli/examples/cloudwatch/delete-anomaly-detector.rst
@@ -0,0 +1,12 @@
+**To delete a specified anomaly detection model**
+
+The following ``delete-anomaly-detector`` example deletes an anomaly detector model in the specified account. ::
+
+    aws cloudwatch delete-anomaly-detector \
+        --namespace AWS/Logs \
+        --metric-name IncomingBytes \
+        --stat SampleCount 
+
+This command produces no output.
+
+For more information, see `Deleting an anomaly detection model <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Create_Anomaly_Detection_Alarm.html#Delete_Anomaly_Detection_Model>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/delete-dashboards.rst b/awscli/examples/cloudwatch/delete-dashboards.rst
@@ -0,0 +1,10 @@
+**To delete specified dashboards**
+
+The following ``delete-dashboards`` example deletes two dashboards named ``Dashboard-A`` and ``Dashboard-B`` in the specified account. ::
+
+    aws cloudwatch delete-dashboards \
+        --dashboard-names Dashboard-A Dashboard-B
+
+This command produces no output.
+
+For more information, see `Amazon CloudWatch dashboards <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/delete-insight-rules.rst b/awscli/examples/cloudwatch/delete-insight-rules.rst
@@ -0,0 +1,14 @@
+**To delete specified contributor insights rules**
+
+The following ``delete-insight-rules`` example deletes two contributor insights rules named ``Rule-A`` and ``Rule-B`` in the specified account. ::
+
+    aws cloudwatch delete-insight-rules \
+        --rule-names Rule-A Rule-B 
+
+Output::
+
+    {
+        "Failures": []
+    }
+
+For more information, see `Use Contributor Insights to analyze high-cardinality data <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/delete-metric-stream.rst b/awscli/examples/cloudwatch/delete-metric-stream.rst
@@ -0,0 +1,10 @@
+**To delete a specified metric stream**
+
+The following ``delete-metric-stream`` example deletes the metric stream named ``QuickPartial-gSCKvO`` in the specified account. ::
+
+    aws cloudwatch delete-metric-stream \
+        --name QuickPartial-gSCKvO 
+
+This command produces no output.
+
+For more information, see `Use metric streams <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Metric-Streams.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/describe-anomaly-detectors.rst b/awscli/examples/cloudwatch/describe-anomaly-detectors.rst
@@ -0,0 +1,59 @@
+**To retrieve a list of anomaly detection models**
+
+The following ``describe-anomaly-detectors`` example displays information about anomaly detector models that are associated with the ``AWS/Logs`` namespace in the specified account. ::
+
+    aws cloudwatch describe-anomaly-detectors \
+        --namespace AWS/Logs
+
+Output::
+
+    {
+        "AnomalyDetectors": [
+            {
+                "Namespace": "AWS/Logs",
+                "MetricName": "IncomingBytes",
+                "Dimensions": [],
+                "Stat": "SampleCount",
+                "Configuration": {
+                    "ExcludedTimeRanges": []
+                },
+                "StateValue": "TRAINED",
+                "SingleMetricAnomalyDetector": {
+                    "AccountId": "123456789012",
+                    "Namespace": "AWS/Logs",
+                    "MetricName": "IncomingBytes",
+                    "Dimensions": [],
+                    "Stat": "SampleCount"
+                }
+            },
+            {
+                "Namespace": "AWS/Logs",
+                "MetricName": "IncomingBytes",
+                "Dimensions": [
+                    {
+                        "Name": "LogGroupName",
+                        "Value": "demo"
+                    }
+                ],
+                "Stat": "Average",
+                "Configuration": {
+                    "ExcludedTimeRanges": []
+                },
+                "StateValue": "PENDING_TRAINING",
+                "SingleMetricAnomalyDetector": {
+                    "AccountId": "123456789012",
+                    "Namespace": "AWS/Logs",
+                    "MetricName": "IncomingBytes",
+                    "Dimensions": [
+                        {
+                            "Name": "LogGroupName",
+                            "Value": "demo"
+                        }
+                    ],
+                    "Stat": "Average"
+                }
+            }
+        ]
+    }
+
+For more information, see `Using CloudWatch anomaly detection <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Anomaly_Detection.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/describe-insight-rules.rst b/awscli/examples/cloudwatch/describe-insight-rules.rst
@@ -0,0 +1,28 @@
+**To retrieve a list of Contributor Insights rules**
+
+The following ``describe-insight-rules`` example shows all the Contributor Insight rules in the specified account. ::
+
+    aws cloudwatch describe-insight-rules 
+
+Output::
+
+    {
+        "InsightRules": [
+            {
+                "Name": "Rule-A",
+                "State": "ENABLED",
+                "Schema": "CloudWatchLogRule/1",
+                "Definition": "{\n\t\"AggregateOn\": \"Count\",\n\t\"Contribution\": {\n\t\t\"Filters\": [],\n\t\t\"Keys\": [\n\t\t\t\"$.requestId\"\n\t\t]\n\t},\n\t\"LogFormat\": \"JSON\",\n\t\"Schema\": {\n\t\t\"Name\": \"CloudWatchLogRule\",\n\t\t\"Version\": 1\n\t},\n\t\"LogGroupARNs\": [\n\t\t\"arn:aws:logs:us-east-1:123456789012:log-group:demo\"\n\t]\n}",
+                "ManagedRule": false
+            },
+            {
+                "Name": "Rule-B",
+                "State": "ENABLED",
+                "Schema": "CloudWatchLogRule/1",
+                "Definition": "{\n\t\"AggregateOn\": \"Count\",\n\t\"Contribution\": {\n\t\t\"Filters\": [],\n\t\t\"Keys\": [\n\t\t\t\"$.requestId\"\n\t\t]\n\t},\n\t\"LogFormat\": \"JSON\",\n\t\"Schema\": {\n\t\t\"Name\": \"CloudWatchLogRule\",\n\t\t\"Version\": 1\n\t},\n\t\"LogGroupARNs\": [\n\t\t\"arn:aws:logs:us-east-1:123456789012:log-group:demo-1\"\n\t]\n}",
+                "ManagedRule": false
+            }
+        ]
+    }
+
+For more information, see `Use Contributor Insights to analyze high-cardinality data <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/disable-insight-rules.rst b/awscli/examples/cloudwatch/disable-insight-rules.rst
@@ -0,0 +1,14 @@
+**To disable specified contributor insight rules**
+
+The following ``disable-insight-rules`` example disables two contributor insights rules named ``Rule-A`` and ``Rule-B`` in the specified account. ::
+
+    aws cloudwatch disable-insight-rules \
+        --rule-names Rule-A Rule-B
+
+Output::
+
+    {
+        "Failures": []
+    }
+
+For more information, see `Use Contributor Insights to analyze high-cardinality data <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/enable-insight-rules.rst b/awscli/examples/cloudwatch/enable-insight-rules.rst
@@ -0,0 +1,14 @@
+**To enable specified contributor insight rules**
+
+The following ``enable-insight-rules`` example enables two contributor insights rules named ``Rule-A`` and ``Rule-B`` in the specified account. ::
+
+    aws cloudwatch enable-insight-rules \
+        --rule-names Rule-A Rule-B
+
+Output::
+
+    {
+        "Failures": []
+    }
+
+For more information, see `Use Contributor Insights to analyze high-cardinality data <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/get-dashboard.rst b/awscli/examples/cloudwatch/get-dashboard.rst
@@ -0,0 +1,16 @@
+**To retrieve information about a Dashboard**
+
+The following ``get-dashboard`` example displays information about the dashboard named ``Dashboard-A`` in the specified account. ::
+
+    aws cloudwatch get-dashboard \
+        --dashboard-name Dashboard-A 
+
+Output::
+
+    {
+        "DashboardArn": "arn:aws:cloudwatch::123456789012:dashboard/Dashboard-A",
+        "DashboardBody": "{\"widgets\":[{\"type\":\"metric\",\"x\":0,\"y\":0,\"width\":6,\"height\":6,\"properties\":{\"view\":\"timeSeries\",\"stacked\":false,\"metrics\":[[\"AWS/EC2\",\"NetworkIn\",\"InstanceId\",\"i-0131f062232ade043\"],[\".\",\"NetworkOut\",\".\",\".\"]],\"region\":\"us-east-1\"}}]}",
+        "DashboardName": "Dashboard-A"
+    }
+
+For more information, see `Amazon CloudWatch dashboards <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/get-insight-rule-report.rst b/awscli/examples/cloudwatch/get-insight-rule-report.rst
@@ -0,0 +1,37 @@
+**To retrieve the time series data collected by a Contributor Insights rule**
+
+The following ``get-insight-rule-report`` example returns the time series data collected by a Contributor Insights rule. ::
+
+    aws cloudwatch get-insight-rule-report \
+        --rule-name Rule-A \
+        --start-time 2024-10-13T20:15:00Z \
+        --end-time 2024-10-13T20:30:00Z \
+        --period 300
+
+Output::
+
+    {
+        "KeyLabels": [
+            "PartitionKey"
+        ],
+        "AggregationStatistic": "Sum",
+        "AggregateValue": 0.5,
+        "ApproximateUniqueCount": 1,
+        "Contributors": [
+            {
+                "Keys": [
+                    "RequestID"
+                ],
+                "ApproximateAggregateValue": 0.5,
+                "Datapoints": [
+                    {
+                        "Timestamp": "2024-10-13T21:00:00+00:00",
+                        "ApproximateValue": 0.5
+                    }
+                ]
+            }
+        ],
+        "RuleAttributes": []
+    }
+
+For more information, see `Use Contributor Insights to analyze high-cardinality data <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContributorInsights.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/get-metric-data.rst b/awscli/examples/cloudwatch/get-metric-data.rst
@@ -0,0 +1,106 @@
+**Example 1: To get the Average Total IOPS for the specified EC2 using math expression**
+
+The following ``get-metric-data`` example retrieves CloudWatch metric values for the EC2 instance with InstanceID ``i-abcdef`` using metric math exprssion that combines ``EBSReadOps`` and ``EBSWriteOps`` metrics. ::
+
+    aws cloudwatch get-metric-data \
+        --metric-data-queries file://file.json \
+        --start-time 2024-09-29T22:10:00Z \
+        --end-time 2024-09-29T22:15:00Z
+
+Contents of ``file.json``::
+
+    [
+        {
+            "Id": "m3",
+            "Expression": "(m1+m2)/300",
+            "Label": "Avg Total IOPS"
+        },
+        {
+            "Id": "m1",
+            "MetricStat": {
+                "Metric": {
+                    "Namespace": "AWS/EC2",
+                    "MetricName": "EBSReadOps",
+                    "Dimensions": [
+                        {
+                            "Name": "InstanceId",
+                            "Value": "i-abcdef"
+                        }
+                    ]
+                },
+                "Period": 300,
+                "Stat": "Sum",
+                "Unit": "Count"
+            },
+            "ReturnData": false
+        },
+        {
+            "Id": "m2",
+            "MetricStat": {
+                "Metric": {
+                    "Namespace": "AWS/EC2",
+                    "MetricName": "EBSWriteOps",
+                    "Dimensions": [
+                        {
+                            "Name": "InstanceId",
+                            "Value": "i-abcdef"
+                        }
+                    ]
+                },
+                "Period": 300,
+                "Stat": "Sum",
+                "Unit": "Count"
+            },
+            "ReturnData": false
+        }
+    ]
+
+Output::
+
+    {
+        "MetricDataResults": [
+            {
+                "Id": "m3",
+                "Label": "Avg Total IOPS",
+                "Timestamps": [
+                    "2024-09-29T22:10:00+00:00"
+                ],
+                "Values": [
+                    96.85
+                ],
+                "StatusCode": "Complete"
+            }
+        ],
+        "Messages": []
+    }
+
+**Example 2: To monitor the estimated AWS charges using CloudWatch billing metrics**
+
+The following ``get-metric-data`` example retrieves ``EstimatedCharges`` CloudWatch metric from AWS/Billing namespace. ::
+
+    aws cloudwatch get-metric-data \
+        --metric-data-queries '[{"Id":"m1","MetricStat":{"Metric":{"Namespace":"AWS/Billing","MetricName":"EstimatedCharges","Dimensions":[{"Name":"Currency","Value":"USD"}]},"Period":21600,"Stat":"Maximum"}}]' \
+        --start-time 2024-09-26T12:00:00Z \
+        --end-time 2024-09-26T18:00:00Z \
+        --region us-east-1
+
+Output::
+
+    {
+        "MetricDataResults": [
+            {
+                "Id": "m1",
+                "Label": "EstimatedCharges",
+                "Timestamps": [
+                    "2024-09-26T12:00:00+00:00"
+                ],
+                "Values": [
+                    542.38
+                ],
+                "StatusCode": "Complete"
+            }
+        ],
+        "Messages": []
+    }
+    
+For more information, see `Using math expressions with CloudWatch metrics <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/using-metric-math.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/get-metric-stream.rst b/awscli/examples/cloudwatch/get-metric-stream.rst
@@ -0,0 +1,22 @@
+**To retrieve information about a metric stream**
+
+The following ``get-metric-stream`` example displays information about the metric stream named ``QuickFull-GuaFbs`` in the specified account. ::
+
+    aws cloudwatch get-metric-stream \
+        --name QuickFull-GuaFbs
+
+Output::
+
+    {
+        "Arn": "arn:aws:cloudwatch:us-east-1:123456789012:metric-stream/QuickFull-GuaFbs",
+        "Name": "QuickFull-GuaFbs",
+        "FirehoseArn": "arn:aws:firehose:us-east-1:123456789012:deliverystream/MetricStreams-QuickFull-GuaFbs-WnySbECG",
+        "RoleArn": "arn:aws:iam::123456789012:role/service-role/MetricStreams-FirehosePutRecords-JN10W9B3",
+        "State": "running",
+        "CreationDate": "2024-10-11T18:48:59.187000+00:00",
+        "LastUpdateDate": "2024-10-11T18:48:59.187000+00:00",
+        "OutputFormat": "json",
+        "IncludeLinkedAccountsMetrics": false
+    }
+
+For more information, see `Use metric streams <https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Metric-Streams.html>`__ in the *Amazon CloudWatch User Guide*.
diff --git a/awscli/examples/cloudwatch/get-metric-widget-image.rst b/awscli/examples/cloudwatch/get-metric-widget-image.rst
@@ -0,0 +1,10 @@
+**To retrieve a snapshot graph of CPUUtilization**
+
+The following ``get-metric-widget-image`` example retrieves snapshot graph for the metric ``CPUUtilization`` of the EC2 instance with the ID ``i-abcde`` and saves the retrieved image as a file named "image.png" on your local machine. ::
+
+    aws cloudwatch get-metric-widget-image \
+        --metric-widget '{"metrics":[["AWS/EC2","CPUUtilization","InstanceId","i-abcde"]]}' \
+        --output-format png \
+        --output text | base64 --decode > image.png
+
+This command produces no output.