# 설치 및 파라미터 설정

TPM Agent를 설치하는 과정은 다음과 같다. **단, 반드시 관제 데이터베이스를 설치한 계정과 동일한 OS 계정으로 진행해야 한다.**

### 1. **설치 파일 배포**

관제 데이터베이스가 위치한 서버에 "tpmagent\_dist\_{*version*}.tar.gz" 압축 파일을 배포한 후 압축을 해제한다.

```
tar -zxvf java_tpmagent_dist_{version}.tar.gz
```

{% hint style="info" %}
**참고**

설치 파일 압축 해제 시 150MB 정도이다. 해당 공간만큼 확보한 이후에 압축 해제를 해야 한다. 이후 에 운영 시에는 로그 로테이션 설정에 따라 용량을 확보하면 된다.

로그 파일 로테이션이란 기존에 로그를 적재하던 로그 파일을 아카이빙하고 새로운 로그 파일을 생 성하여 적재하는 것이다. 기본적으로 매 24시간 또는 한 파일의 사이즈가 50MB를 넘었을 때 새 로그 파일을 생성한다. 또한 로그 파일을 최대 7개까지 저장하는 것이 기본 설정이며, 7개가 넘어가게 되 면 오래된 로그 파일부터 삭제된다. 따라서 기본 설정인 상태에서 시간 트리거만 발생했을 때는 약 1주일 분량의 로그를 보관하며, 파일 사이즈 트리거만 발생했을 때 약 350MB 분량의 로그를 보관한 다. 그러므로 기본 설정인 상태에서 모든 로그를 보관하기 위해서는 실행 파일과 로그 파일을 합쳐 약 500MB 이상의 공간을 확보해야 한다.
{% endhint %}

###

***

### 2. application.yml 파일 설정

"java\_tpmagent\_dist\_{version}.tar.gz" 압축 파일을 해제한 디렉터리에 application.yml 파일을 아래와 같이 작성하여 설정을 적용한다.\
\
yml 문법에 맞게 각 파라미터들의 값을 조정하여 설정한다.

```
agent-config:
  id: "AAA1"
  ip: "192.1.3.225"
  port: 8292
  freq: 1000
  charset: "utf-8"
  cpu-mem-proc-freq: 5000
  disk-freq: 5000
  sessioninfo-freq: 5000
  dbsysinfo-freq: 5000
  sqltrace-freq: 5000
  sqltrace-queue-size: 10
  sqltrace-elapsed-time-threshold: 100
  sqltrace-monitoring-freq: 10
  sqltrace-monitoring-thread-per-session-count: 500
log:
  level: INFO
  rotate-time-interval: 24
  rotate-file-size: 50MB
  max-log-file-number: 7
  path: logs/
```

해당 과정에서 설정하는 파라미터에 대한 설명은 다음과 같다.

