managing-datadog-recipe

Datadog CLI Management

SCOPE: dogshell CLI for Datadog API operations.

Quick Reference

# Setup
pip install datadog
echo "api_key = YOUR_API_KEY" > ~/.dogrc
echo "app_key = YOUR_APP_KEY" >> ~/.dogrc

# Common operations
dog metric post my.metric 100 --tags "env:prod,service:api"
dog monitor show 12345
dog event post "Deploy completed" --tags "env:prod"
dog slo show abc123

When to Use

Post metrics | Query monitors | Manage SLOs | Create events | Schedule downtimes | Tag hosts | Dashboard operations

Installation & Authentication

# Install
pip install datadog

# Auth methods (priority order):
1. CLI flags: --api-key KEY --app-key KEY
2. Environment: export DATADOG_API_KEY=... DATADOG_APP_KEY=...
3. Config file: ~/.dogrc

~/.dogrc format:

[Connection]
apikey = YOUR_API_KEY
appkey = YOUR_APP_KEY
api_host = https://api.datadoghq.com  # Optional: EU → api.datadoghq.eu

1Password integration:

# Store in 1Password
op item create \
  --category=api-credential \
  --title="Datadog API" \
  api_key=YOUR_API_KEY \
  app_key=YOUR_APP_KEY

# Retrieve
export DATADOG_API_KEY=$(op item get "Datadog API" --fields api_key)
export DATADOG_APP_KEY=$(op item get "Datadog API" --fields app_key)

Core Commands

Command	Purpose	Example
metric	Post/query metrics	dog metric post cpu.usage 75
monitor	CRUD monitors	dog monitor show 12345
event	Post events	dog event post "Deploy v1.2"
slo	Manage SLOs	dog slo show abc123
downtime	Schedule downtimes	dog downtime schedule
tag	Manage host tags	dog tag show host123
dashboard	Manage dashboards	dog dashboard show dash-id
host	Query hosts	dog host show host123
search	Search Datadog	dog search query "service:api"

Metrics Operations

Post Metrics

# Basic
dog metric post my.metric VALUE

# With tags
dog metric post api.latency 250 --tags "env:prod,region:us-east-1"

# Scoped to host
dog metric post cpu.usage 80 --host web-01

# No host association
dog metric post batch.processed 1000 --no_host

# With device
dog metric post disk.usage 75 --device /dev/sda1

# Metric types
dog metric post requests.count 100 --type counter  # 64bit integer
dog metric post cpu.percent 45.5 --type gauge     # 32bit float

Tag format:

key:value,key2:value2
env:prod,service:api,version:1.2.0

Query Metrics

# Via search
dog search query "metric:api.latency env:prod"

Monitor Operations

Show Monitor

dog monitor show MONITOR_ID

# Multiple
dog monitor show 12345 67890

Show All Monitors

dog monitor show_all

# Filter by tags
dog monitor show_all --tags "env:prod,service:api"

# Filter by group
dog monitor show_all --group_states "alert,warn"

# Filter by name
dog monitor show_all --name "API Latency"

Create Monitor

# Not directly supported via dogshell
# Use Python API or Datadog UI
# Alternative: Use Datadog Terraform provider

Mute/Unmute Monitor

dog monitor mute MONITOR_ID

# With scope
dog monitor mute MONITOR_ID --scope "env:staging"

# With end time
dog monitor mute MONITOR_ID --end $(date -d "+2 hours" +%s)

# Unmute
dog monitor unmute MONITOR_ID

Delete Monitor

dog monitor delete MONITOR_ID

Event Operations

Post Event

# Basic
dog event post "Deployment completed"

# With text body
dog event post "Deploy v1.2.0" --text "Deployed to production"

# With tags
dog event post "Deploy" --tags "env:prod,version:1.2.0"

# With priority
dog event post "Critical issue" --priority "normal"  # normal | low

# With alert type
dog event post "Service down" --alert_type "error"  # error | warning | info | success

# With aggregation key
dog event post "Deploy" --aggregation_key "deploy-123"

# With source type
dog event post "Deploy" --source_type_name "jenkins"

# With host
dog event post "Deploy" --host "web-01"

Show Event

dog event show EVENT_ID

Query Events

# Via search
dog search query "sources:jenkins"
dog search query "tags:env:prod"

SLO Operations

Show SLO

dog slo show SLO_ID

# With time window
dog slo show abc123 --from_ts $(date -d "-30 days" +%s) --to_ts $(date +%s)

Show All SLOs

