> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/admin/modules/analytics.md).

# analytics (분석)

## 역할

대용량 분석 / SQL 쿼리 / 데이터 카탈로그를 담당하는 빅데이터 스택. **데이터 웨어하우스 / 레이크하우스의 핵심**으로, Cassandra / Iceberg 데이터를 분산 분석합니다.

| 항목    | 값                                                       |
| ----- | ------------------------------------------------------- |
| 모듈명   | `plantpulse-analytics`                                  |
| 설치 경로 | `/opt/kopens/plantpulse-platform/plantpulse-analytics/` |
| 크기    | 약 4.4GB (플랫폼 중 최대)                                      |

## 구성

```mermaid
graph TB
  subgraph CLIENT["클라이언트"]
    SQLC[SQL 쿼리]
    JDBC[JDBC / Thrift]
    UI[Spark UI :4440]
  end

  subgraph ANL["plantpulse-analytics"]
    KY[Kyuubi :10000<br/>SQL Gateway]
    SP[Spark Master :7077<br/>Spark Workers]
    HV[Hive Metastore :9083<br/>스키마 카탈로그]
    GR[Gravitino :19001<br/>통합 카탈로그]
    HD[Hadoop HDFS]
  end

  subgraph DATA["데이터 소스"]
    CASS[(Cassandra<br/>시계열)]
    PG[(PostgreSQL<br/>메타)]
    MN[(MinIO<br/>Iceberg)]
  end

  SQLC --> KY
  JDBC --> KY
  KY --> SP
  SP --> HV
  HV --> GR
  GR --> MN
  SP --> CASS
  SP --> PG
  SP --> MN
  HV --> HD
  UI -.-> SP
```

## 디렉토리 구조

```
plantpulse-analytics/
├── spark/                          # Apache Spark 3.5+
│   ├── bin/                        # spark-submit, beeline, pyspark
│   ├── conf/spark-defaults.conf
│   ├── conf/spark-env.sh
│   ├── conf/log4j2.properties
│   ├── data/
│   ├── jars/
│   ├── logs/
│   └── work/
├── hive/                            # Apache Hive 4
│   ├── bin/
│   ├── conf/hive-site.xml
│   ├── lib/
│   ├── jdbc/
│   └── logs/
├── kyuubi/                          # Apache Kyuubi (SQL gateway)
│   ├── bin/
│   ├── conf/kyuubi-defaults.conf
│   ├── conf/log4j2.xml
│   ├── jars/
│   ├── jars-ext/
│   ├── externals/
│   ├── web-ui/
│   └── logs/
├── gravitino/                       # Apache Gravitino (통합 카탈로그)
│   ├── bin/
│   ├── conf/gravitino.conf
│   ├── catalogs/
│   ├── libs/
│   └── logs/
└── hadoop/                          # Hadoop HDFS
    ├── bin/
    ├── etc/hadoop/
    ├── lib/
    └── logs/
```

## 각 컴포넌트 상세

### Apache Spark — 분산 처리 엔진

| 항목       | 값                                                 |
| -------- | ------------------------------------------------- |
| 포트       | 7077 (Master), 4440 (Master UI), 8081 (Worker UI) |
| 모드       | Standalone (단일 노드) / Master-Worker (클러스터)         |
| 사용자 워크로드 | warehouse 모듈의 Iceberg 아카이빙, 임의 SQL, ML            |

#### 핵심 설정 (`spark/conf/spark-defaults.conf`)

```properties
spark.master                    spark://${PP_HOST_IP}:7077
spark.eventLog.enabled          true
spark.eventLog.dir              /data1/pp-data/spark-events
spark.history.fs.logDirectory   /data1/pp-data/spark-events

spark.driver.memory             4g
spark.executor.memory           4g
spark.executor.cores            ${PP_CLUSTER_CORES}
spark.cores.max                 ${PP_CLUSTER_CORES}

# Iceberg / Hive 통합
spark.sql.extensions            org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions
spark.sql.catalog.iceberg       org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.iceberg.type  hive
spark.sql.catalog.iceberg.uri   thrift://${PP_HIVE_HOST}:${PP_HIVE_PORT}
```