<table><thead><tr><th>카테고리</th><th>파라미터</th><th width="444">설명</th><th>필수 여부</th></tr></thead><tbody><tr><td>agent-config</td><td>id</td><td><p>인스턴스 ID<br></p><p><strong>[참고]</strong> 웹 UI에서 관제 데이터베이스 인스턴스 등록 시 입력한 INSTANCE ID 값과 동일해야 함. 잘못 입력시 잘못된 Tibero 설치 머신 현황과 세션 목록, 그리고 TSC 네트워크 구성을 모니터링하게 되므로 주의 요망.</p></td><td>O</td></tr><tr><td>agent-config</td><td>ip</td><td>SysMaster DB 서버에 접속할 수 있는 IP 주소</td><td>O</td></tr><tr><td>agent-config</td><td>port</td><td>TPM Agent가 SysMaster DB 서버의 COLLECTOR_PORT로 연결하기 위한 포트 번호</td><td>O</td></tr><tr><td>agent-config</td><td>freq</td><td><p>수집 주기 (단위: msec).</p><p></p><p><strong>[참고]</strong> 설정하지 않으면 1000ms로 설정되므로 1초 주기로 수집.</p></td><td>X</td></tr><tr><td>agent-config</td><td>charset</td><td><p>관제 DB의 문자 집합 (NLS_CHARACTERSET 파라미터로 확인).</p><p></p><p><strong>[참고]</strong> 설정하지 않으면 utf-8 로 설정</p></td><td>X</td></tr><tr><td>agent-config</td><td>cpu-mem-proc-freq</td><td>CPU, 메모리, 프로세스 목록 정보를 가져오는 주기(단위: ms)<br><br><strong>[참고]</strong> 설정하지 않으면 "freq" 값으로 설정됨</td><td>X</td></tr><tr><td>agent-config</td><td>disk-freq</td><td><p>디스크 정보를 가져오는 주기 (단위: ms) </p><p></p><p><strong>[참고]</strong> 설정하지 않으면 "freq × 60" 값으로 설정되며, 설정하면 설정한 주기로 수집을 진행</p></td><td>X</td></tr><tr><td>agent-config</td><td>session-freq</td><td><p>세션 정보를 가져오는 주기 (단위: ms) </p><p></p><p><strong>[참고]</strong> 설정하지 않으면 "freq" 값으로 설정됨</p></td><td>X</td></tr><tr><td>agent-config</td><td>dbsysinfo-freq</td><td><p>관제 DB의 시스템 지표 정보를 가져오는 주기 (단위: ms) </p><p></p><p><strong>[참고]</strong> 설정하지 않으면 "freq" 값으로 설정됨</p></td><td>X</td></tr><tr><td>agent-config</td><td>sqltrace-freq</td><td><p>SQL Trace 정보를 가져오는 주기 (단위: ms)</p><p></p><p><strong>[참고]</strong> 설정하지 않으면 "freq" 값으로 설정됨</p></td><td>X</td></tr><tr><td>agent-config</td><td>sqltrace-queue-size</td><td>메모리에 SQL Trace를 수집하기 전에 저장하는 개수. sqltrace-freq마다 해당 queue에서 수집된 SQL Trace를 모아서 수집한다. (1 ~ 2^32-1 사이의 정수).<br><br><strong>[참고]</strong> 설정하지 않으면 10으로 설정</td><td>X</td></tr><tr><td>agent-config</td><td>sqltrace-elapsed-time-threshold</td><td>SQL 실행 정보 생성 기준 실행 시간 임계치(단위: ms)(예: 100msec 이상 수행된 SQL에 대해서만실행 정보 생성)<br><br><strong>[참고]</strong> 설정하지 않으면 100으로 설정</td><td>X</td></tr><tr><td>agent-config</td><td>sqltrace-monitoring-freq</td><td>SQL Trace를 모니터링하는 스레드의 세션 목록 조회 주기(단위: ms)<br><br><strong>[참고]</strong> 설정하지 않으면 10으로 설정</td><td>X</td></tr><tr><td>agent-config</td><td>sqltrace-monitoring-thread-per-session-count</td><td>SQL Trace를 모니터링하는 스레드가 담당하는 세션의 개수<br><br><strong>[참고]</strong> 설정하지 않으면 500으로 설정</td><td>X</td></tr><tr><td>log</td><td>level</td><td><p>로그 레벨로</p><ul><li> FATAL </li><li>ERROR</li><li>WARN</li><li>INFO</li><li>DEBUG</li><li>TRACE </li></ul><p></p><p><strong>[참고]</strong>설정하지 않으면 INFO 로 설정됨.</p><p><br>DEBUG 이상 설정을 할 경우 로그양이 많아져 TPM Agent 에 설정한 주기 안에 수집을 하지 못하여 데이터 누락이 발생할 수 있음. 그로 인하여 실시간 데이터 모니터링 중 데이터가 조회되지 않는 현상이 있을 수 있음. 따라서 운영 환경에서는 해당 설정을 하지 않는 것을 권고하며, 이슈 분석을 위해서만 해당 로그 레벨을 설정.</p></td><td>X</td></tr><tr><td>log</td><td>rotate-time-interval</td><td><p>로그 파일이 아카이빙되는 주기 (단위: h)</p><p></p><p>적재 중인 로그 파일을 주기마다 아카이빙하고 새로운 로그 파일에 적재</p><p></p><p><strong>[참고]</strong> 설정하지 않으면 24로 설정되므로 하루 주기로 로그 파일 아카이빙</p></td><td>X</td></tr><tr><td>log</td><td>rotate-file-size</td><td><p>로그 파일이 아카이빙되는 파일 사이즈 (단위: MB) </p><p></p><p>적재 중인 로그 파일이 해당 파일 사이즈에 도달하면 적재 중인 로그 파일을 아카이빙하고 새로운 로그 파일에 적재</p><p></p><p><strong>[참고]</strong> 설정하지 않으면 50으로 설정되므로 적재 중인 로그 파일이 50MB에 도달하면 로그 파일 아카이빙</p></td><td>X</td></tr><tr><td>log</td><td>max-log-file-number</td><td><p>아카이빙되는 파일 최대 개수 (단위: 개수) </p><p></p><p>아카이빙한 파일 개수가 최대에 도달하면 가장 오래 된 로그 파일부터 삭제</p><p></p><p><strong>[참고]</strong> 설정하지 않으면 7로 설정되므로 최대 로그 파일 개수는 7개</p></td><td>X</td></tr><tr><td>log</td><td>path</td><td><p>로그 파일 생성 디렉터리</p><p></p><p><strong>[참고]</strong> 설정하지 않으면 tpmagent.jar 경로에 logs/ 로 경로 설정</p></td><td>X</td></tr></tbody></table>

{% hint style="info" %}
**참고**

현재 Java TPM Agent는 Tibero jdbc Charset 을 동일하게 지원한다.
{% endhint %}

{% hint style="info" %}
**참고**

