AWS SDK CloudWatch Examples: Custom Metrics, Alarms and Logs Insights (Python, PHP, Node.js)

By Ravindra Bagale, trainer · LinkedIn · Last updated: 24 October 2026

1. The big picture: the car dashboard

Why do we need this?

Your car shows speed and fuel all the time, and a red light flashes when oil is low. Metrics are the gauges, alarms are the warning lights, logs are the trip diary you read after something went wrong.

What is it?

A metric is a Namespace + MetricName + Dimensions. PutMetricData writes points; GetMetricData reads them. PutMetricAlarm watches a statistic. Logs live in log groups and streams.

How to do it (step by step)

2. Publish custom metrics

Why do we need this?

Mateo wants to see how many orders arrive late, by city, every minute.

What is it?

Use your own namespace, a Unit, and Dimensions to split. Keep dimension values low-cardinality (city, not order id).

How to do it (step by step)

1. Python.

import boto3
cw = boto3.client("cloudwatch", region_name="eu-south-2")
cw.put_metric_data(Namespace="FoodApp", MetricData=[
    {"MetricName": "LateOrders", "Dimensions": [{"Name": "City", "Value": "Barcelona"}], "Value": 4, "Unit": "Count"},
    {"MetricName": "DeliveryMinutes", "Dimensions": [{"Name": "City", "Value": "Barcelona"}], "Values": [28, 31, 45], "Unit": "None"}])
print("sent")

Expected output:

sent

2. Node.js.

import { CloudWatchClient, PutMetricDataCommand } from "@aws-sdk/client-cloudwatch";
const cw = new CloudWatchClient({ region: "ap-south-1" });
await cw.send(new PutMetricDataCommand({ Namespace: "FoodApp", MetricData: [
  { MetricName: "LateOrders", Dimensions: [{ Name: "City", Value: "Bengaluru" }], Value: 9, Unit: "Count" }] }));
console.log("sent");

Expected output:

sent

3. PHP.

<?php
require "vendor/autoload.php";
$cw = new Aws\CloudWatch\CloudWatchClient(["region" => "eu-west-2"]);
$cw->putMetricData(["Namespace" => "FoodApp", "MetricData" => [[
  "MetricName" => "LateOrders", "Dimensions" => [["Name" => "City", "Value" => "London"]],
  "Value" => 2, "Unit" => "Count"]]]);
echo "sent", PHP_EOL;

Expected output:

sent

4. Verify: list the metric.

aws cloudwatch list-metrics --namespace FoodApp --region ap-south-1 --query "Metrics[].Dimensions[0].Value" --output text

Expected output:

Bengaluru

3. Read statistics

Why do we need this?

Ishaan builds a small report: late orders per 5 minutes for the last hour.

What is it?

GetMetricData takes MetricDataQueries with a Stat and Period and returns Timestamps and Values arrays.

How to do it (step by step)

1. Python.

from datetime import datetime, timedelta, timezone
now = datetime.now(timezone.utc)
r = cw.get_metric_data(StartTime=now - timedelta(hours=1), EndTime=now, MetricDataQueries=[{
    "Id": "late", "MetricStat": {"Stat": "Sum", "Period": 300, "Metric": {
        "Namespace": "FoodApp", "MetricName": "LateOrders",
        "Dimensions": [{"Name": "City", "Value": "Barcelona"}]}}}])
print(sum(r["MetricDataResults"][0]["Values"]))

Expected output:

4.0

2. Node.js.

import { GetMetricDataCommand } from "@aws-sdk/client-cloudwatch";
const end = new Date(), start = new Date(end - 3600e3);
const r = await cw.send(new GetMetricDataCommand({ StartTime: start, EndTime: end, MetricDataQueries: [{
  Id: "late", MetricStat: { Stat: "Sum", Period: 300, Metric: { Namespace: "FoodApp", MetricName: "LateOrders",
  Dimensions: [{ Name: "City", Value: "Bengaluru" }] } } }] }));
console.log(r.MetricDataResults[0].Values);

Expected output:

[ 9 ]

3. PHP: math across metrics.

<?php
$r = $cw->getMetricData(["StartTime" => strtotime("-1 hour"), "EndTime" => time(), "MetricDataQueries" => [
  ["Id" => "l", "ReturnData" => false, "MetricStat" => ["Stat" => "Sum", "Period" => 3600,
    "Metric" => ["Namespace" => "FoodApp", "MetricName" => "LateOrders", "Dimensions" => [["Name" => "City", "Value" => "London"]]]]],
  ["Id" => "pct", "Expression" => "l * 100 / 50", "Label" => "late % of 50 orders"]]]);
echo $r["MetricDataResults"][0]["Values"][0], "%", PHP_EOL;

Expected output:

4%

4. Verify with the CLI.

aws cloudwatch get-metric-statistics --namespace FoodApp --metric-name LateOrders --dimensions Name=City,Value=Bengaluru --statistics Sum --period 3600 --start-time $(date -u -d "-1 hour" +%FT%TZ) --end-time $(date -u +%FT%TZ) --query "Datapoints[0].Sum"

