MariaDB Agent Manager Configuration File Reference

Overview

The MariaDB Agent Manager configuration file defines the on-premises database infrastructure and all required parameters.

Path

When running MariaDB Agent Manager, the path to the configuration file can be specified using the -c flag or by setting the REMOTE_AGENT_CONFIG environment variable.

Consistency

The MariaDB Agent Manager configuration file must be consistent on all servers. Each host can have an identical copy of the configuration file or all hosts could share a single copy of the file via shared storage.

Format

The MariaDB Agent Manager configuration file uses the JSON format.

Sections

The MariaDB Agent Manager configuration file consists of the following sections:

Section

Description

"datacenter"

The set of parameters clusters and servers in your data center and the corresponding exporters that MariaDB Agent Manager should use for each.

"prometheus"

Prometheus-related settings.

Configuration Attributes for "datacenter" Section

The "datacenter" section contains a nested database_services section with an array defining each database service within the data center.

The following configuration attributes are currently supported in the "datacenter" section:

Attribute Key Name

Description

Type

Recommended Value

"name"

  • Provide a name for the data center, such as "Production Data Center (Western US)"

  • The provided name is not currently shown on the monitoring dashboard.

String

Any

"location"

  • Provide a geographical location for the data center, such as "Portland, OR, USA"

  • The provided name is shown on the monitoring dashboard.

String

Any

"skysql_region"

  • Provide the SkySQL region to store the monitoring data for the data center.

  • Defaults to "us-central1"

  • Also supported: "eu-west1", "asia-southeast1"

  • For additional information, see "Region".

String

Any

Configuration Attributes for "datacenter.database_services[]" Section

The "datacenter.database_services[]" section contains a nested servers section with an array defining each server within the database service.

The following configuration attributes are currently supported in the "datacenter.database_services[]" section for each database service defined:

Attribute Key Name

Description

Type

Recommended Value

"type"

  • Specify the type of database service

  • For a standalone MariaDB Enterprise Server node, specify "mariadb" or "standalone"

  • For multiple MariaDB Enterprise Server nodes connected using replication, specify "primaryreplica" or "replicated"

  • For MariaDB Xpand, specify "xpand" or "distributed"

  • For MariaDB Enterprise ColumnStore, specify "columnstore"

  • For MariaDB Enterprise Cluster, specify "galera" or "cluster"

String

See description

"name"

  • Provide a name for the database service, such as "ProdDatabaseClusterUSWest"

String

Any

Configuration Attributes for "datacenter.database_services[].servers[]" Section

The "datacenter.database_services[].servers[]" section contains a nested exporters section that configures the exporters at the server level.

The following configuration attributes are currently supported in the "datacenter.database_services[].servers[]" section for each server defined in the database service:

Attribute Key Name

Description

Type

Recommended Value

"name"

  • Provide a name for the server, such as "prod-mdb1"

  • The provided name is shown on the monitoring dashboard and panels.

  • If a service configuration includes MaxScale, this attribute must be set to the same name that MaxScale uses to identify the node.

  • For Enterprise ColumnStore nodes, this attribute must start with the 'cs_node' prefix. If the service also uses MaxScale, the cs_node prefix also applies to the name that MaxScale uses to identify the node.

String

Any

"type"

  • Specify the type of server

  • For a MariaDB Enterprise Server node, specify "server"

  • For a MariaDB Xpand node, specify "xpand-backend"

  • For a MariaDB MaxScale node, specify "maxscale"

String

See description

"hostname"

  • For most nodes, this attribute can be set to the hostname (as returned by the command hostname on Linux) or IP address, such as "prod-mdb1.example.com" or "192.0.2.1"

  • For Xpand nodes, this attribute must be set to the hostname, not the IP address.

String

Any

"logging"

  • Configures the log processing behavior with Fluent Bit

  • Value is a JSON object with 2 attributes: "mode" and "path"

  • Set "mode" to "enabled" or "disabled". By default, this is set to "enabled"

  • Set "path" to an array of log paths. By default, this is set to ["/var/log/mysql/error.log"]

  • For additional information, see "mariadb_agent_manager fluent-bit"

  • This attribute is optional

Object

See description