1. sqltrace-elapsed-time-threshold 이상 수행된 SQL 실행 정보를 sqltrace-queue-size 크기의 큐에 저장한다.
2. 큐가 모두 차있을 경우 가장 오래된 SQL 실행 정보부터 큐에서 지운다.
3. TPM Agent에서 sqltrace-freq(ms)마다 SQL 실행 정보를 수집하므로,  \[세션 개수 \* (sqltrace-freq / sqltrace-elapsed-time-threshold) ≤ sqltrace-queue-size] 로 sqltrace-queue-size를 설정해야 정상적인 상황에 유실되는 정보가 없다. sqltrace-queue-size의 경우 위에 언급되어 있듯 개수이므로 정수 값이며, 만약 나누기의 결과가 0.01과 같은 소수일 경우 부등호로 인하여 0.01 이상의 정수인 1이상으로 sqltrace-queue-size를 설정하면 유실이 없다. sqltrace-freq의 범위와 sqltrace-queue-size의 범위는 매뉴얼에 기입된 것을 참고한다. 추가로 부하 상황에서는 권장 값으로 sqltrace-queue-size를 설정하였더라도 수집 누락이 발생할 수 있는데, 예를 들어 Tibero에 부하가 발생하여 CPU 자원을 TPM Agent가 사용하지 못하게 되는 상황이 발생하면 수집 주기가 예기치 못하게 늘어나게 된다. 만약 기존에 1000ms 마다 수집을 하고 있었는데, CPU 자원을 사용하지 못하여 몇 초간 수집을 2000ms 마다 진행하게 될 수 있다. 이럴 경우 권장 값으로 설정하였더라도 SQL Trace 수집에 누락이 발생할 수 있다. 이럴 경우를 대비하여 권장 값보 다 더 많은 sqltrace-queue-size를 할당하여 대비할 수 있으나, 그만큼 메모리를 사용하게 되므로 상황에 맞게 권장 값 기반으로 sqltrace-queue-size를 설정하면 된다.
   {% endhint %}

***

### Java TPM Agent 지원 Charset

Tibero에서 지원하는 문자 집합은 다음과 같다.

* ASCII
* EUC-KR
* MSWIN949
* UTF-8
* UTF-16
* SHIFT-JIS
* JA16SJIS
* JA16SJISTILDE
* JA16EUC
* JA16EUCTILDE
* VN8VN3
* GBK
* WE8MSWIN1252
* ZHT16HKSCS
* CL8MSWIN1251
* WE8ISO8859P1
* EE8ISO8859P2
* WE8ISO8859P9
* WE8ISO8859P15
* CL8KOI8R
* CL8ISO8859P5
* CP866
* TH8TISASCII
* EL8MSWIN1253
* EL8ISO8859P7
* AR8MSWIN1256
* AR8ISO8859P6
* SJISTILDE
* ZHT16BIG5
* ZHT16MSWIN950
* GB18030
* IW8ISO8859P8
* EUC-TW

###

***

### 환경 변수를 통한 설정

"java\_tpmagent\_dist\_{version}.tar.gz" 압축 파일을 해제한 디렉터리에 set.sh 파일에 적용시킬 환경 변수들이 있으며, 아래와 같이 작성하여 설정을 적용한다.

```
export BOOT_WITH_AUTO_DOWN_CLEAN=true
export ENABLE_DEBUG=false
export ENABLE_GC_LOG=false
export JAVA_MIN_HEAP_SIZE=1000m
export JAVA_MAX_HEAP_SIZE=1000m
```

{% hint style="info" %}
**참고**

Tibero max session이 2000세션인 기준으로 1000MB 이며, 그 이상이면 max heap size를  증가시켜줘야 한다. 1000세션 당 200MB를 증가시키는 것을 권장한다. (한 세션 당 할당하는 SQL Trace의 개수가 10개라 가정했을 때, 한 세션당 추가로 사용하는 메모리는 약 200KB이다.)
{% endhint %}

해당 과정에서 설정하는 환경변수에 대한 설명은 다음과 같다.

| 환경 변수                         | 설명                                                                                     | 필수 여부 |
| ----------------------------- | -------------------------------------------------------------------------------------- | ----- |
| BOOT\_WITH\_AUTO\_DOWN\_CLEAN | TPM Agent 실행시 기존에 실행중인 process가 있으면 해당 프로세스 종료 후 실행할 것인가에 대한 환경 변수, default는 true      | X     |
| ENABLE\_DEBUG                 | TPM Agent 실행시 debug port를 열 것인 지에 대한 환경 변수, default는 false                             | X     |
| ENABLE\_GC\_LOG               | TPM Agent 실행시 jvm gc log를 파일로 생성할 것인가에 대한 환경 변수, default는 false                        | X     |
| JAVA\_MIN\_HEAP\_SIZE         | TPM Agent 실행시 시작 heap 크기 설정에 대한 환경 변수, default는 각 jvm 구현체마다 다르며 보통 현재 머신 메모리의 1/64 이다. | X     |
| JAVA\_MAX\_HEAP\_SIZE         | TPM Agent 실행시 최대 heap 크기 설정에 대한 환경 변수, default는 각 jvm 구현체마다 다르며 보통 현재 머신 메모리의 1/4 이다.  | X     |

###


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tibero.com/sysmasterdb/8.3_manual/installation-guide/db-configuration/tpm-agent/installation-parameters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.