Expected output:

9.0

4. Create an alarm

Why do we need this?

If more than 20 orders are late in 5 minutes in Bengaluru, the on-call team must get an email.

What is it?

PutMetricAlarm sets threshold, period, evaluation periods and AlarmActions (an SNS topic). States: OK, ALARM, INSUFFICIENT_DATA.

How to do it (step by step)

1. Python.

cw.put_metric_alarm(AlarmName="late-orders-blr", Namespace="FoodApp", MetricName="LateOrders",
    Dimensions=[{"Name": "City", "Value": "Bengaluru"}], Statistic="Sum", Period=300,
    EvaluationPeriods=1, Threshold=20, ComparisonOperator="GreaterThanThreshold",
    TreatMissingData="notBreaching",
    AlarmActions=["arn:aws:sns:ap-south-1:123456789012:oncall"])
print("alarm ok")

Expected output:

alarm ok

2. Node.js: force the state to test the email.

import { SetAlarmStateCommand } from "@aws-sdk/client-cloudwatch";
await cw.send(new SetAlarmStateCommand({ AlarmName: "late-orders-blr", StateValue: "ALARM", StateReason: "test" }));
console.log("forced");

Expected output:

forced  (on-call gets an email)

3. PHP: read alarm state.

<?php
$cw = new Aws\CloudWatch\CloudWatchClient(["region" => "ap-south-1"]);
$a = $cw->describeAlarms(["AlarmNames" => ["late-orders-blr"]])["MetricAlarms"][0];
echo $a["StateValue"], " ", $a["Threshold"], PHP_EOL;

Expected output:

ALARM 20

4. Verify: alarm history.

aws cloudwatch describe-alarm-history --alarm-name late-orders-blr --history-item-type StateUpdate --max-items 1 --query "AlarmHistoryItems[0].HistorySummary" --output text

Expected output:

Alarm updated from OK to ALARM

5. Logs and Logs Insights

Why do we need this?

A rider in Paris says order PA-311 never arrived; Mateo searches the logs.

What is it?

Create a group and stream, PutLogEvents with millisecond timestamps, FilterLogEvents for simple search, StartQuery/GetQueryResults for Logs Insights.

How to do it (step by step)

1. Python: write JSON log lines.

import json, time
logs = boto3.client("logs", region_name="eu-west-3")
logs.create_log_group(logGroupName="/foodapp/orders")
logs.create_log_stream(logGroupName="/foodapp/orders", logStreamName="api-1")
logs.put_log_events(logGroupName="/foodapp/orders", logStreamName="api-1", logEvents=[
    {"timestamp": int(time.time() * 1000), "message": json.dumps({"order": "PA-311", "status": "picked", "total": "€23.40"})}])
print("logged")

Expected output:

logged

2. Node.js: filter events.

import { CloudWatchLogsClient, FilterLogEventsCommand } from "@aws-sdk/client-cloudwatch-logs";
const logs = new CloudWatchLogsClient({ region: "eu-west-3" });
const r = await logs.send(new FilterLogEventsCommand({ logGroupName: "/foodapp/orders", filterPattern: '{ $.order = "PA-311" }' }));
for (const e of r.events) console.log(e.message);

Expected output:

{"order": "PA-311", "status": "picked", "total": "€23.40"}

3. PHP: Logs Insights query.

<?php
$logs = new Aws\CloudWatchLogs\CloudWatchLogsClient(["region" => "eu-west-3"]);
$q = $logs->startQuery(["logGroupName" => "/foodapp/orders", "startTime" => time() - 3600, "endTime" => time(),
  "queryString" => "stats count(*) by status"])["queryId"];
do { sleep(1); $r = $logs->getQueryResults(["queryId" => $q]); } while ($r["status"] === "Running");
foreach ($r["results"] as $row) echo $row[0]["value"], "=", $row[1]["value"], PHP_EOL;

Expected output:

picked=1

4. Verify: tail the group.

aws logs tail /foodapp/orders --since 10m --region eu-west-3 | grep -c PA-311

Expected output:

1

6. The same call in Java, Go, .NET and the CLI

Why do we need this?

Teams often mix languages. Once you know the call in Python, PHP and Node.js, the other SDKs are the same API with different syntax.

What is it?

All of them call the PutMetricData API. Use the CLI line to test it quickly from a terminal.

How to do it (step by step)

7. Clean up so nothing keeps costing

Why do we need this?

Lab resources left running cost money and can be a security risk.

What is it?

Delete in reverse order: children first, then parents.

How to do it (step by step)

1. Delete the alarm and log group (metrics expire by themselves).

aws cloudwatch delete-alarms --alarm-names late-orders-blr --region ap-south-1
aws logs delete-log-group --log-group-name /foodapp/orders --region eu-west-3

Expected output:

(no output means success)

8. Interview questions and answers

Revision, comparison and interview cards

Revise this lesson in a few minutes. Save the cards on your phone or download them as PNG files. The QR code on each card opens this lesson.

More cards: Ravi Sir's Cards.