plantpulse-analytics (분석 계층)
역할
대용량 분석 · SQL 쿼리 · 데이터 카탈로그를 담당하는 빅데이터 스택입니다. Cassandra · PostgreSQL · Iceberg(MinIO) 데이터를 분산 분석합니다. pd 기동 순서에서 두 번째 문지기입니다.
| 항목 | 값 |
|---|---|
| 모듈명 | plantpulse-analytics |
| 설치 경로 | /opt/kopens/plantpulse-platform/plantpulse-analytics/ |
| 크기 | 약 4.4GB (플랫폼 중 최대) |
pd 서비스 | analytics — MASTER: spark-master → hive → gravitino → kyuubi / WORKER: spark-worker → kyuubi |
| 계정 | PP_SPARK_USER / PP_SPARK_PASSWORD (클라이언트), PP_HIVE_USER / PP_HIVE_PASSWORD (메타스토어), PP_GRAVITINO_USER / PP_GRAVITINO_PASSWORD (카탈로그 백엔드) |
구성
디렉토리 구조
plantpulse-analytics/
├── spark/ # bin/ (spark-submit · beeline · spark-sql) · conf/ (생성물) · logs/ · work/
├── hive/ # bin/ · conf/hive-site.xml (생성물) · logs/
├── kyuubi/ # bin/ · conf/kyuubi-defaults.conf (생성물) · logs/ · work/
├── gravitino/ # bin/ · conf/gravitino-iceberg-rest-server.conf (생성물) · logs/
└── hadoop/ # 라이브러리 — 단일 노드에서는 HDFS 를 띄우지 않습니다
각 컴포넌트
Spark — 분산 처리 엔진
| 항목 | 값 |
|---|---|
| 포트 | 7077 (마스터 RPC) · 4440 (마스터 UI) · 8081 (워커 UI) |
| 모드 | Standalone. 워커 노드가 붙으면 그 노드의 spark-worker 가 마스터에 등록 |
| 설정 | spark-defaults.conf.template · spark-env.sh.template · metrics.properties.template |
| 워크로드 | Kyuubi 세션의 SQL, 웨어하우스의 Iceberg 아카이브 잡 |
마스터 UI 는 http://<서버IP>:4440/ 입니다(8080 이 아닙니다). Iceberg 카탈로그는 Gravitino 의 REST 엔드포인트(PP_GRAVITINO_ICEBERG_REST_PORT, 19001)를 가리키도록 템플릿이 렌더합니다.
docker exec -it plantpulse-datalake /opt/kopens/plantpulse-platform/plantpulse-analytics/spark/bin/spark-sql --master spark://127.0.0.1:7077
Cassandra → Iceberg 아카이버(plantpulse-warehouse)는 2026-09-06 부터 플랫폼 이미지의 plantpulse-warehouse 컨테이너에서 돕니다. 이 컨테이너에는 그 모듈이 없습니다. 아카이브 잡의 상태는 pd retention 의 cold_tier · archive_job 줄로 봅니다 → warehouse 모듈
Hive Metastore
| 항목 | 값 |
|---|---|
| 포트 | 9083 (thrift) |
| 백엔드 | PostgreSQL DB hive-metastore-230 (PP_HIVE_DB), 계정 hive |
| 설정 | hive-site.xml.template (hive 와 spark 두 곳으로 렌더) |
PP_HIVE_PASSWORD 는 값 하나가 양방향입니다 — 메타스토어가 PostgreSQL 에 접속할 때 제시하고, 클라이언트가 Kyuubi 에 접속해 올 때 hive-auth.properties 로 검증합니다. 그래서 passwd.sh 가 계정 변경과 재렌더를 둘 다 합니다.
Kyuubi — SQL 게이트웨이
JDBC / Thrift 로 SQL 클라이언트(DBeaver · Tableau · 데이터 게이트웨이)가 Spark 에 접속하는 문입니다. 세션 격리와 큐잉을 제공합니다.
| 항목 | 값 |
|---|---|
| 포트 | 10000 (thrift) · 10099 (웹 UI) |
| 설정 | kyuubi-defaults.conf.template |
| 인증 | hive-auth.properties — 계정 PP_SPARK_USER / PP_SPARK_PASSWORD 를 이 파일이 만듭니다 |
docker exec -it plantpulse-datalake bash -c \
'/opt/kopens/plantpulse-platform/plantpulse-analytics/spark/bin/beeline -u "jdbc:hive2://127.0.0.1:10000/default" -n "$PP_SPARK_USER" -p "$PP_SPARK_PASSWORD"'
기동 순서에서 Kyuubi 가 마지막이라, 기동 직후 pd status 에 PP_ANALYTICS[KYUUBI] STOPPED 가 몇십 초 보이는 것은 정상입니다.
Gravitino — Iceberg REST 카탈로그
Iceberg 테이블의 카탈로그 서버입니다. MASTER 에서만 뜨고, 워커의 Spark 는 마스터의 것을 바라봅니다.
| 항목 | 값 |
|---|---|
| 포트 | 19001 (REST API) — 웹 화면은 없습니다. / 는 404 를 답합니다 |
| 백엔드 | PostgreSQL 계정 gravitino (PP_GRAVITINO_PASSWORD) |
| 설정 | gravitino-iceberg-rest-server.conf.template |
통합 운영
docker exec plantpulse-datalake pd status analytics
docker exec plantpulse-datalake pd restart analytics # 실행 중인 SQL · Spark 잡이 전부 중단됩니다
docker exec plantpulse-datalake pd logs --lines 100 analytics
아카이브 잡이 도는 중이면(pd retention 의 archive_job 이 NA + «running») 끝난 뒤 재시작하세요.
자주 사용하는 쿼리
-- Cassandra 직접 조회 (Spark SQL)
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 (콜드 티어)
USE iceberg;
SHOW TABLES;
SELECT count(*), min(time), max(time) FROM tw_tag_point WHERE dt BETWEEN '2026-01-01' AND '2026-05-30';
로그
docker exec plantpulse-datalake pd logs --list | grep -i "spark\|hive\|kyuubi\|gravitino"
자주 발생하는 문제
| 증상 | 원인 | 조치 |
|---|---|---|
| Spark 잡 OutOfMemory | executor 메모리 부족 | spark-defaults.conf.template 의 spark.executor.memory |
| Kyuubi 가 영영 안 뜸 | 코어 수가 실제보다 큼 | 호스트의 DOCKER_PP_CLUSTER_CORES 가 컨테이너에 전달되는지 — 16 vCPU 박스가 30 코어를 믿으면 이렇게 됩니다 |
| Kyuubi 세션 타임아웃 | idle 세션 누적 | kyuubi.session.idle.timeout |
| 메타스토어 연결 실패 | PostgreSQL 다운 · hive 비밀번호 불일치 | pd status storage, passwd.sh PP_HIVE_PASSWORD |
| Iceberg 작은 파일 적체 | optimize 미실행 | 웨어하우스 컨테이너의 최적화 잡 → warehouse 모듈 |
| Spark UI 접근 안 됨 | 방화벽 | 4440 |
튜닝 포인트
| 항목 | 템플릿 | 권장 |
|---|---|---|
| Spark executor memory | spark-defaults.conf.template | 호스트 메모리의 25 ~ 50% |
| Spark cores | PP_CLUSTER_CORES (호스트 DOCKER_PP_CLUSTER_CORES) | 호스트 코어 − 2 (자동) |
| Kyuubi engine 공유 수준 | kyuubi-defaults.conf.template | kyuubi.session.engine.share.level=USER |
자세한 튜닝은 성능 튜닝을 참고하세요.
관련 문서
- 데이터레이크 개요
- warehouse 모듈 — Iceberg 아카이브
- plantpulse-data-gateway — SQL 콘솔