Getting Started

Getting Started

This guide will help you get up and running with the DataDog Dashboard Deployer quickly.

Prerequisites

Before you begin, ensure you have:

1. Python 3.8 or higher installed
2. pip (Python package manager)
3. A DataDog account with API and Application keys
4. Git (optional, for development)

Quick Start

1. Installation

# Install from PyPI
pip install datadog-dashboard-deployer

# Verify installation
datadog-dashboard-deploy --version

2. Configuration

1. Set up your DataDog credentials:

   # Linux/macOS
   export DATADOG_API_KEY='your-api-key'
   export DATADOG_APP_KEY='your-application-key'
   
   # Windows (PowerShell)
   $env:DATADOG_API_KEY='your-api-key'
   $env:DATADOG_APP_KEY='your-application-key'

2. Create a basic dashboard configuration:

   # config/dashboard_config.yaml
   version: "1.0"
   
   dashboards:
     - name: "My First Dashboard"
       description: "Basic system metrics"
       widgets:
         - title: "CPU Usage"
           type: "timeseries"
           query: "avg:system.cpu.user{*}"
         - title: "Memory Usage"
           type: "timeseries"
           query: "avg:system.mem.used{*}"

3. Deploy your dashboard:

   datadog-dashboard-deploy config/dashboard_config.yaml

Basic Usage

1. Command Line Interface

# Validate configuration
datadog-dashboard-deploy --validate config.yaml

# Dry run (preview changes)
datadog-dashboard-deploy --dry-run config.yaml

# Deploy with verbose output
datadog-dashboard-deploy --verbose config.yaml

# Show help
datadog-dashboard-deploy --help

2. Basic Configuration Examples

System Monitoring Dashboard

dashboards:
  - name: "System Overview"
    description: "Key system metrics"
    widgets:
      - title: "CPU Usage"
        type: "timeseries"
        query: "avg:system.cpu.user{*}"
      - title: "Memory Usage"
        type: "timeseries"
        query: "avg:system.mem.used{*}"
      - title: "Disk Usage"
        type: "query_value"
        query: "avg:system.disk.used{*}"

Application Monitoring Dashboard

dashboards:
  - name: "Application Status"
    description: "Application performance metrics"
    template_variables:
      - name: "env"
        prefix: "env"
        default: "prod"
    widgets:
      - title: "Request Rate"
        type: "timeseries"
        query: "sum:http.requests{env:$env}"
      - title: "Error Rate"
        type: "query_value"
        query: "sum:http.errors{env:$env}"

GitHub Actions Integration

1. Create a GitHub repository for your dashboards

2. Add DataDog credentials as secrets:

   • Go to repository Settings > Secrets and Variables > Actions
   • Add DATADOG_API_KEY and DATADOG_APP_KEY

3. Create a workflow file:

   # .github/workflows/deploy.yml
   name: Deploy Dashboards
   
   on:
     push:
       branches: [main]
     workflow_dispatch:
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v2
         - name: Set up Python
           uses: actions/setup-python@v2
           with:
             python-version: "3.x"
         - name: Install dependencies
           run: pip install datadog-dashboard-deployer
         - name: Deploy dashboards
           env:
             DATADOG_API_KEY: ${{ secrets.DATADOG_API_KEY }}
             DATADOG_APP_KEY: ${{ secrets.DATADOG_APP_KEY }}
           run: datadog-dashboard-deploy config/dashboard_config.yaml

Next Steps

1. Read the Configuration Guide for detailed configuration options
2. Check out the Examples for more dashboard templates
3. Review Security best practices
4. Join our GitHub Discussions

Common Issues

1. Authentication Errors

# Error: API authentication failed
# Solution: Check your API and Application keys
export DATADOG_API_KEY='correct-api-key'
export DATADOG_APP_KEY='correct-app-key'

2. Configuration Errors

# Error: Invalid widget configuration
# Wrong:
widgets:
  - type: "timeseries"
    # Missing required 'title' field

# Correct:
widgets:
  - title: "CPU Usage"
    type: "timeseries"
    query: "avg:system.cpu.user{*}"

3. Permission Issues

• Ensure your API key has appropriate permissions
• Check DataDog role assignments
• Verify organization access

Getting Help

• Check the FAQ for common questions
• Visit our Support page
• Join GitHub Discussions
• Report issues on GitHub Issues