#### 운영 명령

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-analytics/spark

# Master UI
# http://[HOST]:4440/

# Spark SQL 셸
./bin/spark-sql --master spark://${PP_HOST_IP}:7077

# Beeline (Hive JDBC)
./bin/beeline -u "jdbc:hive2://${PP_HOST_IP}:10000"

# Job 제출
./bin/spark-submit --master spark://${PP_HOST_IP}:7077 \
  --class plantpulse.warehouse.Archive \
  /opt/kopens/plantpulse-platform/plantpulse-warehouse/lib/plantpulse-warehouse.jar
```

### Apache Hive — 메타스토어

Spark 와 Kyuubi 가 사용하는 스키마 카탈로그. PostgreSQL 의 `hive-metastore-230` DB 에 메타데이터 저장.

| 항목             | 값                         |
| -------------- | ------------------------- |
| Metastore 포트   | 9083                      |
| HiveServer2 포트 | 10000 (Kyuubi 에서 통합)      |
| 백엔드 DB         | PostgreSQL (`PP_HIVE_DB`) |

#### 핵심 설정 (`hive/conf/hive-site.xml`)

```xml
<configuration>
  <property>
    <name>javax.jdo.option.ConnectionURL</name>
    <value>jdbc:postgresql://${PP_POSTGRES_HOST}:${PP_POSTGRES_PORT}/hive-metastore-230</value>
  </property>
  <property>
    <name>javax.jdo.option.ConnectionUserName</name>
    <value>${PP_HIVE_USER}</value>
  </property>
  <property>
    <name>javax.jdo.option.ConnectionPassword</name>
    <value>${PP_HIVE_PASSWORD}</value>
  </property>
  <property>
    <name>hive.metastore.warehouse.dir</name>
    <value>s3a://plantpulse-iceberg/warehouse/</value>
  </property>
</configuration>
```

### Apache Kyuubi — 분산 SQL 게이트웨이

JDBC / Thrift 로 SQL 클라이언트 (DBeaver, Tableau, Apache Superset 등) 가 Spark 에 접속하는 게이트웨이. 멀티 테넌시 / 세션 격리 / 큐잉을 제공합니다.

| 항목        | 값     |
| --------- | ----- |
| Thrift 포트 | 10000 |
| Web UI 포트 | 10099 |
| 백엔드 엔진    | Spark |

#### 운영

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-analytics/kyuubi

# 상태 / 세션 확인
./bin/kyuubi-ctl list session

# Beeline 클라이언트 접속
./bin/beeline -u "jdbc:hive2://${PP_HOST_IP}:10000/default" \
  -n ${PP_HIVE_USER} -p ${PP_HIVE_PASSWORD}

# 예제 쿼리
0: jdbc:hive2://...> SHOW DATABASES;
0: jdbc:hive2://...> USE iceberg;
0: jdbc:hive2://...> SHOW TABLES;
0: jdbc:hive2://...> SELECT count(*) FROM tag_point WHERE dt='2026-05-30';
```

### Apache Gravitino — 통합 데이터 카탈로그

Hive Metastore, JDBC, S3 등 다양한 데이터 소스의 메타데이터를 통합 관리하는 카탈로그.

| 항목     | 값                                             |
| ------ | --------------------------------------------- |
| 포트     | 19001                                         |
| Web UI | `http://[HOST]:19001/`                        |
| 인증     | `PP_GRAVITINO_USER` / `PP_GRAVITINO_PASSWORD` |

```bash
# API 로 카탈로그 목록
curl -fsS -u gravitino:gravitino123! http://localhost:19001/api/metalakes
```

### Hadoop HDFS — 분산 파일 시스템

Spark 의 임시 데이터, Hive 의 외부 테이블 저장에 사용. 단일 노드 환경에서는 로컬 파일시스템 또는 MinIO 로 대체 가능합니다.

