Busca en todas las páginas de la documentación
A CloudWatch dashboard is a JSON document describing a grid of widgets. There is no drag-and-drop-only path required - PutDashboard accepts that JSON directly, which means dashboards can be generated, templated, and version-controlled exactly like the rest of your infrastructure.
This page covers building, reading, and updating dashboards from the SDK.
Quick-reference recipe card - copy-paste ready.
# --- 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),
}));When to reach for this:
Create a multi-widget dashboard, read it back, then update it in place.
# --- Python (boto3) ---
import boto3, json
cw = boto3.client("cloudwatch", region_name="us-east-1")
NAME = "checkout-overview"
# 1. Build a dashboard with a metric widget and a log-query widget.
body = {
"widgets": [
{
"type": "metric", "x": 0, "y": 0, "width": 12, "height": 6,
"properties": {
"metrics": [
["MyApp", "OrdersFailed", {"stat": "Sum", "label": "Failed"}],
["MyApp", "OrdersSucceeded", {"stat": "Sum", "label": "Succeeded"}],
],
"period": 300, "region": "us-east-1", "title": "Order Outcomes",
},
},
{
"type": "log", "x": 12, "y": 0, "width": 12, "height": 6,
"properties": {
"query": "SOURCE '/myapp/checkout' | fields @timestamp, @message"
" | filter @message like /ERROR/ | limit 20",
"region": "us-east-1", "title": "Recent Errors", "view": "table",
},
},
],
}
cw.put_dashboard(DashboardName=NAME, DashboardBody=json.dumps(body))
# 2. Read it back.
current = cw.get_dashboard(DashboardName=NAME)
loaded = json.loads(current["DashboardBody"])
print(len(loaded["widgets"]), "widgets")
# 3. Update: add a third widget and re-put the whole body.
loaded["widgets"].append({
"type": "text", "x": 0, "y": 6, "width": 24, "height": 2,
"properties": {"markdown": "## Checkout Service - On-call: #checkout-oncall"},
})
cw.put_dashboard(DashboardName=NAME, DashboardBody=json.dumps(loaded))// --- TypeScript (AWS SDK v3) ---
import {
CloudWatchClient, PutDashboardCommand, GetDashboardCommand,
} from "@aws-sdk/client-cloudwatch";
const cw = new CloudWatchClient({ region: "us-east-1" });
const NAME = "checkout-overview";
// 1. Build a dashboard with a metric widget and a log-query widget.
const body = {
widgets: [
{
type: "metric", x: 0, y: 0, width: 12, height: 6,
properties: {
metrics: [
["MyApp", "OrdersFailed", { stat: "Sum", label: "Failed" }],
["MyApp", "OrdersSucceeded", { stat: "Sum", label: "Succeeded" }],
],
period: 300, region: "us-east-1", title: "Order Outcomes",
},
},
{
type: "log", x: 12, y: 0, width: 12, height: 6,
properties: {
query: "SOURCE '/myapp/checkout' | fields @timestamp, @message"
+ " | filter @message like /ERROR/ | limit 20",
region: "us-east-1", title: "Recent Errors", view: "table",
},
},
],
};
await cw.send(new PutDashboardCommand({ DashboardName: NAME, DashboardBody: JSON.stringify(body) }));
// 2. Read it back.
const current = await cw.send(new GetDashboardCommand({ DashboardName: NAME }));
const loaded = JSON.parse(current.DashboardBody!);
console.log(loaded.widgets.length, "widgets");
// 3. Update: add a third widget and re-put the whole body.
loaded.widgets.push({
type: "text", x: 0, y: 6, width: 24, height: 2,
properties: { markdown: "## Checkout Service - On-call: #checkout-oncall" },
});
await cw.send(new PutDashboardCommand({ DashboardName: NAME, DashboardBody: JSON.stringify(loaded) }));What this demonstrates:
log widget embeds a Logs Insights query directly - SOURCE '<log-group>' | <query> - and renders its results as a table or visualization.GetDashboard returns DashboardBody as a JSON string you parse yourself; the SDK does not model widgets as typed objects.PutDashboard again with the full body - there is no widget-level patch operation.text widget renders markdown, useful for on-call links or runbook context alongside the metrics.Every widget occupies a rectangle on a 24-column-wide grid, positioned by x/y and sized by width/height. There is no automatic layout - your code (or a human in the Console) decides where each widget goes.
Common widget type values:
| Type | Renders | Key properties |
|---|---|---|
metric | A graph or number of one or more metrics | metrics, period, stat, view (timeSeries, singleValue, bar, pie) |
log | A Logs Insights query result | query (a SOURCE '<group>' | ... string), view (table, bar, pie, stacked) |
text | Static markdown | markdown |
alarm | An alarm's current state and history | alarms (list of alarm ARNs) |
PutDashboard always replaces the entire DashboardBody for that name. There is no operation to add or remove a single widget server-side - the pattern is always read (or hold in memory), modify the JSON, and re-put the whole thing, as shown in the working example.
This makes dashboards a good fit for generation: build the JSON from a list of services or metrics known at deploy time, and PutDashboard the result idempotently on every deploy.
Because the body is plain JSON, the same generator function can parameterize namespace and region per environment.
# --- Python (boto3) ---
def build_dashboard(env: str, region: str) -> str:
ns = f"MyApp-{env}"
body = {"widgets": [{
"type": "metric", "x": 0, "y": 0, "width": 24, "height": 6,
"properties": {
"metrics": [[ns, "OrdersFailed"]],
"period": 300, "stat": "Sum", "region": region,
"title": f"Orders Failed ({env})",
},
}]}
return json.dumps(body)
cw.put_dashboard(DashboardName="checkout-prod", DashboardBody=build_dashboard("prod", "us-east-1"))// --- TypeScript (AWS SDK v3) ---
function buildDashboard(env: string, region: string): string {
const ns = `MyApp-${env}`;
const body = {
widgets: [{
type: "metric", x: 0, y: 0, width: 24, height: 6,
properties: {
metrics: [[ns, "OrdersFailed"]],
period: 300, stat: "Sum", region,
title: `Orders Failed (${env})`,
},
}],
};
return JSON.stringify(body);
}
await cw.send(new PutDashboardCommand({
DashboardName: "checkout-prod",
DashboardBody: buildDashboard("prod", "us-east-1"),
}));DashboardBody through as an opaque string. Fix: build and validate the JSON shape yourself; a malformed widget only surfaces as a Console rendering error, not a client-side type error.PutDashboard the full body back.region in metric/log widget properties - a dashboard viewed from a different default region can show blank widgets. Fix: set region explicitly per widget rather than relying on account defaults.x/y/width/height values can silently overlap. Fix: compute positions programmatically (a simple row/column layout function) instead of hardcoding by hand for larger dashboards.PutDashboard call. Fix: treat the SDK/generator as the single source of truth once a dashboard is code-managed.DashboardBody fails the call with a generic validation error. Fix: parse your own generated JSON locally before calling PutDashboard to catch mistakes early.| Alternative | Use When | Don't Use When |
|---|---|---|
| PutDashboard (this page) | Dashboards should be generated, templated, or version-controlled | A single, rarely-changed dashboard is easier to build by hand once in the Console |
| Console dashboard editor | Quick, one-off, exploratory dashboards | You need the same layout reproduced across environments |
CloudFormation/CDK/Terraform AWS::CloudWatch::Dashboard | Dashboards should deploy alongside the rest of your IaC-managed infrastructure | You need to regenerate dashboards dynamically at runtime from application state |
| Third-party dashboards (Grafana, Datadog) | Cross-cloud or more advanced visualization needs | A single-account, CloudWatch-native setup is sufficient |
No. It is always a plain JSON string in both boto3 and SDK v3 - you build and parse the widget structure yourself; the SDK does not model widgets as typed classes.
Not directly. PutDashboard replaces the entire DashboardBody for that name. Read the current body (or keep your generator's source of truth), modify it, and re-put the whole thing.
Common types are metric (graphs/numbers from CloudWatch metrics), log (a saved Logs Insights query), text (static markdown), and alarm (an alarm's state and history).
Its properties.query is a string in the form SOURCE '<log-group>' | <Logs Insights query>, rendered as a table or chart depending on view.
Yes, it is idempotent by DashboardName - calling it again with the same name simply replaces the layout, which is what makes dashboard generation on every deploy practical.
Generally no. Once a dashboard is generated from code, manual Console edits get overwritten on the next PutDashboard call. Pick one source of truth per dashboard.
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