Templating Guide

Templating Guide

Guide to using templates and variables in dashboard configurations.

Template Variables

Basic Template Variables

template_variables:
  - name: "env"
    prefix: "env"
    default: "prod"
  - name: "service"
    prefix: "service"
    default: "web-api"

Using Template Variables

widgets:
  - title: "CPU Usage ($env)"
    type: "timeseries"
    query: "avg:system.cpu.user{env:$env,service:$service}"

Default Values

Dashboard Defaults

version: "1.0"
defaults:
  layout_type: "ordered"
  refresh_interval: 300
  tags:
    - "team:infrastructure"
    - "env:production"

dashboards:
  - name: "System Dashboard"
    # Inherits defaults
    widgets: []

Widget Templates

widget_templates:
  cpu_widget: &cpu_widget
    type: "timeseries"
    query: "avg:system.cpu.user{$scope}"
    visualization:
      type: "line"
      yaxis:
        min: 0
        max: 100

dashboards:
  - name: "System Dashboard"
    widgets:
      - title: "Production CPU"
        <<: *cpu_widget
        query: "avg:system.cpu.user{env:prod}"
      - title: "Staging CPU"
        <<: *cpu_widget
        query: "avg:system.cpu.user{env:staging}"

Advanced Templates

Conditional Widgets

version: "1.0"
dashboards:
  - name: "Environment Dashboard"
    template_variables:
      - name: "env"
        prefix: "env"
        default: "prod"
    widgets:
      - title: "Requests ($env)"
        type: "timeseries"
        query: >
          avg:http.requests{env:$env}
          {{#if eq env "prod"}}
          .rollup(sum, 3600)
          {{else}}
          .rollup(sum, 300)
          {{/if}}

Reusable Components

components:
  monitoring: &monitoring_widgets
    - title: "CPU Usage"
      type: "timeseries"
      query: "avg:system.cpu.user{$scope}"
    - title: "Memory Usage"
      type: "timeseries"
      query: "avg:system.mem.used{$scope}"

dashboards:
  - name: "Production Monitoring"
    widgets:
      <<: *monitoring_widgets
      scope: "env:production"

  - name: "Staging Monitoring"
    widgets:
      <<: *monitoring_widgets
      scope: "env:staging"

Best Practices

1. Variable Naming

• Use descriptive names
• Follow consistent naming conventions
• Document variable purposes

2. Default Values

• Always provide sensible defaults
• Consider environment-specific defaults
• Document default behavior

3. Template Organization

• Group related templates
• Use clear component names
• Maintain template documentation

4. Performance Considerations

• Limit template complexity
• Consider query optimization
• Monitor template expansion

Examples

1. Environment-based Dashboard

version: "1.0"
defaults:
  tags:
    - "managed-by:datadog-dashboard-deployer"

dashboards:
  - name: "$env Application Dashboard"
    template_variables:
      - name: "env"
        prefix: "env"
        values: ["prod", "staging", "dev"]
    widgets:
      - title: "Requests ($env)"
        type: "timeseries"
        query: "sum:http.requests{env:$env}"

2. Service Monitoring Template

templates:
  service_monitor: &service_monitor
    template_variables:
      - name: "service"
        prefix: "service"
    widgets:
      - title: "$service Status"
        type: "check_status"
        check: "service.up"
        group: "cluster"
      - title: "$service Errors"
        type: "timeseries"
        query: "sum:service.errors{service:$service}"

dashboards:
  - name: "Web API Monitor"
    <<: *service_monitor
    service: "web-api"

  - name: "Database Monitor"
    <<: *service_monitor
    service: "database"

Related Resources

• Configuration Guide
• Dashboard Examples
• Best Practices