Dashboards

# Dashboards Reference ## ⚠️ CRITICAL: Dashboard Update is DESTRUCTIVE **The `dashboards update` command REPLACES the entire dashboard, not just the fields you specify.** If you omit any of these fields during an update, they will be **permanently deleted**: - `--template-variables` → Template variables will be removed - `--description` → Description will be cleared - `--notify-list` → Notify list will be cleared **Example of DATA LOSS:** ```bash # This will DELETE template variables and description! npx @leoflores/datadog-cli dashboards update --id "abc-def-ghi" --title "My Dashboard" --layout ordered --widgets '[...]' # Only widgets provided, other fields wiped! ``` ## Safe Dashboard Update Workflow **ALWAYS follow this 3-step process when updating dashboards:** > ⚠️ **Important:** Always use `--output` to save to a temp file instead of capturing output in a bash variable. JSON with special characters, newlines, or ANSI codes can break `jq` parsing when piped through `echo`. ### Step 1: Backup the Current Dashboard to a Temp File ```bash # Save the current dashboard state BEFORE any changes # Using --output ensures clean JSON without encoding issues npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --output /tmp/dashboard.json ``` ### Step 2: Modify and Preserve All Fields ```bash # Extract existing values directly from the file (not through echo!) TEMPLATE_VARS=$(jq -c '.dashboard.templateVariables // []' /tmp/dashboard.json) DESCRIPTION=$(jq -r '.dashboard.description // ""' /tmp/dashboard.json) # Modify widgets (example: change title of widget at index 1) WIDGETS=$(jq -c '.dashboard.widgets | .[1].definition.title = "New Title"' /tmp/dashboard.json) # Update with ALL fields preserved npx @leoflores/datadog-cli dashboards update --id "abc-def-ghi" --title "My Dashboard" --layout ordered --widgets "$WIDGETS" --description "$DESCRIPTION" --template-variables "$TEMPLATE_VARS" --pretty ``` ### Step 3: Verify the Update ```bash # Confirm all fields are intact npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --pretty ``` ### Recovery from Accidental Data Loss ```bash # If you have a backup file, restore from it WIDGETS=$(jq -c '.dashboard.widgets' /tmp/dashboard.json) TEMPLATE_VARS=$(jq -c '.dashboard.templateVariables // []' /tmp/dashboard.json) DESCRIPTION=$(jq -r '.dashboard.description // ""' /tmp/dashboard.json) TITLE=$(jq -r '.dashboard.title' /tmp/dashboard.json) LAYOUT=$(jq -r '.dashboard.layoutType' /tmp/dashboard.json) npx @leoflores/datadog-cli dashboards update --id "abc-def-ghi" --title "$TITLE" --layout "$LAYOUT" --widgets "$WIDGETS" --description "$DESCRIPTION" --template-variables "$TEMPLATE_VARS" --pretty ``` ### Why Use Files Instead of Variables? ❌ **Don't do this** - prone to parsing errors: ```bash DASHBOARD_JSON=$(npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi") WIDGETS=$(echo "$DASHBOARD_JSON" | jq -c '.dashboard.widgets') # May fail! ``` ✅ **Do this** - reliable with any JSON content: ```bash npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --output /tmp/dashboard.json WIDGETS=$(jq -c '.dashboard.widgets' /tmp/dashboard.json) # Always works ``` ## Commands Overview | Command | Description | |---------|-------------| | `dashboards list` | List all dashboards | | `dashboards get` | Get full dashboard definition | | `dashboards create` | Create a new dashboard | | `dashboards update` | ⚠️ **DESTRUCTIVE** - Replaces entire dashboard | | `dashboards delete` | Delete a dashboard | | `dashboard-lists list` | List all dashboard lists | | `dashboard-lists get` | Get dashboard list details | | `dashboard-lists create` | Create a new list | | `dashboard-lists update` | Update list name | | `dashboard-lists delete` | Delete a list | | `dashboard-lists items` | List dashboards in a list | | `dashboard-lists add-items` | Add dashboards to list | | `dashboard-lists delete-items` | Remove dashboards from list | ## Dashboard Flags | Flag | Commands | Description | |------|----------|-------------| | `--id` | get, update, delete | Dashboard ID | | `--title` | create, update | Dashboard title | | `--layout` | create, update | `ordered` or `free` | | `--widgets` | create, update | Widgets JSON (or stdin) | | `--description` | create, update | ⚠️ **Required on update to preserve** | | `--template-variables` | create, update | ⚠️ **Required on update to preserve** | | `--notify-list` | create, update | ⚠️ **Required on update to preserve** | | `--read-only` | create, update | Make read-only | ## Examples ### List & Get ```bash npx @leoflores/datadog-cli dashboards list --pretty npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --pretty ``` ### Create Dashboard ```bash npx @leoflores/datadog-cli dashboards create --title "API Monitoring" --layout ordered --widgets '[{"definition":{"type":"timeseries","requests":[{"q":"avg:system.cpu.user{*}"}]}}]' --pretty ``` ### With Template Variables ```bash npx @leoflores/datadog-cli dashboards create --title "Service Dashboard" --layout ordered --template-variables '[{"name":"env","prefix":"env","default":"prod"},{"name":"service","prefix":"service","default":"*"}]' --widgets '[{"definition":{"type":"timeseries","requests":[{"q":"avg:system.cpu.user{$env,$service}"}]}}]' --pretty ``` ### Using Stdin ```bash cat widgets.json | npx @leoflores/datadog-cli dashboards create --title "My Dashboard" --layout ordered --pretty ``` ## Template Variables ```json {"name": "env", "prefix": "env", "default": "prod"} ``` Use in queries: `avg:system.cpu.user{$env,$service}` ## Widget Types ### Timeseries ```json {"definition": {"type": "timeseries", "title": "CPU", "requests": [{"q": "avg:system.cpu.user{*}"}]}} ``` ### Query Value ```json {"definition": {"type": "query_value", "title": "Errors", "requests": [{"q": "sum:errors{*}.as_count()"}]}} ``` ### Top List ```json {"definition": {"type": "toplist", "title": "Top Services", "requests": [{"q": "top(sum:errors{*} by {service}, 10, 'sum', 'desc')"}]}} ``` ## Layout Types - **ordered**: Auto-arranged responsive grid - **free**: Manual positioning with x, y, width, height ## Dashboard Lists ```bash # List all npx @leoflores/datadog-cli dashboard-lists list --pretty # Add dashboards to list npx @leoflores/datadog-cli dashboard-lists add-items --id 123 --dashboards '[{"type":"custom_timeboard","id":"abc-def-ghi"}]' --pretty ```