Configure Monitoring Objects

The installation package includes a default agent.yaml. If you only need to onboard the host object, keep the default configuration first. After the host appears in the console, add MySQL, Redis, PostgreSQL, and other objects as needed.

Basic configuration example

The following configuration is suitable for first-time onboarding:

locator_mappings: {}

host:
  sample_interval: 2s

  disk:
    extra_exclude_mount_points: []
    extra_exclude_fs_types: []
    statfs_timeout: 1s
    top_n: 20

  disk_io:
    top_n: 5
    skip_loop: true
    skip_partitions: true
    dm_exclude_patterns:
      - "docker-*"
      - "*-pool"

  network_io:
    top_n: 5
    exclude_patterns:
      - "lo"
      - "veth*"
      - "docker*"
      - "br-*"
      - "virbr*"
      - "flannel*"
      - "cali*"
      - "cni*"
      - "tun*"
      - "tap*"

  top_processes:
    default_top_n: 10
    max_top_n: 50
    include_cmdline: false

  shell_exec:
    enabled: true
    pipeline_max_segments: 3
    default_max_lines: 200
    cat_max_file_size: 20971520
    user_allow_list: []

tool_policy:
  disabled_tools: []

mysql: []
redis: []
redis_sentinel: []
postgres: []
mongodb: []
mongodb_mongos: []
kafka: []
elasticsearch: []

script_tool:
  enabled: false
  dir: /opt/monit-agent/tools.d

locator_mappings

locator_mappings controls the object address displayed in the console. It is commonly used for non-host objects such as MySQL. For example, the Agent connects to MySQL through a local address:

mysql:
  - targets:
      - "localhost:3306"

If you want the console to display a more recognizable database address, configure:

locator_mappings:
  "localhost:3306": "db-prod-01.example.com:3306"

Recommendations:

If MySQL, Redis, PostgreSQL, MongoDB, or similar services are configured with localhost or 127.0.0.1, also configure locator_mappings.
The mapped address should be a stable IP, DNS name, or host:port.
Do not map an address to localhost or 127.0.0.1.
Kafka and Elasticsearch are cluster-level objects and do not use locator_mappings. Kafka uses cluster_name as the identifier. Elasticsearch automatically obtains cluster_name from the cluster.

host

host controls the collection behavior for host diagnostics. It usually does not need to be changed for first-time onboarding.

Config	Recommended value	Description
`sample_interval`	`2s` or `3s`	Sampling interval for CPU, disk I/O, network I/O, and similar metrics.
`disk.statfs_timeout`	`1s`	Prevents abnormal mount points from slowing down diagnostics.
`disk.top_n`	`20`	Controls the number of file systems returned.
`disk_io.top_n`	`5`	Controls the number of disk I/O devices returned.
`network_io.top_n`	`5`	Controls the number of network interfaces returned.
`top_processes.default_top_n`	`10`	Default number of processes returned.
`top_processes.include_cmdline`	`false`	Does not return the full command line by default, reducing the risk of exposing passwords, tokens, or connection strings.

shell_exec

shell_exec controls whether the Agent allows controlled host diagnostic commands.

host:
  shell_exec:
    enabled: true
    pipeline_max_segments: 3
    default_max_lines: 200
    cat_max_file_size: 20971520
    user_allow_list: []

Recommendations:

Keep enabled: true when AI-SRE needs live host diagnostics. Only controlled shell commands can be executed.
If some shell commands are blocked by built-in guardrails, add them manually to user_allow_list only after confirming that they are safe, read-only, and do not expose sensitive information.

To urgently disable a tool, use tool_policy.disabled_tools:

tool_policy:
  disabled_tools:
    - shell.exec

MySQL

To diagnose MySQL, add instance configuration under mysql:. Use a read-only MySQL account, and preferably store the password in a separate credential file:

locator_mappings:
  "localhost:3306": "db-prod-01.example.com:3306"

mysql:
  - targets:
      - "localhost:3306"
    connection:
      charset: utf8mb4
      timeout: 3s
      max_open_conns: 8
      max_idle_conns: 2
    overview:
      sample_interval: 2s
    query:
      enabled: false
      default_max_rows: 200
      statement_timeout: 6s
    credential:
      source: env_file
      path: /etc/monit-agent/mysql.env
      username_key: MYSQL_USER
      password_key: MYSQL_PASSWORD

Credential file example:

MYSQL_USER=monit_ro
MYSQL_PASSWORD=<MYSQL_PASSWORD>

