dogonnet 🐶

A Datadog dashboard templating library using Jsonnet - because good dashboards deserve good tools!

Overview

dogonnet is a Python library that provides a Jsonnet-based templating system for creating Datadog dashboards programmatically. Think of it as grafonnet-lib for Datadog.

Features

• Jsonnet Templates: Write dashboards as code using Jsonnet
• 38 Widget Types: 100% coverage of all Datadog dashboard widgets
• Reusable Components: Pre-built widgets and layouts for common patterns
• Type-Safe: Pydantic models for dashboard definitions
• CLI Tools: Push, fetch, export, and manage dashboards
• Rich Presets: Opinionated defaults for beautiful dashboards
• AI-Friendly: Comprehensive guides for LLM agents to create dashboards from natural language

AI Agent Support 🤖

dogonnet is designed to be easily used by AI agents like Claude, ChatGPT, and others. We provide:

• Agent Guide - Comprehensive guide for AI agents with metric-to-widget mapping, decision trees, and templates
• Cookbook - Copy-paste recipes for common dashboard patterns (Golden Signals, RED metrics, business KPIs)
• Progressive Disclosure - Simple one-liners to complex configurations
• Semantic Documentation - Every widget has usage examples and common patterns

Example AI prompts that work:

• "Create a golden signals dashboard for my payment-api service"
• "Make a business dashboard with revenue, signups, and conversion rate"
• "Show me CPU and memory trends for my infrastructure"

Installation

pip install dogonnet

Quick Start

Create a Dashboard with Jsonnet

local dogonnet = import 'dogonnet/lib/main.libsonnet';

dogonnet.dashboard.new(
  title='My Service Dashboard',
  tags=['service:my-service'],
)
.addRow(
  dogonnet.row.new(title='Key Metrics')
  .addPanel(
    dogonnet.widgets.timeseries(
      title='Request Rate',
      queries=['avg:http.requests{service:my-service}']
    )
  )
  .addPanel(
    dogonnet.widgets.timeseries(
      title='Error Rate',
      queries=['avg:http.errors{service:my-service}']
    )
  )
)

Push to Datadog

# Compile and push
dogonnet push my-dashboard.jsonnet

# Export without pushing
dogonnet compile my-dashboard.jsonnet > output.json

# Fetch existing dashboard
dogonnet fetch my-dashboard-id > existing.json

Library Structure

• dogonnet.lib.widgets - Widget builders (timeseries, query_value, heatmap, etc.)
• dogonnet.lib.layouts - Layout utilities (rows, columns, grid)
• dogonnet.lib.presets - Opinionated presets for common patterns
• dogonnet.client - Datadog API client
• dogonnet.cli - Command-line tools

Documentation

See docs/ for detailed documentation:

For AI Agents & Users:

• Agent Guide - Complete guide for AI agents with templates, patterns, and decision trees
• Cookbook - Copy-paste recipes for common use cases
• Widget Reference - All 38 widgets with examples
• Preset Catalog - Pre-configured common patterns
• Layout Guide - Dashboard organization and positioning

For Developers:

• Design Philosophy - Architecture and principles
• API Version - Datadog API compatibility

Examples

Check out examples/ for sample dashboards:

• examples/basic.jsonnet - Simple dashboard with timeseries widgets
• examples/service-health.jsonnet - Complete service health monitoring
• examples/infrastructure.jsonnet - Infrastructure monitoring (CPU, memory, disk)
• examples/golden-signals.jsonnet - Google SRE Golden Signals (latency, traffic, errors, saturation)

Development

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Format code
ruff format .

License

MIT

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

Inspired by grafonnet-lib for Grafana.