dog slo show_all

# Filter by tags
dog slo show_all --tags "env:prod"

# Filter by IDs
dog slo show_all --ids "abc123,def456"

Check SLO Status

# History
dog slo history SLO_ID

# With time window
dog slo history abc123 --from_ts $(date -d "-7 days" +%s) --to_ts $(date +%s)

Downtime Operations

Schedule Downtime

# Basic (1 hour from now)
dog downtime schedule "scope:env:staging"

# With message
dog downtime schedule "host:web-01" --message "Maintenance window"

# With start/end time
dog downtime schedule "service:api" \
  --start $(date +%s) \
  --end $(date -d "+2 hours" +%s)

# Recurring (not supported via CLI, use Python API)

Show Downtime

dog downtime show DOWNTIME_ID

Show All Downtimes

dog downtime show_all

# Current only
dog downtime show_all --current_only

Cancel Downtime

dog downtime cancel DOWNTIME_ID

Tag Operations

Show Host Tags

dog tag show HOST

# By source
dog tag show web-01 --source "chef"

Add Host Tags

dog tag add HOST TAG1 TAG2

# Examples
dog tag add web-01 "env:prod" "role:webserver"

Update Host Tags

# Replace all tags
dog tag update HOST TAG1 TAG2

# By source
dog tag update web-01 "env:prod" --source "terraform"

Detach Host Tags

dog tag detach HOST

# By source
dog tag detach web-01 --source "ansible"

Dashboard Operations

Show Dashboard

dog dashboard show DASHBOARD_ID

Show All Dashboards

dog dashboard show_all

Host Operations

Show Host

dog host show HOST

# With from timestamp
dog host show web-01 --from $(date -d "-1 hour" +%s)

Mute Host

dog host mute HOST

# With message
dog host mute web-01 --message "Planned maintenance"

# With end time
dog host mute web-01 --end $(date -d "+2 hours" +%s)

# Override (end previous mute)
dog host mute web-01 --override

Unmute Host

dog host unmute HOST

Search Operations

# Search hosts
dog search hosts "role:webserver"

# Search metrics
dog search metrics "metric:api.*"

# General query
dog search query "tags:env:prod service:api"

Service Checks

# Post service check
dog service_check check SERVICE_CHECK_NAME HOST STATUS

# Statuses: 0 (OK), 1 (WARNING), 2 (CRITICAL), 3 (UNKNOWN)
dog service_check check api.health web-01 0

# With message
dog service_check check db.connection db-01 2 --message "Connection timeout"

# With tags
dog service_check check cache.available redis-01 0 --tags "env:prod"

# With timestamp
dog service_check check api.health web-01 0 --timestamp $(date +%s)

Common Patterns

See patterns.md for:

• CI/CD integration (deploy events, metrics)
• Maintenance window scheduling
• SLO monitoring and alerting
• Batch metric posting
• Monitor health checks
• Error handling and retries

Environment Variables

Variable	Purpose	Example
DATADOG_API_KEY	API key (fallback to DD_API_KEY)	export DATADOG_API_KEY=...
DATADOG_APP_KEY	App key (fallback to DD_APP_KEY)	export DATADOG_APP_KEY=...
DD_API_KEY	API key (alternative)	export DD_API_KEY=...
DD_APP_KEY	App key (alternative)	export DD_APP_KEY=...
DD_SITE	Datadog site	export DD_SITE=datadoghq.eu

Troubleshooting

Issue	Check	Fix
Command not found	dogshell installed?	pip install datadog
Authentication failed	Credentials set?	Check ~/.dogrc or env vars
403 Forbidden	App key valid?	Verify app_key permissions
404 Not Found	Resource exists?	Verify ID via UI
Timeout	Network/API slow?	Increase timeout or retry
Invalid tags	Format correct?	Use key:value,key2:value2

Reference

dogshell modules:

• comment: Comment operations
• dashboard: Dashboard management
• dashboard_list: Dashboard list operations
• downtime: Downtime scheduling
• event: Event posting
• host/hosts: Host operations
• metric: Metric posting
• monitor: Monitor management
• screenboard/timeboard: Legacy board types
• search: Search operations
• security_monitoring: Security rules
• service_check: Service check posting
• service_level_objective: SLO management
• tag: Tag management
• wrap: Command wrapping (dogwrap)

Python library: https://github.com/DataDog/datadogpy Datadog API: https://docs.datadoghq.com/api/ dogshell docs: https://docs.datadoghq.com/developers/guide/dogshell/