Config	Recommendation
`targets`	Explicitly use `host:port`. If `localhost:3306` is used, configure `locator_mappings`.
`connection.timeout`	Recommended: `3s`.
`overview.sample_interval`	Recommended: `2s` or `3s`.
`query.enabled`	Default: `false`. Enable only after confirming the account is read-only.
`query.default_max_rows`	Recommended: `200`.
`query.statement_timeout`	Recommended: `6s`.
`credential.source`	Recommended: `env_file`.

If mysql.query is enabled, always use a read-only account. This tool executes controlled read-only SQL and should not use a privileged account.

Redis

To diagnose Redis, add instance configuration under redis:.

Tool	Function	Default status
`redis.overview`	Collects INFO ALL twice, calculates the diff, and returns key metrics such as memory, hit rate, connections, and QPS.	Enabled
`redis.slowlog`	Reads SLOWLOG GET and returns recent slow query records.	Enabled
`redis.command`	Executes controlled read-only Redis commands with an allowlist policy.	Disabled by default

locator_mappings:
  "localhost:6379": "redis-prod-01.example.com:6379"

redis:
  - targets:
      - "localhost:6379"
    connection:
      database: 0
      timeout: 3s
    overview:
      sample_interval: 2s
    command:
      enabled: false
    credential:
      source: env_file
      path: /etc/monit-agent/redis.env
      password_key: REDIS_PASSWORD

REDIS_PASSWORD=<REDIS_PASSWORD>

Config	Recommendation
`targets`	Explicitly use `host:port`. If `localhost:6379` is used, configure `locator_mappings`.
`connection.database`	Default: `0`.
`connection.timeout`	Recommended: `3s`.
`overview.sample_interval`	Recommended: `2s` or `3s`, range `[1s, 5s]`.
`command.enabled`	Default: `false`. Enable only when controlled read-only commands are needed.
`credential`	Redis versions earlier than 6 only use password authentication, so `username` can be omitted. Redis 6+ ACL mode can configure both `username_key` and `password_key`.

After redis.command is enabled, only allowlisted read-only commands such as CONFIG GET, CLIENT LIST, MEMORY USAGE, and LATENCY HISTORY are allowed. Write commands are rejected.

Redis Sentinel

To diagnose a Redis Sentinel high availability cluster, add Sentinel process configuration under redis_sentinel:. redis_sentinel and redis are different object types. They point to Sentinel processes and Redis data nodes respectively.

Tool	Function	Default status
`redis_sentinel.overview`	Gets Sentinel INFO, including the monitored master list and status.	Enabled
`redis_sentinel.topology`	Gets topology information for all monitored masters, including master, replica, and sentinel node lists.	Enabled

redis_sentinel:
  - targets:
      - "10.1.2.10:26379"
      - "10.1.2.11:26379"
      - "10.1.2.12:26379"
    connection:
      timeout: 3s
    credential:
      source: env
      password_key: REDIS_SENTINEL_PASSWORD

Config	Recommendation
`targets`	Sentinel default port is `26379`. Explicitly use `host:port`.
`connection.timeout`	Recommended: `3s`.
`credential`	Sentinel usually uses password-only authentication without username. If Sentinel does not enable `requirepass`, credential can be omitted.

PostgreSQL

To diagnose PostgreSQL, add instance configuration under postgres:.

Tool	Function	Default status
`postgres.overview`	Collects key statistics views twice, calculates the diff, and returns connection count, transaction throughput, cache hit rate, replication lag, and other key metrics.	Enabled
`postgres.activity`	Queries `pg_stat_activity` and returns current active and long-running queries.	Enabled
`postgres.query`	Executes controlled read-only SQL queries such as SELECT, WITH, and EXPLAIN.	Disabled by default

locator_mappings:
  "localhost:5432": "pg-prod-01.example.com:5432"

postgres:
  - targets:
      - "localhost:5432"
    connection:
      database: postgres
      sslmode: prefer
      timeout: 3s
      max_open_conns: 8
      max_idle_conns: 2
    overview:
      sample_interval: 2s
    activity:
      min_query_age: 1s
      top_n: 10
    query:
      enabled: false
      default_max_rows: 200
      statement_timeout: 6s
    credential:
      source: env_file
      path: /etc/monit-agent/postgres.env
      username_key: POSTGRES_USER
      password_key: POSTGRES_PASSWORD

POSTGRES_USER=monit_ro
POSTGRES_PASSWORD=<POSTGRES_PASSWORD>

