@bancame/datadog

A TypeScript library and CLI tool for automated Datadog agent installation and monitor management on production services.

🚀 Quick Start - Deploy to Production Service

The fastest way to get Datadog monitoring running on your service:

1. One-Command Setup (Recommended)

Install agent + create essential system monitors in one command:

npx @bancame/datadog setup \
  --apiKey YOUR_DD_API_KEY \
  --appKey YOUR_DD_APP_KEY \
  --tags env:production,service:your-service-name,team:your-team

This will:

• ✅ Install Datadog agent with proper configuration
• ✅ Create 3 essential monitors: CPU > 80%, Memory > 85%, Disk > 90%
• ✅ Apply your custom tags to everything
• ✅ Start monitoring immediately

2. Manual Steps (if you prefer control)

# Step 1: Install agent only
npx @bancame/datadog install --apiKey YOUR_DD_API_KEY --tags env:production,service:web

# Step 2: Create custom monitors
npx @bancame/datadog monitor \
  --apiKey YOUR_DD_API_KEY \
  --appKey YOUR_DD_APP_KEY \
  --name "High CPU Alert" \
  --query "avg(last_5m):avg:system.cpu.user{service:web} > 80" \
  --critical 80 \
  --warning 70

📋 What Gets Installed

Datadog Agent

• Auto-detects your OS (Ubuntu, CentOS, Alpine, SUSE)
• Downloads correct installer for your platform
• Configures with your API key and custom tags
• Starts monitoring system metrics immediately

Essential Monitors

• 🔥 High CPU Usage: Alerts when CPU > 80% (warning at 70%)
• 💾 High Memory Usage: Alerts when Memory > 85% (warning at 75%)
• 💿 High Disk Usage: Alerts when Disk > 90% (warning at 80%)

All monitors include your custom tags for easy filtering in Datadog dashboard.

🏭 Production Deployment Examples

Docker/Kubernetes

# In your Dockerfile or deployment script
RUN npx @bancame/datadog setup \
    --apiKey $DD_API_KEY \
    --appKey $DD_APP_KEY \
    --tags env:production,service:api,version:v1.2.0

CI/CD Pipeline

# In your deployment pipeline
- name: Setup Datadog Monitoring
  run: |
    npx @bancame/datadog setup \
      --apiKey ${{ secrets.DD_API_KEY }} \
      --appKey ${{ secrets.DD_APP_KEY }} \
      --tags env:${{ env.ENVIRONMENT }},service:${{ env.SERVICE_NAME }}

Terraform/Infrastructure

# As a provisioning step
provisioner "remote-exec" {
  inline = [
    "npx @bancame/datadog setup --apiKey ${var.dd_api_key} --appKey ${var.dd_app_key} --tags env:${var.environment},service:${var.service_name}"
  ]
}

Installation

npm install @bancame/datadog

📚 Library Usage (Advanced)

For custom monitoring logic in your application code:

import { installAgent, createMonitor } from '@bancame/datadog';

async function setupCustomMonitoring() {
  // Install agent programmatically
  await installAgent({
    apiKey: process.env.DD_API_KEY!,
    tags: ['env:production', 'service:my-api'],
  });

  // Create application-specific monitor
  const monitor = await createMonitor(
    process.env.DD_API_KEY!,
    process.env.DD_APP_KEY!,
    {
      name: 'API Response Time Alert',
      query: 'avg(last_5m):avg:http.response_time{service:my-api} > 500',
      thresholds: { critical: 500, warning: 300 },
      tags: ['env:production', 'type:performance'],
    },
  );

  console.log(`Monitor created: ${monitor.id}`);
}

🔧 CLI Commands Reference

setup - Complete Setup (Recommended)

Installs agent + creates basic system monitors in one step.

npx @bancame/datadog setup [options]

Options:

• --apiKey (required) - Your Datadog API key
• --appKey (required) - Your Datadog Application key
• --tags (optional) - Comma-separated tags: env:prod,service:api
• --version (optional) - Agent version (default: "7")
• --site (optional) - Datadog site (default: "datadoghq.com")

install - Agent Only

Installs Datadog agent without creating monitors.

npx @bancame/datadog install --apiKey YOUR_API_KEY --tags env:prod,service:web

monitor - Create Custom Monitor

Creates a single custom monitor.

npx @bancame/datadog monitor \
  --apiKey YOUR_API_KEY \
  --appKey YOUR_APP_KEY \
  --name "Custom Alert" \
  --query "avg(last_5m):avg:custom.metric{*} > 100" \
  --critical 100 \
  --warning 80

🎯 Best Practices

Production Tagging Strategy

Always include these tags for better organization:

--tags env:production,service:your-service,team:your-team,version:v1.0.0

Environment-Specific Setup

# Production
npx @bancame/datadog setup --tags env:production,service:api,region:us-east-1

# Staging
npx @bancame/datadog setup --tags env:staging,service:api,region:us-west-1

# Development
npx @bancame/datadog setup --tags env:development,service:api,region:local

🔒 Security

• Never commit API keys to version control
• Use environment variables or secret management systems
• Rotate keys regularly following your security policies
• Apply least-privilege principle to API/App key permissions

🆘 Troubleshooting

Agent Installation Issues

# Check if agent is running
sudo systemctl status datadog-agent

# View agent logs
sudo journalctl -u datadog-agent -f

# Test connectivity
sudo datadog-agent status

Monitor Creation Issues

• ✅ Verify your API and App keys have correct permissions
• ✅ Check Datadog site parameter matches your account region
• ✅ Ensure query syntax follows Datadog query language

📖 API Reference

Core Functions

installAgent(options) - Install Datadog agent

interface InstallAgentOptions {
  apiKey: string;
  tags?: string[];
  version?: string;
}

createMonitor(apiKey, appKey, options, site?) - Create monitor

interface CreateMonitorOptions {
  name: string;
  query: string;
  thresholds: { critical: number; warning?: number };
  tags?: string[];
}

Classes

AgentInstaller - Advanced agent installation with OS detection MonitorManager - Full CRUD operations for monitors

🛠️ Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Coverage
npm run test:coverage

Requirements: Node.js 16+, TypeScript 5+

Made with ❤️ by the Bancame team