## 통합 운영 명령

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-startup

./restart-analytics.sh    # 분석 모듈 전체 재시작
./status.sh               # 7077 / 10000 / 19001 RUNNING 확인
```

> **재시작 영향**: 분석 모듈 재시작 시 실행 중인 모든 SQL / Spark job 이 중단됩니다. `warehouse/s3/archive.sh` 등 정기 배치가 동작 중이면 완료 후 재시작해 주세요.

## 자주 사용하는 쿼리

### 시계열 데이터 집계 (Spark SQL)

```sql
-- 어제 하루의 일별 시간당 평균 (Cassandra 직접 조회)
SELECT date_format(time, 'yyyy-MM-dd HH:00') AS hour,
       avg(value) AS avg_value
FROM cassandra.pp.tm_tag_point
WHERE tag_id = 'TAG_001' AND time >= date_sub(current_date(), 1)
GROUP BY 1
ORDER BY 1;
```

### Iceberg 테이블 조회

```sql
USE iceberg;
SHOW TABLES;
DESCRIBE TABLE tag_point;

SELECT count(*), min(time), max(time)
FROM tag_point
WHERE dt BETWEEN '2026-01-01' AND '2026-05-30';
```

### Iceberg 테이블 최적화 (warehouse 모듈에서)

```bash
/opt/kopens/plantpulse-platform/plantpulse-warehouse/s3/optimize.sh
```

## 로그 위치

| 컴포넌트                  | 로그                          |
| --------------------- | --------------------------- |
| Spark Master / Worker | `spark/logs/system.log`     |
| Hive Metastore        | `hive/logs/system.log`      |
| Kyuubi                | `kyuubi/logs/system.log`    |
| Gravitino             | `gravitino/logs/system.log` |
| Hadoop                | `hadoop/logs/`              |

## 자주 발생하는 문제

| 증상                    | 원인              | 조치                               |
| --------------------- | --------------- | -------------------------------- |
| Spark Job OutOfMemory | executor 메모리 부족 | `spark.executor.memory` 상향       |
| Kyuubi 세션 타임아웃        | idle session 누적 | `kyuubi.session.idle.timeout` 단축 |
| Hive Metastore 연결 실패  | PostgreSQL 다운   | `node-psql.sh` 로 확인 후 storage 점검 |
| Iceberg 테이블 작은 파일 적체  | optimize 미실행    | `warehouse/s3/optimize.sh` 정기 실행 |
| Spark UI 접근 안 됨       | 방화벽 / 포트 충돌     | 4440 포트 확인, \`ss -tlnp           |
| Hadoop safe mode      | 비정상 종료 후        | `hdfs dfsadmin -safemode leave`  |

## 튜닝 포인트

| 항목                       | 위치                     | 권장                                       |
| ------------------------ | ---------------------- | ---------------------------------------- |
| Spark executor memory    | `spark-defaults.conf`  | 호스트 메모리의 25\~50%                         |
| Spark cores per executor | `spark-defaults.conf`  | 호스트 코어의 50\~70%                          |
| Kyuubi engine pool       | `kyuubi-defaults.conf` | `kyuubi.session.engine.share.level=USER` |
| Hive Metastore JVM       | `hive-env.sh`          | 2\~4GB                                   |
| Gravitino 캐시             | `gravitino.conf`       | `gravitino.entity.cache.enabled=true`    |

자세한 튜닝은 [성능 튜닝](/plantpulse-platform/admin/performance-tuning.md) 페이지를 참고해 주세요.

## 관련 문서

* [모듈 인덱스](/plantpulse-platform/admin/modules.md)
* [warehouse 모듈](https://dev.kopens.io/plantpulse-platform/plantpulse-docs/-/blob/master/admin/modules/warehouse.md)
* [성능 튜닝](/plantpulse-platform/admin/performance-tuning.md)
* [문제 해결](/plantpulse-platform/admin/troubleshooting.md)