Config	Recommendation
`targets`	Explicitly use `host:port`. The default port is `5432`. If `localhost:5432` is used, configure `locator_mappings`.
`connection.database`	Required. PostgreSQL has no implicit default database. A common value is `postgres`.
`connection.sslmode`	Default: `prefer`. Valid values: `disable`, `allow`, `prefer`, `require`, `verify-ca`, `verify-full`.
`connection.timeout`	Recommended: `3s`.
`overview.sample_interval`	Recommended: `2s` or `3s`, range `[1s, 5s]`.
`activity.min_query_age`	Returns only queries running longer than this threshold. Default: `1s`.
`activity.top_n`	Default: `5`, maximum `20`.
`query.enabled`	Default: `false`. Enable only after confirming the account is read-only.
`query.default_max_rows`	Recommended: `200`, maximum `10000`.
`query.statement_timeout`	Recommended: `6s`, range `[1s, 7s]`.
`credential`	Required. PostgreSQL wire protocol does not support anonymous connections. Grant the `pg_monitor` role to get full `pg_stat_activity` visibility.

If postgres.query is enabled, always use a read-only account.

MongoDB

To diagnose MongoDB (mongod or replica set members), add instance configuration under mongodb:. Only the host:port format is accepted. mongodb+srv:// URIs are not supported.

Tool	Function	Default status
`mongodb.overview`	Collects serverStatus twice, calculates the diff, and returns connection count, operation throughput, memory, replication lag, and other key metrics.	Enabled
`mongodb.current_ops`	Queries currentOp and returns currently running operations.	Enabled
`mongodb.command`	Executes controlled read-only management commands with an allowlist policy.	Disabled by default

mongodb:
  - targets:
      - "10.1.3.10:27017"
      - "10.1.3.11:27017"
    connection:
      database: admin
      timeout: 3s
      # tls:
      #   enabled: true
      #   ca_file: /etc/ssl/mongo-ca.pem
      #   allow_invalid_hostnames: false
    overview:
      sample_interval: 3s
    command:
      enabled: false
    credential:
      source: env_file
      path: /etc/monit-agent/mongodb.env
      username_key: MONGODB_USER
      password_key: MONGODB_PASSWORD

MONGODB_USER=monit_ro
MONGODB_PASSWORD=<MONGODB_PASSWORD>

Config	Recommendation
`targets`	Explicitly use `host:port`. Each target corresponds to an independent mongod instance.
`connection.database`	SCRAM authentication authSource database. Default: `admin`.
`connection.timeout`	Recommended: `3s`.
`connection.tls`	Optional. Set `enabled: true` when TLS is enabled. Specify `ca_file` when using a self-signed CA.
`overview.sample_interval`	Recommended: `3s`, range `[1s, 5s]`.
`command.enabled`	Default: `false`. Enable only when controlled read-only management commands are needed.
`credential`	If MongoDB authentication is disabled in development or test environments, credential can be omitted. Configure a read-only account in production.

After mongodb.command is enabled, only allowlisted read-only management commands such as dbStats, collStats, serverStatus, and replSetGetStatus are allowed. Write commands and dangerous commands are rejected.

MongoDB Mongos

To diagnose MongoDB sharded cluster routing processes (mongos), add configuration under mongodb_mongos:. mongodb_mongos and mongodb are different object types. They point to mongos routing processes and mongod data nodes respectively.

Tool	Function	Default status
`mongodb_mongos.overview`	Collects mongos serverStatus and returns connection count, operation throughput, and other key metrics.	Enabled
`mongodb_mongos.shard_distribution`	Gets sharded cluster topology and data distribution information.	Enabled

mongodb_mongos:
  - targets:
      - "10.1.3.20:27017"
      - "10.1.3.21:27017"
    connection:
      database: admin
      timeout: 3s
    overview:
      sample_interval: 3s
    credential:
      source: env_file
      path: /etc/monit-agent/mongodb.env
      username_key: MONGODB_USER
      password_key: MONGODB_PASSWORD

Config	Recommendation
`targets`	mongos routing process address. Explicitly use `host:port`.
`connection.database`	SCRAM authentication authSource database. Default: `admin`.
`connection.timeout`	Recommended: `3s`.
`overview.sample_interval`	Recommended: `3s`, range `[1s, 5s]`.
`credential`	Usually shares the same credential file as `mongodb`.

Kafka

To diagnose a Kafka cluster, add configuration under kafka:. Kafka is a cluster-level object. One kafka configuration block represents one logical cluster, and bootstrap_brokers are connection entry points rather than independent targets.

