> For the complete documentation index, see [llms.txt](https://docs.tibero.com/sysmasterdb/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tibero.com/sysmasterdb/8.4_manual/installation-guide/db-configuration/tpm-agent/installation-parameters.md).

# 설치 및 파라미터 설정

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

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

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

{% code collapsedlinecount="10" %}

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

{% endcode %}

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

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

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

***

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

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

{% code collapsedlinecount="10" %}

```
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/
```

{% endcode %}

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

<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>SysMasterDB 서버에 접속할 수 있는 IP 주소</td><td>O</td></tr><tr><td>agent-config</td><td>port</td><td>TPM Agent가 SysMasterDB 서버의 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>sessioninfo-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

***

### 환경 변수를 통한 설정 <a href="#undefined-2" id="undefined-2"></a>

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

{% code collapsedlinecount="10" %}

```
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
```

{% endcode %}

{% 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     |