Installation and Parameter Configuration
This is the process of installing SysMaster DB 8.3 in a Docker-compose and Podman-compose environment.
Note
Podman-compose supports Docker-compose style yml files, so the same yml file can be used to run both Docker and Podman environments.
1. Load Docker/Podman image
In the directory where the installation files are prepared, execute the following command to load the Docker/Podman image.
Docker:
docker load -i sysmaster-db-{version}.tarPodman:
podman load -i sysmaster-db-{version}.tar
The list of loaded container images is as follows.
sysmaster-db-client:{version}
sysmaster-db-sdm:{version}
sysmaster-db-tibero-master:{version}
sysmaster-db-collector:{version}
sysmaster-db-analyzer:{version}
sysmaster-db-tmaxopensql-postgres:{version}
sysmaster-db-schema-registry:{version}
sysmaster-db-kafka-loggable:{version}
sysmaster-db-zookeeper-loggable:{version}
Note
The users can check the list of container images using the command
docker images | grep sysmaster .
2. Docker / Podman Service Definition
Open the docker-compose.yml file in the installation directory and define the 10 services to be created in the Docker-compose / Podman-compose environment. The description of each service is as follows.
client
The web server that users will access through their browsers
SDM
API server that retrieves collected information and communicates with clients
tibero-master
A server that performs status checks on the monitoring database and admin functions
collector
A server that collects data from the monitoring database
analyzer
A server that processes, analyzes, and stores collected information
metadb
DB server that stores UI-related setting information
repodb
A DB server that stores monitoring database collection data
zookeeper
Manages the status of Kafka Broker servers
broker
Kafka Broker server
Schema Registry
Kafka message protocol management
3. Set installation parameters
Open the .env file in the installation directory and set the parameter values required for installing SysMaster DB 8.3.
Note
If the .env file does not exist, create it using the vim .env command.
Each parameter should be separated by a line break, and there should be no spaces between the parameter name and value; simply enter an equal sign (=).
The parameters set in this process are described as follows.
CLIENT_PORT
Port number of the UI connection URL
8
ADMIN_USERNAME
Admin account username
admin
ADMIN_PASSWORD
Password for the Admin account
admin
COLLECTOR_PORT
Port number for the collection module (TPM Agent) to connect to [Note] Must be open on the SysMaster server to allow access from the monitoring DB
829
METADB_PORT
Meta DB connection port number
25432
METADB_USER
Meta DB super user name
sysmaster
METADB_PASSWORD
Meta DB super user password
sysmaster
METADB_PATH
Meta DB data file path
./meta
METADB_CONF_PATH
Path to the Meta DB configuration file
./meta.conf
REPODB_PORT
The port number for connecting to the repository DB
15432
REPODB_USER
Super user name for the repository DB
sysmaster
REPODB_PASSWORD
Repository DB super user password
sysmaster
REPODB_PATH
Repository DB data file path
./repo
REPODB_CONF_PATH
Path to the repository DB configuration file
./repo.conf
RETENTION_DAY
Retention period for collected information
7
LOG_PATH
Log creation location
./logs
LOG_RETENTION_DAY
Log file retention period
1
LOG_FILE_SIZE
Maximum size of a single log file
100MB
LOG_TOTAL_SIZE
Maximum log storage capacity per module
1000MB
LOG_LEVEL
Log level for each module
info
CONTAINER_LOG_PATH
Set the container internal log path
/sysmaster/logs
KAFKA_MESSAGE_MAX_BYTES
Set the Kafka message size, Can be set within the range of 1MB to 2GB
20971520 bytes
TIME_ZONE
SysMaster DB server time zone setting
Asia/Seoul
SQL_FLUSH_THRESHOLD
Limits the number of pieces of information that can be contained in a single SQL-related message. For SQL Plans, this value is limited to 10 times the specified value.
100 per monitoring DB
SQL_RS_FETCH_SIZE
The number of SQL-related information rows retrieved from the monitoring DB at one time.
1,000 per monitoring database
SKIP_DB_USER_COUNT_MIGRATION_PATCH
(When applying patches to an existing environment,) whether to skip the patch that creates the DB_USER_COUNT table data in the Repository DB based on previously collected data. If necessary, refer to [Note 1] below and configure accordingly.
true (disabled via comment)
SKIP_DAILY_SEGMENT_MIGRATION_PATCH
(When applying patches to an existing environment,) whether to skip the patch that creates data in the DAILY_SEGMENT table of the Repository DB based on existing data. If necessary, refer to [Reference 1] below and configure accordingly.
true (disabled via comment)
SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH
(When applying the patch to an existing environment,) whether to skip the migration of existing data collected in v8.2.1 or earlier for tables targeted by the new schema in v8.3.0. If necessary, refer to [Reference 2] below and configure accordingly.
true (disabled via comment)
RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH
(When applying patches to an existing environment,) the migration scope (daily period) for data collected in v8.2.1 or earlier that is subject to migration in tables where the new schema has been applied in v8.3.0. If necessary, refer to [Note 2] below and configure accordingly.
7 (Not applied via comment)
SDM_HEAP_SIZE_MAX
Maximum heap size for SDM
1/4 of the total memory of the current container (refer to the "total mem" output of the "free" command). [Note] The current default Docker image is openjdk:17-alpine.
SDM_HEAP_SIZE_MIN
Minimum heap size for SDM
It is 1/64 of the total memory of the current container (refer to the total mem of the free command). [Note] The current default Docker image is openjdk:17-alpine.
ANALYZER_HEAP_SIZE_MAX
Maximum heap size for the analyzer
1/4 of the current container's total memory (refer to the total mem value from the free command). [Note] The current default Docker image is openjdk:17-alpine.
ANALYZER_HEAP_SIZE_MIN
Analyzer's minimum heap size
1/64 of the current container's total memory (refer to the total mem value from the free command). [Note] The current default Docker image is openjdk:17-alpine.
COLLECTOR_HEAP_SIZE_MAX
Maximum heap size for the collector
1/4 of the current container's total memory (refer to the total mem value from the free command). [Note] The current default Docker image is openjdk:17-alpine.
COLLECTOR_HEAP_SIZE_MIN
Minimum heap size for the collector
1/64 of the current container's total memory (refer to the total mem value from the free command). [Note] The current default Docker image is openjdk:17-alpine.
TBM_HEAP_SIZE_MAX
Maximum heap size for TBM
1/4 of the current container's total memory (refer to the total mem value from the free command). [Note] The current default Docker image is openjdk:17-alpine.
TBM_HEAP_SIZE_MIN
Minimum heap size for TBM
It is 1/64 of the current container's total memory (refer to the total mem value from the free command). [Note] The current default Docker image is openjdk:17-alpine.
PERFORMANCE_LOGGING
Whether to enable performance-related logging [Note] Since this uses additional CPU and disk resources, setting this to Y may cause performance degradation.
N
LIMIT_SQL_HASH_COUNT
The maximum number of SQL plan hash value + cost combinations stored in memory to prevent duplicate collection, and the maximum number of SQL text hash values at the same time.
1 million [Note] This occupies approximately 300MB of memory in total.
NGINX_RESOLVER
Podman environment-specific setting Specifies the gateway address of the Sysmaster internal DNS network for DNS name resolution in NGINX. This setting is only required in the Podman environment and does not require additional configuration in other runtimes such as Docker.
Can be verified using `podman network inspect script_sysmaster`.
Note
The SKIP_DB_USER_COUNT_MIGRATION_PATCH and SKIP_DAILY_SEGMENT_MIGRATION_PATCH parameters are not required for new installations and are only applicable when performing a version update in environments where SysMaster DB v8.1.2 or earlier is already installed.
If these parameters are not set separately, the patch will be automatically applied during the version update, generating DB_USER_COUNT and DAILY_SEGMENT data based on the previously collected data.
However, depending on the amount of existing data, the patch execution may take a significant amount of time. Therefore, users can optionally enable or disable the patch execution using this parameter.
When using the SysMaster DB service version 8.1.3 or higher, the DB_USER_COUNT and DAILY_SEGMENT data are used in the following menus, respectively.
DB_USER_COUNT data - Analysis > All Session Flow menu
DAILY_SEGMENT data - Analysis > Segment Usage menu
Therefore, if the users configure the patch to be omitted (set each parameter to true and remove comments), the data from the past (collected before the update) will not be displayed in the menus 1 and 2 above. Therefore, we recommend that the users do not configure these parameters separately by default.
However, in the following cases, users can set the relevant parameters to true (remove comments) to skip the patch described earlier.
When viewing past data (collected in SysMaster DB v8.1.2 or earlier) in the menus mentioned in steps 1 and 2 is unnecessary
If there is concern that the SysMaster DB server resources may be insufficient during the data creation patch process, resulting in prolonged unavailability of the SysMaster DB, and this must be prevented.
Users can selectively set only the desired parameter among the two parameters as needed.
Note
The SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH and RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH parameters are not required for new installations and are only applicable when performing a version update in an environment where SysMaster DB v8.2.1 or earlier is already installed.
If these parameters are not set individually, a patch will automatically migrate data collected in versions prior to v8.2.1 to tables with the new schema applied in v8.3.0.
The list of tables with the new schema applied in v8.3.0 is as follows.
SQL
SQL_TEXT
SQL_PLAN
DB_SESSION
SESSION_TEMP
SESSION_UNDO
LOCK
SQL_TRACE
The migration process for the above tables may take a long time depending on the amount of data collected.
Users can optionally enable or disable the execution of the patch by configuring the following parameters as needed.
SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH
Set whether to perform the patch that migrates data from versions prior to v8.2.1 to the new schema applied in v8.3.0 for tables with the new schema.
If the SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH parameter is set to true (comment removed), migration will not be performed on all tables targeted by the patch.
If migration is not performed using the SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH setting, data collected in v8.2.1 or earlier will be deleted and will no longer be available for retrieval.
Therefore, it is recommended not to set this parameter separately by default.
However, in the following cases, users may consider skipping the migration:
If there is no need to view past data (collected in SysMaster DB v8.2.1 or earlier) from tables subject to the new schema in v8.3.0
If there are concerns that the SysMaster DB server resources may be insufficient during the data creation patch process, resulting in prolonged unavailability of the SysMaster DB, and this must be prevented.
In such cases, users can set the following parameter to perform the migration patch while separately specifying the data scope (daily period) for the patch execution.
RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH
Set the migration target data range (daily period) for data collected prior to v8.2.1 in tables where the new schema has been applied in v8.3.0.
For example, if the RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH parameter is set to 7 (comment removed), migration will only be performed on data collected in v8.2.1 or earlier within the last 7 days.
If the SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH parameter is set to true (comment removed), this parameter setting is ignored.
Refer to the above explanation to select and apply appropriate parameter settings for the usersr operating environment.
3.1 DNS Resolver Settings in Podman Environment
In a rootless Podman environment, the NGINX_RESOLVER parameter must be set separately. This is necessary for reconnection when individual containers are restarted after the sysmaster is started, and it uses the gateway IP address of the sysmaster network. This value may vary depending on the environment or Podman startup.
The following example shows the process of setting NGINX_RESOLVER=10.89.0.1 and booting the sysmaster.
4. Setting Meta DB and Repository DB Parameters
The users can check the Meta DB and Repository DB parameter values in the meta.conf and repo.conf files in the installation directory. These conf files use the default settings provided, but the parameters described below should be set manually by the user according to the runtime environment if necessary.
pg_max_connections
Maximum number of connections to the Meta DB (or Repository DB)
pg_owner_id
The user ID (uid) of the host OS for setting access permissions to the DB data directory. If the users want to directly access the container DB directory from a specific user on the host machine, set this to the user ID of that user.
pg_group_id
The user group ID (gid) of the host OS for setting access permissions to the DB data directory. If the users want to directly access the container DB directory from a specific user on the host machine, set this to the group ID of that user.
log_timezone
Time zone for logs in the Meta DB (or Repository DB).
Note
If the users need to change the Meta DB and Repository DB parameters, refer to the TmaxOpenSQL User Guide for the relevant parameter settings. However, if the users modify the relevant parameters arbitrarily, normal operation of the SysMaster DB server is not guaranteed. Therefore, we recommend using the default settings for parameters other than those specified in the table above.
Especially when installing in a Podman-compose environment, setting (or changing) the pg_owner_id and pg_group_id values directly may cause abnormal operation. Podman containers operate in Rootless mode, where the root user inside the container (owner_id = 0, group_id = 0) corresponds to the host machine's user. However, since OpenSQL does not allow installation or startup in root mode, it is recommended to use the default settings.
Last updated