Tool	Function	Default status
`kafka.overview`	Gets the broker list, controller information, and topic overview.	Enabled
`kafka.consumer_lag`	Gets consumer group lag.	Enabled
`kafka.topic_detail`	Gets partition details for a specified topic, including replica distribution, ISR, and leader.	Enabled
`kafka.group_detail`	Gets details for a specified consumer group, including member assignment and offsets.	Enabled

kafka:
  - cluster_name: "prod-order-kafka"
    bootstrap_brokers:
      - "10.1.4.10:9092"
      - "10.1.4.11:9092"
      - "10.1.4.12:9092"
    connection:
      timeout: 5s
      sasl_mechanism: none
      # tls:
      #   enabled: true
      #   ca_file: /etc/ssl/kafka-ca.pem
      #   cert_file: /etc/ssl/kafka-client.pem
      #   key_file: /etc/ssl/kafka-client-key.pem
    consumer_lag:
      default_top_n: 10
    # credential:
    #   source: env_file
    #   path: /etc/monit-agent/kafka.env
    #   username_key: KAFKA_USER
    #   password_key: KAFKA_PASSWORD

Config	Recommendation
`cluster_name`	Required. Used as the object identifier in the console. Only lowercase letters, digits, `.`, `-`, and `_` are allowed. Length: 2-128.
`bootstrap_brokers`	At least one Broker address in `host:port` format. Configure multiple addresses for better availability.
`connection.timeout`	Recommended: `5s`.
`connection.sasl_mechanism`	Default: `none`. Supported values: `none`, `plain`, `scram-sha-256`, `scram-sha-512`.
`connection.tls`	Optional. Set `enabled: true` when TLS is enabled. mTLS requires both `cert_file` and `key_file`.
`consumer_lag.default_top_n`	Default: `10`, range `[1, 50]`.
`credential`	Required only when `sasl_mechanism` is not `none`.

Kafka does not use locator_mappings. cluster_name is directly used as the object address in the console.

Elasticsearch

To diagnose an Elasticsearch cluster, add configuration under elasticsearch:. Elasticsearch is a cluster-level object. cluster_name does not need to be declared in the configuration. The Agent automatically obtains it through GET _cluster/health during startup or reload. If the cluster is unreachable, the target is skipped until the next reload.

Tool	Function	Default status
`elasticsearch.overview`	Gets cluster health, node count, index count, shard allocation, and other global cluster information.	Enabled
`elasticsearch.node_stats`	Gets detailed node metrics such as JVM, OS, thread pool, and transport.	Enabled
`elasticsearch.index_stats`	Gets index-level statistics such as document count, storage size, and read/write throughput.	Enabled
`elasticsearch.shard_allocation`	Gets cluster shard allocation details to diagnose uneven shard distribution or unassigned shards.	Enabled
`elasticsearch.cat`	Executes controlled `_cat` API queries with an allowlist policy.	Disabled by default

elasticsearch:
  - targets:
      - "https://es-node1.example.com:9200"
      - "https://es-node2.example.com:9200"
      - "https://es-node3.example.com:9200"
    connection:
      timeout: 5s
      tls:
        ca_cert: /etc/ssl/es-ca.pem
        skip_verify: false
    cat:
      enabled: false
    credential:
      source: env_file
      path: /etc/monit-agent/elasticsearch.env
      username_key: ES_USER
      password_key: ES_PASSWORD

ES_USER=monit_ro
ES_PASSWORD=<ES_PASSWORD>

Config	Recommendation
`targets`	Full URL format, including protocol and port, such as `https://es-node:9200`. `http://` and `https://` are supported. Configure multiple nodes for better availability.
`connection.timeout`	Recommended: `5s`.
`connection.tls.ca_cert`	Specify the CA certificate path when using a self-signed CA. It must be an absolute path.
`connection.tls.skip_verify`	Default: `false`. Do not enable it in production.
`cat.enabled`	Default: `false`. When enabled, allowlisted `_cat` API queries can be executed.
`credential`	If Elasticsearch security authentication is disabled, credential can be omitted. Configure a read-only account in production.

Elasticsearch does not use locator_mappings. The Agent automatically obtains cluster_name from the cluster and uses it as the object address in the console.

script_tool

script_tool is used to add custom script tools. Most users can keep it disabled:

script_tool:
  enabled: false
  dir: /opt/monit-agent/tools.d

Enable it only when you need custom diagnostic capabilities and can confirm that the script source and directory permissions are controlled.

​Basic configuration example

​locator_mappings

​host

​shell_exec

​MySQL

​Redis

​Redis Sentinel

​PostgreSQL

​MongoDB

​MongoDB Mongos

​Kafka

​Elasticsearch

​script_tool