Configuration Guide

Configuration Guide

This guide provides comprehensive information about configuring the DataDog Dashboard Deployer package.

Configuration File Structure

The package uses YAML configuration files to define dashboard layouts and settings. Here's the basic structure:

version: "1.0"
defaults:
  layout_type: "ordered"
  refresh_interval: 300

dashboards:
  - name: "System Overview"
    description: "System performance metrics"
    layout_type: "ordered"
    widgets:
      - title: "CPU Usage"
        type: "timeseries"
        query: "avg:system.cpu.user{*}"

Configuration Options

1. Global Settings

version: "1.0" # Configuration version
defaults:
  layout_type: "ordered" # Default layout type
  refresh_interval: 300 # Default refresh interval in seconds
  tags: # Default tags for all dashboards
    - "team:infrastructure"
    - "env:production"

2. Dashboard Configuration

dashboards:
  - name: "Dashboard Name" # Required
    description: "Dashboard description" # Optional
    layout_type: "ordered" # Optional (defaults to global setting)
    tags: # Optional
      - "team:infrastructure"
    widgets: [] # Required (list of widgets)

3. Widget Types

Time Series Widget

widgets:
  - title: "CPU Usage"
    type: "timeseries"
    size: "medium"
    query: "avg:system.cpu.user{*}"
    visualization:
      type: "line"
      yaxis:
        min: 0
        max: 100

Query Value Widget

widgets:
  - title: "Total Requests"
    type: "query_value"
    query: "sum:http.requests{*}"
    precision: 0
    format: "number"

Heat Map Widget

widgets:
  - title: "Response Times"
    type: "heatmap"
    query: "avg:http.response.time{*} by {host}"

4. Layout Options

layout_type: "ordered" # or "free"
layout:
  height: 800
  width: 1200
  widgets:
    - widget_id: "w1"
      x: 0
      y: 0
      width: 600
      height: 400

Environment Variables

Required Variables

DATADOG_API_KEY=your-api-key
DATADOG_APP_KEY=your-application-key

Optional Variables

DATADOG_SITE=datadoghq.com  # Default site
DATADOG_HOST=https://api.datadoghq.com  # API endpoint

Template Variables

1. Basic Templates

template_variables:
  - name: "env"
    prefix: "env"
    default: "prod"
  - name: "service"
    prefix: "service"
    default: "*"

2. Advanced Templates

template_variables:
  - name: "datacenter"
    prefix: "datacenter"
    default: "us-east-1"
    values:
      - "us-east-1"
      - "us-west-2"
      - "eu-west-1"

Query Configuration

1. Metric Queries

query: "avg:system.cpu.user{$env} by {host}"

2. Event Queries

events_query:
  q: "sources:nagios status:error"
  tags_execution: "and"

3. Log Queries

logs_query:
  query: "service:web-api status:error"
  indexes: ["main"]

Advanced Features

1. Dynamic Dashboards

dashboards:
  - name: "{{env}} Service Dashboard"
    template_variables:
      - name: "env"
        values: ["prod", "staging", "dev"]

2. Conditional Widgets

widgets:
  - title: "Error Rate"
    conditional_formats:
      - comparator: ">"
        value: 1
        palette: "red"
      - comparator: ">"
        value: 0.5
        palette: "yellow"

3. Custom Links

widgets:
  - title: "Service Status"
    custom_links:
      - label: "View Logs"
        link: "https://app.datadoghq.com/logs"

Best Practices

1. Organization

• Use meaningful dashboard and widget names
• Group related metrics together
• Use consistent naming conventions
• Include descriptions

2. Performance

• Limit the number of widgets per dashboard
• Use efficient queries
• Set appropriate refresh intervals
• Consider time ranges

3. Maintenance

• Use version control
• Document changes
• Test configurations
• Regular reviews

Examples

1. Basic Dashboard

dashboards:
  - name: "Basic System Monitoring"
    description: "Essential system metrics"
    widgets:
      - title: "CPU Usage"
        type: "timeseries"
        query: "avg:system.cpu.user{*}"
      - title: "Memory Usage"
        type: "timeseries"
        query: "avg:system.mem.used{*}"

2. Application Dashboard

dashboards:
  - name: "Web Application"
    template_variables:
      - name: "service"
        prefix: "service"
        default: "web-api"
    widgets:
      - title: "Request Rate"
        type: "timeseries"
        query: "sum:http.requests{service:$service}"
      - title: "Error Rate"
        type: "query_value"
        query: "sum:http.errors{service:$service}"

Validation

1. Schema Validation

datadog-dashboard-deploy --validate config.yaml

2. Dry Run

datadog-dashboard-deploy --dry-run config.yaml

Troubleshooting

Common Issues

1. Invalid Configuration

   # Wrong
   widgets:
     - type: "timeseries"
       # Missing required 'title' field
   
   # Correct
   widgets:
     - title: "Metric"
       type: "timeseries"
       query: "avg:system.cpu.user{*}"

2. Query Syntax

   # Wrong
   query: "avg:system.cpu.user{env:prod}}"  # Extra }
   
   # Correct
   query: "avg:system.cpu.user{env:prod}"

Additional Resources

• DataDog API Documentation
• Dashboard JSON Schema
• Query Guide