Barkdog

Datadog

Manage Datadog monitors as code with a Ruby DSL

Manages: Datadog monitors
Language: Ruby
Package: barkdog
CLI: barkdog
Config file: Barkfile

The codenize-tools/barkdog repository is archived on GitHub (last activity 2019); the gem still works but no longer tracks changes to Datadog's API.

Barkfile

monitor "Check load avg", :type=>"metric alert" do
  query "avg(last_5m):avg:ddstat.load_avg.1m{host:i-XXXXXXXX} > 1"
  message "@[email protected]"
  tags ["load", "host", "example"]
  options do
    locked false
    new_host_delay 300
    notify_no_data true
    no_data_timeframe 2
    notify_audit true
    silenced({})
  end
end

In short

Barkdog is a Ruby command-line tool that manages Datadog monitors as code. You export existing monitors into a Barkfile, review edits as Git diffs, then apply them idempotently. A dry-run previews every monitor it would create, update, or delete, and safety flags limit deletions.

What is Barkdog?

Barkdog is a command-line tool that manages Datadog monitors as code. Each monitor's query, message, tags, and options like notify_no_data or new_host_delay live in a Ruby file called a Barkfile. Barkdog updates Datadog through its API to match. Credentials are two variables, BARKDOG_API_KEY and BARKDOG_APP_KEY.

Hand-edited monitors cause alerting drift. Thresholds get tweaked during an incident and never reviewed. Duplicate monitors pile up. Nobody can say which alerts are on purpose. Monitors as code fixes this. Every change is a Git diff, and a dry-run reveals anything edited behind the file's back. Barkdog follows the same export, review, apply cycle as the rest of the codenize-tools family.

It suits teams already using Ruby DSL tools who want Datadog alerting under the same discipline. Its sibling Radiosonde does the same for Datadog dashboards, so the two often run together.

Key facts

Manages Datadog monitors (query, message, tags, and options) as code.
Config lives in a file named the Barkfile, kept in Git.
Deletion safety flags like --no-delete protect shared accounts.
A dry-run shows drift, and applies are idempotent.
Radiosonde covers Datadog dashboards; the sunset lbrt did the same for Librato.
The repository is archived (last active 2019); the gem still installs.

Illustration: Datadog monitors managed as code with Barkdog

Getting started

Install and run Barkdog

Install

Install the barkdog gem (Ruby required).

$ gem install barkdog

Export current state

Pull the live Datadog configuration into a Barkfile.

$ barkdog -e -o Barkfile

Dry-run, then apply

Preview the diff, then apply the change for real.

$ barkdog -a --dry-run

Barkdog follows the export, review, apply loop. With BARKDOG_API_KEY and BARKDOG_APP_KEY set, run barkdog -e to pull every monitor into the Barkfile and commit it. That first export doubles as an audit. Expect to find abandoned monitors and incident-era threshold tweaks worth cleaning up.

Changes then go through the file. Edit the Barkfile, run barkdog -a --dry-run to see which monitors would be created, updated, or deleted, and get the diff reviewed. barkdog -a applies the plan idempotently. In shared accounts, --no-delete or --delete-only-tagged limits destructive changes, and --fail-if-empty guards against applying an empty file. A scheduled dry-run in CI makes UI drift visible as soon as it happens.

Pro tip

Turn on --no-delete while you first bring an account under Barkdog. Once you trust the diffs, drop it so obsolete monitors get cleaned up on apply.

Capabilities

What Barkdog can do

Full monitor definitions in the DSL

Each monitor block captures type, query, message, tags, and the options hash (<code>locked</code>, <code>new_host_delay</code>, <code>notify_no_data</code>, and more) exactly as Datadog stores them.

Idempotent apply with dry-run

<code>barkdog -a</code> makes Datadog match the Barkfile and changes nothing on a second run. <code>barkdog -a --dry-run</code> prints the planned creates, updates, and deletes without calling the write API.

Templates for monitor families

Since version 0.1.3, <code>template</code> and <code>include_template</code> stamp out per-host or per-service monitor sets from one definition, with context variables filling in queries and messages.

Deletion safety valves

<code>--no-delete</code> blocks any removal, <code>--delete-only-tagged TAG</code> limits deletions to tagged monitors, and <code>--fail-if-empty</code> aborts if the DSL would wipe the account.

Silence-aware diffs

<code>--ignore-silenced</code> keeps ad-hoc mutes made during incidents from showing up as drift, so operational silences do not fight the codified state.

In practice

When teams reach for Barkdog

Alert thresholds under code review

Threshold changes go through pull requests with the on-call team reviewing. The Git history explains why a monitor fires at 85 percent instead of 90, which helps at the next incident retro.

Per-host or per-service monitor sets

Define a template with the standard CPU, load, and disk monitors, then <code>include_template</code> it for each host or service. Every new service gets identical coverage in a three-line diff.

Detecting dashboard drift

Run <code>barkdog -a --dry-run</code> on a schedule. Any monitor edited directly in the Datadog UI shows up in the plan, so the team can codify the change or revert it on purpose.

Pruning a noisy account

Export everything, delete the obsolete monitors from the Barkfile, and apply with <code>--delete-only-tagged</code> so the cleanup can only touch monitors tagged for management.

FAQ

Barkdog questions, answered

Is Barkdog still maintained?

No. The barkdog repository is archived on GitHub, last active in 2019. The gem still installs, but Datadog's API keeps changing, so verify behavior against your account. For a maintained path, the Terraform Datadog provider covers monitors as code.

Will Barkdog delete monitors missing from the Barkfile?

By default, yes. It makes the account match the DSL. Use --no-delete to forbid deletions, --delete-only-tagged TAG to fence them to tagged monitors, and always inspect barkdog -a --dry-run output before applying.

How does Barkdog authenticate with Datadog?

Through a Datadog API key and application key, set via BARKDOG_API_KEY and BARKDOG_APP_KEY or the --api-key and --app-key flags. --datadog-timeout adjusts the API timeout for large accounts.

Can Barkdog manage dashboards too?

No, Barkdog only handles monitors. Its sibling Radiosonde was built for Datadog dashboards, so the two were typically used together when codifying a Datadog account.

What happens to monitors silenced during an incident?

Silences would normally show up as drift against the Barkfile. The --ignore-silenced flag leaves silenced state out of the comparison, so temporary mutes survive an apply without being codified.