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

# timeseries (시계열)

## 역할

시계열 데이터 전용 처리 엔진과 시각화 UI를 제공합니다. Cassandra 의 raw 시계열을 다운샘플링 / 집계 / 캐싱하여 대시보드 쿼리 응답성을 보장합니다.

| 항목    | 값                                                        |
| ----- | -------------------------------------------------------- |
| 모듈명   | `plantpulse-timeseries`                                  |
| 설치 경로 | `/opt/kopens/plantpulse-platform/plantpulse-timeseries/` |
| 엔진 포트 | **7800** (HTTP), 7801 (TLS)                              |
| UI 포트 | **3000**                                                 |

## 구성

```mermaid
graph LR
  KAFKA[Kafka<br/>pp-tag-point] --> TSE[Time-Series Engine<br/>:7800]
  TSE --> CASS[(Cassandra)]
  TSE --> CACHE[(Valkey)]
  TSE --> UI[Time-Series UI<br/>:3000]
  UI --> BROWSER[브라우저]
  SVR[plantpulse-server] --> TSE
```

## 디렉토리 구조

```
plantpulse-timeseries/
├── engine/                       # 시계열 엔진 (Java)
│   ├── bin/start.sh stop.sh log-viewer.sh
│   ├── conf/
│   │   ├── application.properties
│   │   ├── engine.properties
│   │   └── storage.properties
│   ├── lib/
│   └── logs/system.log
└── dashboard/                    # 시각화 UI (Grafana 기반)
    ├── bin/
    ├── conf/grafana.ini
    ├── data/
    └── logs/
```

## 시계열 엔진 (port 7800)

### 주요 책임

* Kafka `pp-tag-point` 토픽 구독 → Cassandra 시계열 테이블 쓰기
* 다운샘플링 (1초 → 1분 → 1시간 → 1일)
* 시계열 쿼리 REST API 제공
* Valkey 캐시 적중률 관리

### 핵심 설정 (`engine/conf/engine.properties`)

```properties
tse.kafka.bootstrap=${PP_KAFKA_HOST}:${PP_KAFKA_PORT}
tse.kafka.topic=${PP_TOPIC_PREFIX}-tag-point
tse.kafka.group=timeseries-engine

tse.cassandra.contact=${PP_CASSANDRA_HOST}
tse.cassandra.keyspace=${PP_KEYSPACE}
tse.cassandra.user=${PP_CASSANDRA_USER}
tse.cassandra.password=${PP_CASSANDRA_PASSWORD}

tse.downsample.intervals=1m,1h,1d
tse.downsample.workers=8

tse.cache.host=${PP_REDIS_HOST}
tse.cache.ttl.seconds=60
```

### 주요 API

```bash
# 헬스체크
curl -fsS http://127.0.0.1:7800/api/health

# 태그 시계열 조회 (Raw)
curl -fsS "http://127.0.0.1:7800/api/v1/tags/TAG_001/values?from=2026-05-30T00:00:00&to=2026-05-30T23:59:59"

# 집계 조회 (1시간 평균)
curl -fsS "http://127.0.0.1:7800/api/v1/tags/TAG_001/aggregate?interval=1h&fn=avg&from=...&to=..."

# 최신 값
curl -fsS "http://127.0.0.1:7800/api/v1/tags/TAG_001/latest"
```

## Time-Series UI (port 3000)

Grafana 기반 시각화 대시보드. 기본 계정 `admin / kopens123!` (`PP_GRAFANA_ADMIN_PASSWORD`).

| URL                        | 용도   |
| -------------------------- | ---- |
| `http://[HOST]:3000/`      | 대시보드 |
| `http://[HOST]:3000/login` | 로그인  |

### 사전 정의 대시보드

* **Plant Overview** — 전체 공장 현황
* **Asset Detail** — 에셋별 시계열
* **Cassandra Health** — 시계열 DB 운영 지표
* **Kafka Lag** — 메시지 적체

## 운영 명령

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

./restart-timeseries.sh    # 엔진 + UI 함께 재시작
./status.sh                # 7800 / 3000 RUNNING 확인
./log-viewer.sh            # 통합 로그
```

## 자주 발생하는 문제

| 증상             | 원인          | 조치                                               |
| -------------- | ----------- | ------------------------------------------------ |
| Kafka lag 증가   | 엔진 처리 부족    | `engine.downsample.workers` 상향, Cassandra I/O 점검 |
| 대시보드 응답 느림     | 캐시 미적용      | `tse.cache.ttl.seconds` 조정, 시간 범위 단축             |
| Grafana 로그인 실패 | 비밀번호 미초기화   | `PP_GRAFANA_ADMIN_PASSWORD` 환경변수 확인              |
| 다운샘플링 지연       | 적체된 raw 데이터 | 수동 backfill 또는 worker 증가                         |

## 관련 문서

* [모듈 인덱스](/plantpulse-platform/admin/modules.md)
* [데이터 처리 플로우](/plantpulse-platform/developer/data-flow.md)
* [성능 튜닝](/plantpulse-platform/admin/performance-tuning.md)