Busca en todas las páginas de la documentación
The Core section's CloudWatch page publishes one metric and creates one alarm. This page is the on-ramp into everything this deeper section covers: batching metrics, adding dimensions, writing EMF logs, querying Logs Insights, composing alarms, and shipping a dashboard as code.
Each example stays small. The dedicated pages later in this section go deeper on any one of these.
pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-cloudwatch @aws-sdk/client-cloudwatch-logs (Node.js 18+).aws configure, environment variables, or an IAM role.us-east-1.CreateLogGroup).PutMetricData accepts up to 1,000 MetricDatum entries per call. Publish several related metrics in one request instead of one request each.
# --- Python (boto3) ---
import boto3
cw = boto3.client("cloudwatch", region_name="us-east-1")
cw.put_metric_data(
Namespace="MyApp",
MetricData=[
{"MetricName": "OrdersFailed", "Value": 2, "Unit": "Count"},
{"MetricName": "OrdersSucceeded", "Value": 48, "Unit": "Count"},
{"MetricName": "CheckoutLatency", "Value": 210, "Unit": "Milliseconds"},
],
)
print("3 metrics published in 1 call")// --- TypeScript (AWS SDK v3) ---
import { CloudWatchClient, PutMetricDataCommand } from "@aws-sdk/client-cloudwatch";
const cw = new CloudWatchClient({ region: "us-east-1" });
await cw.send(new PutMetricDataCommand({
Namespace: "MyApp",
MetricData: [
{ MetricName: "OrdersFailed", Value: 2, Unit: "Count" },
{ MetricName: "OrdersSucceeded", Value: 48, Unit: "Count" },
{ MetricName: "CheckoutLatency", Value: 210, Unit: "Milliseconds" },
],
}));
console.log("3 metrics published in 1 call");PutMetricData call can carry many different metric names at once.MetricDatum still needs its own Unit - mixing units across a batch is fine.Dimensions let you break one metric name down by service, environment, or any other axis you care about.
# --- Python (boto3) ---
import boto3
cw = boto3.client("cloudwatch", region_name="us-east-1")
cw.put_metric_data(
Namespace="MyApp",
MetricData=[{
"MetricName": "OrdersFailed",
"Value": 1, "Unit": "Count",
"Dimensions": [
{"Name": "Service", "Value": "checkout"},
{"Name": "Environment", "Value": "prod"},
],
}],
)// --- TypeScript (AWS SDK v3) ---
import { CloudWatchClient, PutMetricDataCommand } from "@aws-sdk/client-cloudwatch";
const cw = new CloudWatchClient({ region: "us-east-1" });
await cw.send(new PutMetricDataCommand({
Namespace: "MyApp",
MetricData: [{
MetricName: "OrdersFailed",
Value: 1, Unit: "Count",
Dimensions: [
{ Name: "Service", Value: "checkout" },
{ Name: "Environment", Value: "prod" },
],
}],
}));Embedded Metric Format lets a single structured log line become a metric, with no separate metrics API call.
# --- Python (boto3) ---
import json, time
emf = {
"_aws": {
"Timestamp": int(time.time() * 1000),
"CloudWatchMetrics": [{
"Namespace": "MyApp",
"Dimensions": [["Service"]],
"Metrics": [{"Name": "OrdersFailed", "Unit": "Count"}],
}],
},
"Service": "checkout",
"OrdersFailed": 1,
}
print(json.dumps(emf)) # in Lambda, printing this to stdout is enough// --- TypeScript (AWS SDK v3) ---
const emf = {
_aws: {
Timestamp: Date.now(),
CloudWatchMetrics: [{
Namespace: "MyApp",
Dimensions: [["Service"]],
Metrics: [{ Name: "OrdersFailed", Unit: "Count" }],
}],
},
Service: "checkout",
OrdersFailed: 1,
};
console.log(JSON.stringify(emf)); // in Lambda, stdout is captured to CloudWatch Logs_aws.CloudWatchMetrics envelope is what tells CloudWatch to extract a metric from this log line.PutMetricData call happens - this is a normal log write that CloudWatch parses.console.log/print output already goes to CloudWatch Logs, so EMF needs no extra plumbing.PutLogEvents like any other log.Start an async query against a log group, then poll for results.
# --- Python (boto3) ---
import boto3, time
logs = boto3.client("logs", region_name="us-east-1")
start = logs.start_query(
logGroupName="/myapp/checkout",
startTime=int(time.time()) - 3600,
endTime=int(time.time()),
queryString="fields @timestamp, @message | filter @message like /failed/ | limit 20",
)
query_id = start["queryId"]
time.sleep(2)
result = logs.get_query_results(queryId=query_id)
print(result["status"], len(result["results"]))// --- TypeScript (AWS SDK v3) ---
import { CloudWatchLogsClient, StartQueryCommand, GetQueryResultsCommand } from "@aws-sdk/client-cloudwatch-logs";
const logs = new CloudWatchLogsClient({ region: "us-east-1" });
const now = Math.floor(Date.now() / 1000);
const { queryId } = await logs.send(new StartQueryCommand({
logGroupName: "/myapp/checkout",
startTime: now - 3600,
endTime: now,
queryString: "fields @timestamp, @message | filter @message like /failed/ | limit 20",
}));
await new Promise((r) => setTimeout(r, 2000));
const result = await logs.send(new GetQueryResultsCommand({ queryId }));
console.log(result.status, result.results?.length);StartQuery returns immediately with a queryId - it does not block until results are ready.GetQueryResults must be polled until status is Complete; a fixed sleep is a placeholder, not production polling.fields, filter, stats, sort) - it is not a CodeGroup target, just a string argument.limit and by a maximum scanned data volume per query.Related: CloudWatch Logs Insights Queries via SDK.
Combine two existing alarms with boolean logic to reduce noise from either one firing alone.
# --- Python (boto3) ---
import boto3
cw = boto3.client("cloudwatch", region_name="us-east-1")
cw.put_composite_alarm(
AlarmName="checkout-degraded",
AlarmRule="ALARM(checkout-failures) AND ALARM(checkout-latency-high)",
AlarmActions=["arn:aws:sns:us-east-1:111122223333:alerts"],
)// --- TypeScript (AWS SDK v3) ---
import { CloudWatchClient, PutCompositeAlarmCommand } from "@aws-sdk/client-cloudwatch";
const cw = new CloudWatchClient({ region: "us-east-1" });
await cw.send(new PutCompositeAlarmCommand({
AlarmName: "checkout-degraded",
AlarmRule: "ALARM(checkout-failures) AND ALARM(checkout-latency-high)",
AlarmActions: ["arn:aws:sns:us-east-1:111122223333:alerts"],
}));AlarmRule references other alarms by name inside a boolean expression.checkout-failures, checkout-latency-high) must already exist.AlarmActions, separate from their child alarms' actions.Related: Composite Alarms & Anomaly Detection.
Alarm against a machine-learned baseline instead of a fixed number.
# --- Python (boto3) ---
import boto3
cw = boto3.client("cloudwatch", region_name="us-east-1")
cw.put_anomaly_detector(
Namespace="MyApp", MetricName="CheckoutLatency", Stat="Average",
)
cw.put_metric_alarm(
AlarmName="checkout-latency-anomaly",
Namespace="MyApp", MetricName="CheckoutLatency", Statistic="Average",
Period=300, EvaluationPeriods=2,
ComparisonOperator="GreaterThanUpperThreshold",
ThresholdMetricId="ad1",
Metrics=[
{"Id": "m1", "MetricStat": {"Metric": {"Namespace": "MyApp",
"MetricName": "CheckoutLatency"}, "Period": 300, "Stat": "Average"},
"ReturnData": True},
{"Id": "ad1", "Expression": "ANOMALY_DETECTION_BAND(m1, 2)",
"ReturnData": True},
],
)// --- TypeScript (AWS SDK v3) ---
import { CloudWatchClient, PutAnomalyDetectorCommand, PutMetricAlarmCommand } from "@aws-sdk/client-cloudwatch";
const cw = new CloudWatchClient({ region: "us-east-1" });
await cw.send(new PutAnomalyDetectorCommand({
Namespace: "MyApp", MetricName: "CheckoutLatency", Stat: "Average",
}));
await cw.send(new PutMetricAlarmCommand({
AlarmName: "checkout-latency-anomaly",
Namespace: "MyApp", MetricName: "CheckoutLatency", Statistic: "Average",
Period: 300, EvaluationPeriods: 2,
ComparisonOperator: "GreaterThanUpperThreshold",
ThresholdMetricId: "ad1",
Metrics: [
{ Id: "m1", MetricStat: { Metric: { Namespace: "MyApp",
MetricName: "CheckoutLatency" }, Period: 300, Stat: "Average" }, ReturnData: true },
{ Id: "ad1", Expression: "ANOMALY_DETECTION_BAND(m1, 2)", ReturnData: true },
],
}));PutAnomalyDetector trains a model for a metric+statistic pair; it does not create an alarm by itself.Metrics array feeds the raw metric plus an ANOMALY_DETECTION_BAND expression into the comparison.ThresholdMetricId points the alarm at the anomaly band instead of a static Threshold.INSUFFICIENT_DATA for the first couple of weeks.Related: Composite Alarms & Anomaly Detection.
Create or update a dashboard from a JSON widget-layout document.
# --- Python (boto3) ---
import boto3, json
cw = boto3.client("cloudwatch", region_name="us-east-1")
body = {
"widgets": [{
"type": "metric", "x": 0, "y": 0, "width": 12, "height": 6,
"properties": {
"metrics": [["MyApp", "OrdersFailed"]],
"period": 300, "stat": "Sum", "region": "us-east-1",
"title": "Orders Failed",
},
}],
}
cw.put_dashboard(DashboardName="checkout-overview", DashboardBody=json.dumps(body))// --- TypeScript (AWS SDK v3) ---
import { CloudWatchClient, PutDashboardCommand } from "@aws-sdk/client-cloudwatch";
const cw = new CloudWatchClient({ region: "us-east-1" });
const body = {
widgets: [{
type: "metric", x: 0, y: 0, width: 12, height: 6,
properties: {
metrics: [["MyApp", "OrdersFailed"]],
period: 300, stat: "Sum", region: "us-east-1",
title: "Orders Failed",
},
}],
};
await cw.send(new PutDashboardCommand({
DashboardName: "checkout-overview",
DashboardBody: JSON.stringify(body),
}));DashboardBody is a JSON string, not a typed structure - both SDKs just serialize a plain object.PutDashboard is idempotent by name: calling it again with the same name replaces the layout.x, y, width, height) are in a 24-column grid.Related: Dashboards as Code via SDK.
Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).
Revisado por Chris St. John·Última actualización: 25 jul 2026