Skip to main content

Agent Quickstart

Overview​

Atlas Agent supports configuring schema monitoring declaratively using HCL (HashiCorp Configuration Language) files. This "as code" approach allows you to version control your monitoring configuration, manage multiple database instances consistently, and automate agent deployments.

With monitoring configuration as code, you can:

  • Version control your monitoring configuration alongside your application code and avoid "ClickOps" mistakes
  • Automate agent deployments with consistent configurations
  • Manage multiple database instances and monitoring scopes declaratively
  • Override default monitoring settings for specific databases or schemas
  • Discover RDS and GCP instances automatically using data sources

Prerequisites​

  • An Atlas Cloud account
  • A bot token for the agent
  • Access to your database instances

Basic Configuration​

A basic Atlas Agent configuration file (agent.hcl) consists of:

  1. An agent block with authentication and logging settings
  2. One or more instance blocks defining database connections
  3. monitor or default_monitor blocks specifying what to monitor

Here's a minimal example:

agent.hcl
agent {
  token = getenv("ATLAS_TOKEN")
}

instance "production" {
  driver = "postgres"

  connection {
    host     = "prod-db.example.com"
    port     = 5432
    user     = "atlas_monitor"
    database = "postgres"

    auth {
      env_var "DATABASE_PASSWORD" {}
    }
  }

  default_monitor "all" {
    snapshot_interval = "1h"

    statistics {
      enabled = true
    }
  }
}

Configuration Structure​

Agent Block​

The agent block configures the agent's connection to Atlas Cloud and optional settings:

agent {
  token = getenv("ATLAS_TOKEN")  # Required: Atlas Cloud token

  log {
    level  = "INFO"  # DEBUG, INFO, WARN, ERROR
    format = "TEXT"  # TEXT or JSON
  }

  metrics {
    enabled = true
    port    = 8081
  }
}

Instance Block​

Each instance block defines a database instance to monitor. The optional metadata attribute accepts a map of key-value pairs (e.g. region, engine, cluster info). When using RDS Discovery or GCP Discovery, each discovered instance exposes a metadata field that you can pass through to this attribute.

instance "my-database" {
  name   = "Production Database"  # Human-friendly name
  slug   = "prod-db"              # Unique identifier
  driver = "postgres"             # Database driver

  tags = {
    environment = "production"
    team        = "backend"
  }

  # Optional: custom metadata (e.g. from discovery; see RDS and GCP Discovery sections)
  metadata = {
    region = "us-east-1"
    source = "rds"
  }

  connection {
    host     = "db.example.com"
    port     = 5432
    user     = "atlas_monitor"
    database = "postgres"

    auth {
      # Authentication method (see below)
    }
  }

  # Monitoring configuration (see below)
}

Connection Authentication​

Atlas Agent supports multiple authentication methods for database connections:

Read the database password from an environment variable:

connection {
  auth {
    env_var "DATABASE_PASSWORD" {}
  }
}

Custom Query Parameters​

Pass custom query parameters to the database connection.

For example, you can pass the sslmode parameter to the database connection to enable or disable SSL:

atlas-agent.hcl
instance "my-database" {
  name   = "Production Database"
  slug   = "prod-db"
  driver = "postgres"

  connection {
    host     = "db.example.com"
    port     = 5432
    user     = "atlas_monitor"
    database = "postgres"

    auth {
      env_var "DATABASE_PASSWORD" {}
    }
    query = {
      sslmode = "disable"
    }
  }
}

Monitoring Configuration​

Each instance must have at least one monitoring configuration using either default_monitor or monitor blocks.

Default Monitor​

A default_monitor block applies monitoring settings to all databases and schemas in the instance:

instance "production" {
  # ... connection configuration ...

  default_monitor "all" {
    snapshot_interval = "1h"  # How often to take snapshots (minimum: 1m)

    # Monitor specific schemas
    schemas = ["public", "app"]

    # Or use include/exclude patterns
    include = ["app_*"]
    exclude = ["temp_*", "test_*"]

    # Exclude entire databases
    exclude_databases = ["postgres", "rdsadmin"]

    # Initial database to connect to (for multi-database instances)
    initial_database = "postgres"

    statistics {
      enabled = true  # Collect table statistics
    }
  }
}

Specific Monitor Blocks​

Use monitor blocks to override default settings for specific databases or schemas:

instance "production" {
  # ... connection configuration ...

  default_monitor "all" {
    snapshot_interval = "1h"
    statistics {
      enabled = true
    }
  }

  # Override for a specific database
  monitor "analytics" {
    database          = "analytics_db"
    snapshot_interval = "6h"  # Less frequent snapshots

    statistics {
      enabled = false  # Disable statistics for this database
    }
  }

  # Monitor specific schemas in another database
  monitor "app-schemas" {
    database = "app_db"
    schemas  = ["users", "orders", "payments"]
  }
}

Running the Agent using Docker​

docker run -d \
  --name atlas-agent \
  -e ATLAS_TOKEN="your-token" \
  -e DATABASE_PASSWORD="your-password" \
  -v $(pwd)/agent.hcl:/etc/atlas-agent/agent.hcl \
  arigaio/atlas-agent \
  --config /etc/atlas-agent/agent.hcl

Next Steps​