> 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/appendix/appendix-c.md).

# Appendix C. 메트릭 데이터 마이그레이션

v8.3에서 v8.4로 업그레이드한 환경에서, 업그레이드 시 옮겨지지 않은 과거 메트릭 데이터를 v8.4 저장 구조로 마저 옮기는 방법이다.

## 1. 개요

v8.3에서 v8.4로 업그레이드하면 메트릭 데이터의 저장 구조가 바뀐다. 업그레이드 후 첫 기동에서 패치가 자동으로 구조를 전환하고, 최근 2일치(오늘·어제) 데이터만 새 구조로 옮긴다. 그보다 오래된 데이터는 옮기기 전까지 화면에서 조회되지 않으며, 데이터 보관 기간(RETENTION\_DAY, 기본 7일)이 지난 날짜부터 SDM이 매일 자동으로 삭제한다. 과거 데이터가 필요하면 업그레이드 후 되도록 빨리 이관한다.

본 장의 `migrate-metrics-v84` 명령은 그 남은 과거 데이터를 마저 옮기는 작업이다. 자동으로 실행되지 않으므로 운영자가 직접 수행해야 한다.

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

본 장에서 메트릭(Metric)은 Repository DB에 저장되는 모니터링 수집 데이터의 종류(`cpu`, `memory`, `db_event_io` 등)를 가리킨다. 대상 메트릭 43종의 전체 이름은 아래 9절에 있다.
{% endhint %}

### 1.1 실행 대상

| 구분           | 설명                                                         |
| ------------ | ---------------------------------------------------------- |
| 실행이 필요한 경우   | v8.3.x에서 v8.4로 업그레이드한 환경에서, 과거 메트릭 데이터를 화면에서 계속 조회해야 하는 경우 |
| 실행이 필요 없는 경우 | v8.4를 신규 설치한 환경. 옮길 과거 데이터가 없어 명령을 실행해도 아무 일도 일어나지 않는다     |

### 1.2 데이터 위치

메트릭마다 옮길 원본과 옮겨질 대상 테이블이 한 쌍씩 있으며, 이름은 메트릭명에서 그대로 만들어진다.

| 구분           | 테이블 이름                  | 설명                                           |
| ------------ | ----------------------- | -------------------------------------------- |
| 원본 (v8.3 구조) | `v83_{메트릭명}`            | 아직 옮기지 않은 과거 데이터. 업그레이드 시 패치가 이 이름으로 바꿔 보관한다 |
| 원본의 일별 파티션   | `v83_{메트릭명}_{YYYYMMDD}` | 하루치 단위. 이관은 이 단위로 처리된다                       |
| 대상 (v8.4 구조) | `_{메트릭명}`               | 화면이 조회하는 테이블. 이관이 끝나면 데이터가 여기로 들어온다          |

예를 들어 메트릭명이 cpu이면 원본은 `v83_cpu`, 그 안의 하루치는 `v83_cpu_20260715`, 대상은 `_cpu`이다.

***

## 2. 실행 방법

모든 명령은 SDM 컨테이너 안에서 실행한다.

{% code collapsedlinecount="10" %}

```
docker exec -it sdm migrate-metrics-v84 [옵션]
```

{% endcode %}

Podman 환경에서는 `podman exec -it sdm migrate-metrics-v84 [옵션]`을 수행한다.

이후 예시는 `migrate-metrics-v84` 부분만 표기한다. 실제로는 위와 같이 `docker exec -it sdm`(Podman 환경에서는 `podman exec -it sdm`)을 앞에 붙여 실행한다.

전체 도움말은 `migrate-metrics-v84 --help`로 확인할 수 있다.

***

## 3. 표준 실행 절차

기본 절차는 STEP 1에서 원본을 남긴 채 먼저 옮기고, 결과를 확인한 뒤 STEP 3에서 원본을 정리하는 2단계 구성이다. 이관 결과가 기대와 다를 때 원본이 남아 있어 다시 판단할 수 있다.

{% hint style="info" %}
**참고 — 원본 보존이 필요 없다면 STEP 1·2를 건너뛰어도 된다.**