"socket"

  • Provide a path to the UNIX domain socket file

  • If this attribute is specified and the credentials file does not specify the user name and password, authentication will be performed with the unix_socket authentication plugin.

  • This attribute is supported for MariaDB Enterprise Server, MariaDB Enterprise ColumnStore, and MariaDB Enterprise Cluster (Powered by Galera).

  • This attribute is optional.

  • When this attribute is not specified, the connection to the database uses TCP/IP.

String

Any

"tls"

  • Set to "enabled" or "disabled".

  • For additional information, see "Configure TLS"

  • This attribute is optional

String

See description

Configuration Attributes for "datacenter.database_services[].servers[].exporters" Sections

The "exporters" section is an optional section that can be added to the "datacenter.database_services[].servers[] section. The section defines configuration attributes for each exporter for the server:

Configuration Attributes for "mariadb_exporter" Sections

The "mariadb_exporter" section is optional. This section can be used to override default values.

The "mariadb_exporter" configuration attributes can appear in the "datacenter.database_services[].servers[].exporters" section:

Attribute Key Name

Description

Type

Recommended Value

"db_host"

  • Set to the host name used to connect to MariaDB Enterprise Server or MariaDB Xpand

  • This attribute is optional

String

"localhost"

"db_port"

  • Set to the port used to connect to MariaDB Enterprise Server or MariaDB Xpand

  • For MariaDB Enterprise Server, the port can be determined by checking the port system variable

  • For MariaDB Xpand, the port can be determined by checking the MYSQL_PORT configuration option

Integer

3306

"port"

  • Set to the port that mariadb_exporter should listen on

Integer

9104

"route"

  • Set to the endpoint that should be used to route requests to mariadb_exporter

String

"/metrics"

Configuration Attributes for "maxscale_exporter" Sections

The "maxscale_exporter" section is optional. This section can be used to override default values.

The "maxscale_exporter" configuration attributes can appear in the "datacenter.database_services[].servers[].exporters" section:

Attribute Key Name

Description

Type

Recommended Value

"mxs_host"

String

http://localhost

"mxs_port"

  • Set to the port used to connect to MariaDB MaxScale's REST API

  • The port can be determined by checking the admin_port parameter

Integer

8989

"port"

  • Set to the port that maxscale_exporter should listen on

Integer

9105

"route"

  • Set to the endpoint that should be used to route requests to maxscale_exporter

String

"/metrics"

Configuration Attributes for "node_exporter" Sections

The "node_exporter" section is optional. This section can be used to override default values.

The "node_exporter" configuration attributes can appear in the "datacenter.database_services[].servers[].exporters" section:

Attribute Key Name

Description

Type

Recommended Value

"port"

  • Set to the port that node-exporter should listen on

Integer

9100

"route"

  • Set to the endpoint that should be used to route requests to node-exporter

String

"/metrics"

Configuration Attributes for "skysql_uni_exporter" Sections

The "skysql_uni_exporter" configuration attributes can appear in the "datacenter.database_services[].servers[].exporters" section:

Attribute Key Name

Description

Type

Recommended Value

"debug"

  • Set to "0" to disable debug mode or "1" to enable debug mode

  • By default, "0" is set

String

"0" or "1"

"resync_after_seconds"

  • Set to the time period between re-syncing in seconds

Integer

600

"scrape_frequency_seconds"

  • Set to the time period between scrape operations in seconds

Integer

60

Configuration Attributes for "prometheus" Section

The "prometheus" section is optional. This section can be used to override default values.

The following configuration attributes are currently supported in the "prometheus" section:

Attribute Key Name

Description

Type

Recommended Value

"scrape_interval"

  • This attribute is optional

Integer

15

"evaluation_interval"

  • This attribute is optional

Integer

15

"scrape_timeout"

  • This attribute is optional

Integer

10

"customer_config_file"

  • Specify the absolute path to a Prometheus configuration file that references custom exporters

  • This attribute is optional

String

See description

Configuration Wizard

A configuration file can be created using the configuration wizard by executing the mariadb_agent_manager init sub-command.

