Install Monitoring Console

DBCC is a console tool for monitoring SynxDB clusters and databases. It provides dashboards and metrics to help users diagnose the current state of the cluster and databases.

This document describes how to install and deploy the DBCC console components to enable monitoring for SynxDB clusters.

The DBCC console consists of two main components: DBCC Server and DBCC Agent. The DBCC Server is the dashboard server that receives and displays metrics in a unified view. The DBCC Agent runs on each cluster node, and collects and reports monitoring data.

The DBCC Agent monitors local system and services on each node, and reports data to the DBCC Server via the gRPC port. The DBCC Server is responsible for receiving, processing, and visualizing the operational status and performance metrics of all nodes in the cluster, and presents the results in the monitoring dashboard.

Prerequisites

A SynxDB database cluster has been installed and configured, and gpperfmon is enabled on all nodes.
The installation package and dependency packages of the DBCC components are available.
The target servers run Linux and support systemd.
root or sudo privileges.
curl (used for health checks).
glibc 2.17 or later.
Hardware requirements: CPU of at least 1 core, RAM of at least 2 GB.

Tip

gpperfmon is a performance monitoring component that helps administrators and developers view, analyze, and diagnose various metrics during cluster runtime. In SynxDB, you can enable gpperfmon following these steps:

Enable the monitoring service:

gpperfmon_install --enable --password <database_password> --port <database_port>

Restart the database:
```
gpstop -ar
```

Step 1: Deploy the Server component

Tip

DBCC Server uses the following default administrator credentials:

Username: admin
Password: admin

To change these default credentials, edit the config/dbcc-server/application.yml configuration file in the installation package before running the installation script. Update the following settings:

spring:
security:
   user:
      name: admin      # Changes to your preferred username
      password: admin  # Changes to your preferred password

Upload the DBCC Server installation tool to the target server, navigate to the tool directory, and run the following command:

sudo ./deploy.sh install

This command performs the following tasks:

Creates required directories.
Copies binaries and configuration files.
Adds systemd service files.
Starts the DBCC Server, Prometheus, and AlertManager services.

After deploying the DBCC Server, open a browser and access the control panel at:

http://<DBCC_SERVER_IP>:8080

<DBCC_SERVER_IP> refers to the IP address of the server where the DBCC Server is installed.

The following table lists the default ports used by the DBCC Server.

Default ports

Component	Port	Description
DBCC Server UI	8080	Web dashboard access port
DBCC gRPC	28080	Port used by Agents to report data
Prometheus	9090	Prometheus dashboard
AlertManager	9093	Alert management dashboard

Start and maintain the Server

Example commands:

 # Starts all services
 sudo ./deploy.sh start

 # Starts a specific service
 sudo ./deploy.sh start dbcc-server
 sudo ./deploy.sh start prometheus
 sudo ./deploy.sh start alertmanager

 # Stops all services
 sudo ./deploy.sh stop

 # Stops a specific service
 sudo ./deploy.sh start prometheus

 # Restarts all services
 sudo ./deploy.sh restart

 # Restarts a specific service
 sudo ./deploy.sh restart alertmanager

 # Checks the status of all services
 sudo ./deploy.sh status

 # Checks the status of a specific service
 sudo ./deploy.sh status alertmanager

 # Checks the version of the monitoring server package and its components
 sudo ./deploy.sh version

# Checks the version of a specific service, for example, alertmanager
 sudo ./deploy.sh version alertmanager

Configuration file paths

The main configuration file of DBCC Server is located at /etc/dbcc/dbcc-server/application.yml. This file contains important server operation settings.
Tip

You can customize the server logo, icon, and name by adding the following configuration to the /etc/dbcc/dbcc-server/application.yml file:
```
dbcc:
title: 'custom name'           # custom display name
distribution:
   distributor: 'distributor'   # only supports SynxDB or BlueBerry
```
Prometheus service configuration files:
- Main configuration: /etc/dbcc/prometheus/prometheus.yml
- Alert rules: /etc/dbcc/prometheus/alert_rule.yml
- Scrape targets: /etc/dbcc/prometheus/scrape_config.yml
AlertManager service configuration file: /etc/dbcc/alertmanager/alertmanager.yml

Step 2: Deploy the Agent on each node

Upload the DBCC Agent installation tool to each node in the SynxDB cluster, then go to the tool directory on each node and run:

sudo ./deploy.sh install --console-url <DBCC_SERVER_IP>:28080

<DBCC_SERVER_IP> is the gRPC IP address of the DBCC Server. For example:

sudo ./deploy.sh install --console-url 192.168.0.1:28080

This command performs the following tasks:

Creates necessary directories.
Copies binaries and configuration files.
Sets up systemd service files.
Starts the Agent service.

Attention

The console-url parameter is critical for communication between the Agent and the DBCC Server. This parameter includes the server IP address and the gRPC port (DBCC_SERVER_GRPC_PORT, default: 28080).

The format of the console-url parameter is <server_ip>:<grpc_port>, for example: 192.168.0.1:28080.

The console URL is saved in the Agent configuration file located at /etc/dbcc/dbcc-agent/config.yml, for example:

# Console configuration
console:
   # Console service address
   url: "192.168.0.1:28080"

Start and maintain the Agent

Example commands:

# Starts the Agent service
sudo ./deploy.sh start

# Stops the Agent service
sudo ./deploy.sh stop

# Restarts the Agent service
sudo ./deploy.sh restart

# Checks the service status
sudo ./deploy.sh status

# Checks the version information of the Agent package and its components
sudo ./deploy.sh version

Next step

After deploying DBCC, you can open the dashboard to view the status of each node in the cluster, including performance metrics such as CPU, memory, and disk I/O. For details, see View Monitoring Data Using the Web Console.

Troubleshooting

Server service fails to start

Check the service status:
```
sudo ./deploy.sh status dbcc-server
```
View detailed logs:
```
sudo journalctl -u dbcc-server -f
```

Verify port availability:

sudo netstat -tulpn | grep 8080
sudo netstat -tulpn | grep 28080

Check for errors in the configuration file:

cat /etc/dbcc/dbcc-server/application.yml

Server health check fails

If the health check fails:

Make sure the service is running.
Check if the ports are accessible.
Check the service logs for errors:
```
sudo journalctl -u dbcc-server -f
```
Verify the configuration file is correct.

Agent service fails to start

Check the service status:
```
sudo ./deploy.sh status
```
View detailed logs:
```
sudo journalctl -u dbcc-agent -f
```
Verify the configuration:
```
cat /etc/dbcc/dbcc-agent/config.yml
```
Check if the console URL is correctly set and the server is reachable:
```
ping <server_ip>
telnet <server_ip> <grpc_port>
```

Agent health check fails

If the health check fails:

Make sure the service is running.
Check whether the DBCC Server is accessible.
Check the service logs for errors:
```
sudo journalctl -u dbcc-agent -f
```
Verify that the console URL in the configuration file is correct.