이관 결과를 미리 확인할 필요가 없다면 STEP 3부터 실행한다. 한 번의 실행으로 이관과 원본 정리가 함께 끝나므로, 같은 데이터를 두 번 읽지 않아 소요 시간도 줄어든다.

대신 이관 직후 원본이 사라진다. 결과를 확인한 뒤에 원본을 정리하려면 STEP 1부터 진행한다.
{% endhint %}

### STEP 1. 이관 (원본 보존)

남아 있는 과거 데이터를 옮긴다. 원본은 그대로 둔다.

{% code collapsedlinecount="10" %}

```
migrate-metrics-v84 --keep-migrated-old-partitions
```

{% endcode %}

남은 전부를 옮긴다. 특정 하루만 옮기려면 `--date YYYYMMDD`, 최근 며칠만 옮기려면 `--retention-days N`을 붙인다.

진행률이 한 줄로 표시되고, 끝나면 `STATUS SUCCESS`로 마친다. 이 단계에서는 원본을 지우지 않는다.

### STEP 2. 결과 확인

화면에서 과거 구간의 메트릭이 정상적으로 조회되는지 확인한다. 이 확인을 마친 뒤 다음 단계로 넘어간다.

### STEP 3. 재실행 (원본 정리)

같은 명령에서 `--keep-migrated-old-partitions`만 뺀다. 이미 옮긴 데이터는 다시 옮기지 않고 원본만 정리하므로, 이 실행 결과의 migrated\_rows가 0인 것은 정상이다.

{% code collapsedlinecount="10" %}

```
migrate-metrics-v84
```

{% endcode %}

{% hint style="info" %}
**참고 — 빈 테이블 정리는 자동이다.**

옮기기가 모두 끝나면 하루치 데이터가 사라진 `v83_*` 테이블만 빈 껍데기로 남는다. 이 테이블은 SDM이 매일 자동으로 정리하므로 운영자가 따로 실행할 명령은 없다.

마지막 실행이 `STATUS SUCCESS`로 끝나고 화면에서 과거 구간이 조회되면 작업이 완료된 것이다.
{% endhint %}

***

## 4. 옵션