$ mariadb_agent_manager init
Please specify a file name for the config output (configuration.json):
Please enter the Data Center Name (PDC):
Please enter the Data Center Location (USA):
Please enter the service Name: catalogdb
Please select a service type:
1. ColumnStore(columnstore)
2. Xpand(distributed)
3. Galera(galera)
4. MariaDB with Replicas(replicated)
5. MariaDB(standalone)
4
Does your service include a MaxScale server: (Y/n) y
Please enter the MaxScale server Name: max1
Please enter the hostname: catalog-max1
Do you have another MaxScale server: (Y/n) n
Please enter the MariaDB server Name: vm1
Please enter the hostname: catalog-vm1
Do you want to use unix_socket authentication for MariaDB: (Y/n) y
Please enter the path to Unix socket file (/run/mysqld/mysqld.sock):
Finished adding servers: (Y/n) n
Please enter the MariaDB server Name: vm2
Please enter the hostname: catalog-vm2
Do you want to use unix_socket authentication for MariaDB: (Y/n) n
Finished adding servers: (Y/n) y
Please enter the user name for MariaDB servers or leave it empty: admin
Please enter a password for MariaDB servers or leave it empty: admin
Please enter the user name for MaxScale servers or leave it empty: admin
Please enter a password for MaxScale servers or leave it empty: admin
    URL: https://id.mariadb.com/account/api/
    Please use provided URL to obtain the API key; paste it below (for security, it will not be visible) and press 'Enter'
    API Key length: xxxx

Initial files have been created successfully:
configuration file:       configuration.json
API Key file:             api_token.txt
credentials file:         mariadb-credentials.json
credentials file:         maxscale-credentials.json

Next steps:
1. Run the agent manager installation command on all service's servers:
    ./mariadb_agent_manager install
2. Run the agent manager credentials encryption command on database and Maxscale servers that require user/password to login:
    ./mariadb_agent_manager encrypt-creds -p ./credentials.json
    with the generated credentials files (edit for each server as needed).
3. Run:
    ./mariadb_agent_manager start -c ./configuration.json -k ./api_token.txt -f
   on a server that will serve as Forwarding Host and
    ./mariadb_agent_manager start -c ./configuration.json
   on all other servers

Example Configuration Files

Single Node Enterprise Server

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-standalone",
        "type": "standalone",
        "servers": [
          {
            "name": "mdb1",
            "type": "server",
            "hostname": "mdb1.example.com"
          }
        ]
      }
    ]
  }
}

Replicated Transactions Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-replicated",
        "type": "replicated",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "mdb1",
            "type": "server",
            "hostname": "mdb1.example.com"
          },
          {
            "name": "mdb2",
            "type": "server",
            "hostname": "mdb2.example.com"
          },
          {
            "name": "mdb3",
            "type": "server",
            "hostname": "mdb3.example.com"
          }
        ]
      }
    ]
  }
}

Distributed Transactions Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-distributed",
        "type": "distributed",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "xpand1",
            "type": "xpand-backend",
            "hostname": "xpand1.example.com"
          },
          {
            "name": "xpand2",
            "type": "xpand-backend",
            "hostname": "xpand2.example.com"
          },
          {
            "name": "xpand3",
            "type": "xpand-backend",
            "hostname": "xpand3.example.com"
          }
        ]
      }
    ]
  }
}

Multi-Node Analytics Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-columnstore",
        "type": "columnstore",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "cs_node1",
            "type": "server",
            "hostname": "mdb1.example.com"
          },
          {
            "name": "cs_node2",
            "type": "server",
            "hostname": "mdb2.example.com"
          },
          {
            "name": "cs_node3",
            "type": "server",
            "hostname": "mdb3.example.com"
          }
        ]
      }
    ]
  }
}

Galera Cluster Topology

{
  "datacenter": {
    "name": "Example Data Center",
    "location": "Oregon, US",
    "database_services": [
      {
        "name": "example-galera",
        "type": "galera",
        "servers": [
          {
            "name": "mxs1",
            "type": "maxscale",
            "hostname": "mxs1.example.com"
          },
          {
            "name": "mdb1",
            "type": "server",
            "hostname": "mdb1.example.com"
          },
          {
            "name": "mdb2",
            "type": "server",
            "hostname": "mdb2.example.com"
          },
          {
            "name": "mdb3",
            "type": "server",
            "hostname": "mdb3.example.com"
          }
        ]
      }
    ]
  }
}