Installation and Parameter Configuration

This is the process of installing SysMaster DB in a Kubernetes environment.

1. Load the Docker image

Execute the following command in the directory where the installation files are prepared to load the Docker image.

docker load -i sysmaster-db-{version}.tar

The list of loaded Docker 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}

• sysmaster-db-alpine-linux:{version}

---

2. Push Docker images

Push the loaded Docker images to the image repository used in the environment.

---

3. Kubernetes Object Definition

Define eight deployments using the YAML files in the kubernetes directory within the installation directory. The description of each deployment is as follows.

Deployment	Description
client	The web server that users will access through their browsers
sdm	An API server that queries 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	Monitoring database DB server that stores collected data
kafka	Kafka cluster (including ZooKeeper, Broker, and Schema Registry)

---

4. Installation parameter settings - Account information and retention period

Open the kubernetes/init/configmap.yaml file in the installation directory and set the parameter values related to account information and retention period required for installing the SysMaster DB.

apiVersion: v1
kind: ConfigMap
metadata:
  name: config-sysmaster
  namespace: sysmasterdb
data:
  RETENTION_DAY: "7"
  METADB_USER: sysmaster
  METADB_PASSWORD: sysmaster
  REPODB_USER: sysmaster
  REPODB_PASSWORD: sysmaster
  ADMIN_USERNAME: admin
  ADMIN_PASSWORD: admin
  LOG_RETENTION_DAY: "1"
  LOG_FILE_SIZE: "100MB"
  LOG_TOTAL_SIZE: "1000MB"
  LOG_LEVEL: "info"
  CONTAINER_LOG_PATH: "/sysmaster/logs"
  KAFKA_MESSAGE_MAX_BYTES: "20971520"
  TIME_ZONE: Asia/Seoul
  SQL_FLUSH_THRESHOLD: 100
  SQL_RS_FETCH_SIZE: 1000
  # SKIP_DB_USER_COUNT_MIGRATION_PATCH: true
  # SKIP_DAILY_SEGMENT_MIGRATION_PATCH: true
  # SKIP_V8_2_1_TO_V8_3_0_MIGRATION_PATCH=true
  # RETENTION_DAY_FOR_V8_2_1_TO_V8_3_0_MIGRATION_PATCH=7
  SDM_HEAP_SIZE_MAX: ""
  SDM_HEAP_SIZE_MIN: ""
  ANALYZER_HEAP_SIZE_MAX: ""
  ANALYZER_HEAP_SIZE_MIN: ""
  COLLECTOR_HEAP_SIZE_MAX: ""
  COLLECTOR_HEAP_SIZE_MIN: ""
  TBM_HEAP_SIZE_MAX: ""
  TBM_HEAP_SIZE_MIN: ""
  PERFORMANCE_LOGGING: ""
  LIMIT_SQL_HASH_COUNT: ""

The following is a description of the parameters set in this process.

Parameter Name	Description	Default
ADMIN_USERNAME	Admin account username	admin
ADMIN_PASSWORD	Password for the admin account	admin
METADB_USER	Meta DB super user name	sysmaster
METADB_PASSWORD	Meta DB super user password	sysmaster
REPODB_USER	Repository DB super user name	sysmaster
REPODB_PASSWORD	Repository DB super user password	sysmaster
RETENTION_DAY	Retention period for collected information	7
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	Maximum log level per module	info
CONTAINER_LOG_PATH	Set the log path inside the container	/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	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.
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	It is currently 1/4 of the total container memory (refer to total mem in the free command). [Note] The current default Docker image is openjdk:17-alpine.
COLLECTOR_HEAP_SIZE_MIN	Minimum heap size for the collector	Currently, it is 1/64 of the total container memory (refer to the "total mem" output of 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.

Note

SKIP_DAILY_SEGMENT_MIGRATION_PATCH parameters are not required for new installations and are only applicable when performing a version update in an existing environment with SysMaster DB v8.1.2 or earlier.

If these parameters are not set individually, the patch will be automatically applied during the version update, generating DB_USER_COUNT and DAILY_SEGMENT data based on the existing 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.

1. DB_USER_COUNT data - Analysis > All Session Flow menu

2. DAILY_SEGMENT data - Analysis > Segment Usage menu

Therefore, if the users configure the patch to be skipped (set each parameter to true and remove the comment), the data from the past (collected before the update) will not be displayed in the menus mentioned in 1 and 2 above. Therefore, it is recommended to leave these parameters unchanged by default.

However, in the following cases, users can set the relevant parameters to true (remove comments) to skip the previously described patch.

1. When viewing past data (collected in SysMaster DB v8.1.2 or earlier) in the menus mentioned in steps 1 and 2 is unnecessary.

2. 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:

1. 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

2. 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 that is subject to migration 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 description to select and apply the appropriate parameter settings for the usersr production environment.

---

5. Installation Parameter Settings - Port

Open the kubernetes/init/service.yaml file in the installation directory and set the parameter values related to the ports required for installing SysMaster DB. The descriptions of the parameters set during this process are as follows.

Parameter Name	Description	Default
CLIENT_PORT	Port number for the UI access URL [Modification location] Modify the nodePort in the ports section where metadata.name=client, name="client-port"
COLLECTOR_PORT	The port number for the collection module (TPM Agent) to connect to [Modification location] Modify the nodePort of the ports with metadata.name=collector, name="collector-port" [Note] Must be open on the SysMaster server to allow access from the monitoring DB.	82
METADB_PORT	Meta DB connection port number [Modification location] metadata.name=metadb, name="metadb-port" in ports nodePort modification	25432
REPODB_PORT	Repository DB connection port number [Modification location] metadata.name=repodb, name="repodb-port" in ports nodePort modification	15432

---

6. Meta DB and Repository DB Parameter Settings

The users can check the Meta DB and Repository DB parameter values in the kubernetes/init/configmap.yaml file in the installation directory. The following is an example of Meta DB parameter settings.

apiVersion: v1
kind: ConfigMap
metadata:
  name: sysmasterdb8-metadb-configmap
  namespace: sysmasterdb
data:
  meta.conf: |
    pg_superuser: "postgres"
    pg_superuser_password: "postgres"
    pg_data: "/pgdata"
    pg_log: "/sysmaster/logs"
    pg_users:
      - name: "sysmaster"
        pass: "sysmaster"
        role_attr_flags: LOGIN
    pg_databases:
      - name: metadb
        owner: sysmaster
    pg_max_connections: 20
    pg_postgres_conf_params:
      - name: "log_filename"
        value: "metadb-%H%M.log"
      - name: "log_timezone"
        value: "Asia/Seoul"
      - name: "log_min_messages"
        value: "INFO"
      - name: "log_rotation_age"
        value: "60"
      - name: "log_rotation_size"
        value: "100MB"
      - name: "log_truncate_on_rotation"
        value: "on"

This conf file uses the default settings provided, but the parameters described below should be set by the user as needed to match the runtime environment.

Parameter name	Description
pg_max_connections	Maximum number of connections to the Meta DB (or Repository DB)
log_timezone	Time zone for logs in the Meta DB (or Repository DB)

Note

If the users need to change the parameters for Meta DB and Repository DB, refer to the TmaxOpenSQL User Guide for related parameter settings. However, if the users arbitrarily modify the related parameters, the normal operation of the SysMasterDB server is not guaranteed. Therefore, we recommend using the default settings for parameters other than those specified in the table above.