| 옵션                               | 설명                                                                                                                                                                                                                                                                                        |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--date YYYYMMDD[,YYYYMMDD...]`  | <p>특정 날짜만 옮긴다(예: <code>--date 20260715</code>). 원본 파티션 이름의 날짜와 같은 형식이다.<br>쉼표로 여러 날짜를 한 번에 지정할 수 있다(예: <code>--date 20260714,20260715</code>).<br>날짜 기준은 UTC이다. 로컬 시각으로 환산해 넣으면 하루 어긋난다.<br><code>--retention-days</code>, <code>--drop-expired-old-partitions</code>와 함께 쓸 수 없다.</p>     |
| `--retention-days DAYS`          | <p>오늘로부터 DAYS일 이내 데이터만 옮긴다. 양의 정수이며, 생략하면 남은 전부를 옮긴다.<br>최근 며칠만 먼저 옮겨 보고 싶을 때 사용한다. 기준일은 UTC로 계산한다.<br>기준일 당일은 만료로 보지 않으므로 1은 어제·오늘을 뜻한다.</p>                                                                                                                                             |
| `--keep-migrated-old-partitions` | <p>옮긴 뒤에도 원본을 지우지 않는다. 결과를 확인한 뒤 원본을 정리하려는 경우에 사용한다.<br>원본 보존이 필요 없으면 이 옵션 없이 한 번만 실행하면 된다.</p>                                                                                                                                                                                           |
| `--metric NAME[,NAME...]`        | <p>메트릭 하나(예: <code>cpu</code>, <code>db\_event\_io</code>) 또는 묶음 <code>db\_event</code>(DB 이벤트 20종), <code>db\_session\_event</code>(세션 이벤트 20종)를 처리한다.<br>쉼표로 여러 개를 함께 지정할 수 있다(예: <code>--metric cpu,memory,db\_event</code>).<br>생략하면 대상 43종을 순서대로 처리한다. 이름을 잘못 쓰면 지원 목록 전체를 안내한다.</p> |
| `--threads N`                    | <p>메트릭 N개를 동시에 처리한다(1부터 8까지, 기본 1). 여러 메트릭을 옮길 때 소요 시간이 줄어든다.<br>메트릭 하나만 옮길 때는 효과가 없다.</p>                                                                                                                                                                                                |
| `--batch-sleep-seconds N`        | 하루치를 하나 옮길 때마다 N초 쉬어 부하를 낮춘다. 기본값은 0이다. 운영 시간대에 실행할 때 사용한다.                                                                                                                                                                                                                               |
| `--stop`                         | <p>실행 중인 이관을 안전하게 중단한다. 중단 요청은 하루치를 시작하기 전에만 확인하므로, 처리 중이던 하루치는 끝까지 마친 뒤 멈춘다. 어중간한 상태가 남지 않고, 같은 명령을 재실행하면 멈춘 지점부터 이어진다.<br>실행 중인 작업이 없으면 <code>IDLE</code>을 반환한다.<br>터미널을 닫거나 Ctrl+C를 눌러도 이관은 멈추지 않는다. 중단하려면 반드시 이 옵션을 사용한다.</p>                                                         |
| `--background`                   | 백그라운드로 시작하고 즉시 반환한다. 데이터가 많은 환경에 권장한다.                                                                                                                                                                                                                                                    |
| `--status`                       | 백그라운드 작업의 현재 상태를 조회한다.                                                                                                                                                                                                                                                                    |
| `--log`                          | 백그라운드 작업의 진행 로그를 조회한다.                                                                                                                                                                                                                                                                    |
| `--drop-expired-old-partitions`  | <p><code>--retention-days</code> 범위 안의 데이터는 그대로 옮기고, 범위 밖의 과거분은 옮기지 않고 바로 지운다. 지운 데이터는 되살릴 수 없다.<br><code>--retention-days</code> 없이 쓰면 오류로 거부된다.</p>                                                                                                                                     |
| `-h`, `--help`                   | 전체 도움말을 출력한다.                                                                                                                                                                                                                                                                             |

***

## 5. 데이터가 많은 환경

진행 상황과 최종 결과를 언제든 다시 확인할 수 있도록 백그라운드로 실행한다.

{% code collapsedlinecount="10" %}

```
migrate-metrics-v84 --background --threads 4 --keep-migrated-old-partitions
migrate-metrics-v84 --status      # 상태 확인
migrate-metrics-v84 --log         # 진행 로그
migrate-metrics-v84 --stop        # 필요 시 안전 중단
```

{% endcode %}

`--threads`로 여러 메트릭을 동시에 처리해 시간을 줄이고, 운영 시간대에 수행해야 한다면 `--batch-sleep-seconds`로 부하를 낮출 수 있다. `--threads`는 값만큼 Repository DB 연결을 추가로 열어 동시에 쓰므로 DB 부하가 커진다. 수집이 진행 중인 운영 시간대에는 기본값(1)을 권장한다.

{% hint style="warning" %}
**주의 — 터미널을 닫아도 이관은 계속된다.**

접속이 끊기거나 Ctrl+C를 눌러도 서버에서 이관은 끝까지 진행되며, 화면 출력만 사라진다. 실제로 멈추려면 `--stop`을 실행한다.

기본 실행으로 시작했다가 화면이 끊겼다면 진행 상황은 아래 7.1의 이관 실행 로그 파일에서 확인할 수 있다. `--background`로 실행했다면 `--status`, `--log`로 바로 확인된다.
{% endhint %}

***

## 6. 주의 사항

| 항목               | 내용                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| 기본 동작은 원본을 정리한다  | 옮기기가 끝난 일자의 원본은 기본적으로 제거된다. 결과를 먼저 보려면 `--keep-migrated-old-partitions`를 붙여 실행한다.                                  |
| 폐기 옵션은 마지막에      | `--drop-expired-old-partitions`는 `--retention-days` 범위 밖의 과거분을 옮기지 않고 지운다. 폐기가 확정된 뒤에만 사용한다.                       |
| 동시에 두 번 실행하지 않는다 | 이미 실행 중이면 `STATUS RUNNING`으로 거부된다(`--background`로 시작한 경우에는 HTTP 409). 먼저 시작한 작업이 끝나기를 기다리거나 `--stop`으로 중단한 뒤 실행한다. |

***

## 7. 중단·실패 시 대처

{% hint style="info" %}
**참고 — 같은 명령을 다시 실행하면 된다.**

이관은 하루치 단위로 처리되며, 어느 단계에서 실패하든 그 일자의 원본은 그대로 남는다. 이미 끝난 일자는 그대로 유지되고, 재실행하면 실패한 지점부터 이어서 처리한다. 같은 데이터가 두 번 들어가지 않으므로 재실행 횟수는 문제되지 않는다.
{% endhint %}

| 증상                                           | 대처                                                                                                                                                                                                                                   |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 실행 중인 작업을 멈추고 싶음                             | <p><code>--stop</code>을 실행한다. 처리 중이던 하루치가 마무리된 뒤 안전하게 멈추고, 상태가 <code>CANCELLED</code>로 표시된다.<br>Ctrl+C나 터미널 종료로는 멈출 수 없다. 화면만 닫히고 이관은 계속된다.</p>                                                                                      |
| `CANCELLED`로 종료                              | `--stop`에 의해 중단된 상태이다. 오류가 아니며, 같은 명령을 재실행하면 멈춘 지점부터 이어서 처리한다.                                                                                                                                                                       |
| 새로 실행한 명령이 `STATUS RUNNING` 또는 HTTP 409로 거부됨 | <p>다른 이관 작업이 실행 중이다. 끝나기를 기다리거나 <code>--stop</code>으로 중단한 뒤 재실행한다.<br><code>--status</code>는 <code>--background</code>로 시작한 작업만 보여주므로, 기본 실행이 돌고 있으면 여기에는 나타나지 않는다. --status 결과의 status가 RUNNING인 것은 백그라운드 작업이 진행 중이라는 뜻으로 정상이다.</p> |
| `STATUS FAILED`로 종료                          | 오류 메시지에 원인이 표시된다. 어느 메트릭·일자에서 멈췄는지는 아래 7.1의 이관 실행 로그 마지막 기록에서 확인할 수 있다. 원본은 보존된 상태이므로 원인을 해소한 뒤 같은 명령을 재실행한다.                                                                                                                        |
| `SDM internal API is not ready`로 실패          | 명령은 SDM이 응답할 때까지 최대 3분 기다린다. SDM이 아직 기동 중이거나 정상 상태가 아닌 경우이므로, SDM이 정상 동작하는지 확인한 뒤 재실행한다.                                                                                                                                             |
| SDM이 재시작됨                                    | 진행 중이던 이관도 함께 멈춘다. 같은 명령을 재실행하면 멈춘 지점부터 이어서 처리한다. 재시작 전의 백그라운드 작업은 --status·--log에 나타나지 않으므로, 진행 기록은 아래 7.1의 이관 실행 로그 파일에서 확인한다.                                                                                                     |
| 진행 상황을 모르겠음                                  | <p>백그라운드로 실행했다면 <code>--log</code>로 진행 상황을 확인한다.<br>처리한 파티션 수와 행 수(<code>migratedPartitions</code>, <code>migratedRows</code>)는 작업이 성공(SUCCESS)으로 끝난 뒤 <code>--status</code> 결과에 표시된다.</p>                                           |

### 7.1 로그 파일 위치

모두 SDM 컨테이너 안의 경로이다.

| 구분            | 경로 · 파일명                                                                                                                   | 내용                                                                                                                                                                                                                |
| ------------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 이관 실행 로그      | <p><code>/sysmaster/logs/timescale-migration/</code><br><code>timescale-metric-migration-{YYYYMMDD\_HHMMSS}.log</code></p> | <p>실행할 때마다 새 파일이 하나 생긴다(기본 실행·백그라운드 동일 형식). 메트릭·일자별 처리 결과가 모두 기록된다.<br>해당 실행의 파일 경로는 백그라운드 실행이면 <code>--log</code> 결과의 <code>JOB\_START</code> 줄에서, 기본 실행이면 실패 시 화면 마지막의 <code>LOG\_FILE</code> 줄에서 확인할 수 있다.</p> |
| SDM 애플리케이션 로그 | `/sysmaster/logs/sdm.v.{version}.log`                                                                                      | 사용한 옵션과 메트릭별 처리 요약이 `[TimescaleMetricMigration]` 태그로 기록된다.                                                                                                                                                        |

{% code collapsedlinecount="10" %}

```
# 파일 목록 확인
docker exec sdm ls -la /sysmaster/logs/timescale-migration/

# 컨테이너 밖으로 꺼내기
docker cp sdm:/sysmaster/logs/timescale-migration/ ./timescale-migration-logs/
```

{% endcode %}

Podman 환경에서는 `docker` 대신 `podman`을 사용한다.

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

`timescale-migration/` 아래 파일은 자동으로 지워지지 않는다. 실행할 때마다 쌓이므로 작업이 끝난 뒤 정리한다. 반면 SDM 애플리케이션 로그는 로그 파일 보관 주기(LOG\_RETENTION\_DAY, 기본 30일)가 지나면 삭제되므로, 그 안의 기록을 남겨야 하면 미리 내려받아 둔다.
{% endhint %}

{% hint style="info" %}
**참고 — 기술지원 문의**

위 절차로 해결되지 않으면 실행한 명령 전문, 화면에 출력된 오류 메시지, `/sysmaster/logs/timescale-migration/` 아래 로그 파일을 함께 전달한다.
{% endhint %}

***

## 8. 완료 확인

다음을 모두 만족하면 작업이 완료된 것이다.

* 마지막 실행 결과의 `remaining_migratable_partitions`(`--status` 결과에서는 `remainingMigratablePartitions`)가 0이다.
* 마지막 실행이 `STATUS SUCCESS`로 끝났다.
* 화면에서 과거 구간의 메트릭이 정상적으로 조회된다.
* 필요한 경우 이관 실행 로그를 별도로 보관했다.

***

## 9. 대상 메트릭

아래가 `--metric`에 쓸 수 있는 이름 전체이다. 원본은 `v83_`, 대상은 `_`를 앞에 붙인 이름이다.

| 분류                                                                                                              | 메트릭명 (`--metric` 값)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 기본 3종                                                                                                           | `cpu`, `memory`, `db_count`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| <p>DB 이벤트 20종<br><code>db\_event\_</code> + 접미사<br>묶음: <code>--metric db\_event</code></p>                      | `db_event_backup`, `db_event_class`, `db_event_cluster`, `db_event_concurrency`, `db_event_dd`, `db_event_ddl`, `db_event_internal`, `db_event_io`, `db_event_psm`, `db_event_recovery`, `db_event_recovery_tac`, `db_event_redo`, `db_event_redo_tac`, `db_event_resource`, `db_event_session`, `db_event_space`, `db_event_sql`, `db_event_sql_tac`, `db_event_standby`, `db_event_xa`                                                                                                                                                                 |
| <p>세션 이벤트 20종<br><code>db\_session\_event\_</code> + 같은 접미사<br>묶음: <code>--metric db\_session\_event</code></p> | `db_session_event_backup`, `db_session_event_class`, `db_session_event_cluster`, `db_session_event_concurrency`, `db_session_event_dd`, `db_session_event_ddl`, `db_session_event_internal`, `db_session_event_io`, `db_session_event_psm`, `db_session_event_recovery`, `db_session_event_recovery_tac`, `db_session_event_redo`, `db_session_event_redo_tac`, `db_session_event_resource`, `db_session_event_session`, `db_session_event_space`, `db_session_event_sql`, `db_session_event_sql_tac`, `db_session_event_standby`, `db_session_event_xa` |

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

사이트에 따라 일부 메트릭은 애초에 수집되지 않아 원본 테이블이 없을 수 있다. 그런 메트릭은 오류가 아니라 건너뛰므로, `--metric` 없이 전체를 한 번에 실행해도 문제되지 않는다. 특정 메트릭만 다시 처리해야 할 때에만 `--metric`을 사용한다.
{% endhint %}