이 레포가 무엇을 하는 물건인가.
비행기 조종석에는 고도·속도·연료를 보여주는 계기판이 빼곡하다. logos-node-dashboard는 블록체인 노드라는 비행기를 위한 그 계기판 전체 세트를 — 화면(익스플로러)부터 센서 배선(관측 스택)까지 — 한 번에 설치해준다.
이 프로젝트는 Logos(코드명 Nomos/Cryptarchia) 테스트넷 노드를 운영하는 사람을 위한 것이다. 노드를 돌리다 보면 "지금 블록 높이가 얼마지?", "피어는 몇 명 붙었지?", "CPU·메모리는 괜찮나?", "에러 로그가 뜨나?" 같은 질문이 끝없이 생긴다. 보통은 이걸 보려고 도구를 하나씩 설치·연결해야 하는데, 이 레포는 그 9개 도구를 docker-compose 파일 하나에 미리 배선해 두었다.
두 가지가 한 묶음으로 들어 있는 게 특징이다. ① 블록 익스플로러 — 블록·트랜잭션을 디코딩해 보여주고, 피어를 3D 지구본에 찍고, 테스트넷 토큰 faucet(수도꼭지)까지 돌리는 전용 웹 UI(localhost:3333). ② 옵저버빌리티 스택 — 시스템 메트릭·로그·트레이스를 모아 Grafana로 보는 모니터링(localhost:3000). 보통 따로 노는 이 둘을 한 레포에 합친 게 신선하다.
트렌딩 이유 · 셀프호스팅/관측 측면 강점.
가장 큰 매력은 "클라우드·SaaS 없이 내 노트북·라즈베리파이에서 완결되는 풀스택 관측 예제"라는 점이다. OpenTelemetry → Prometheus/Loki/Tempo → Grafana로 이어지는 현대 관측 파이프라인을, 추상적 설명이 아니라 실제로 돌려보며 배울 수 있게 통째로 묶었다. 관측 스택을 처음 공부하는 사람에게 최적의 놀이터다.
| 항목 | 흔한 방식 | logos-node-dashboard |
|---|---|---|
| 설치 | 도구마다 따로 설치·연결 | docker compose up 한 방에 9서비스 기동 |
| 관측 범위 | 메트릭만(Grafana 모니터링) | 메트릭+로그+트레이스 3종 + 블록 익스플로러 |
| 재현성 | 버전 제각각 | 이미지 버전 핀 고정 + 설정을 코드로 선언 |
| 비용 | SaaS 구독 | 전부 오픈소스 셀프호스팅(무료) |
| 보안 기본값 | 종종 0.0.0.0 노출 | 모든 포트 127.0.0.1 바인딩 + 읽기전용 마운트 |
또 하나 배울 점은 "불완전한 데이터로 정직한 UI를 만드는 법"이다. 이 노드는 살아있는 피어 IP 목록을 API로 주지 않는다. 그래서 개발자는 노드 로그 파일에서 IP를 긁어 피어를 발견하고, "로그 갱신 지연(lag)" 기반으로 online/offline을 추정하는 로직을 따로 문서화(docs/PEER_STATUS_LOGIC.md)했다. 실무에서 흔한 "데이터가 부족한데 그럴듯하게 속이지 않고 정직하게 표시하기"의 좋은 사례다.
블록체인 노드를 돌려도 터미널 로그가 주르륵 흐를 뿐, 블록 높이·동기화 진행률·피어 수·리소스 사용량을 한눈에 보기 어렵다. 모니터링을 붙이려면 Prometheus·Grafana·Loki를 각각 설치하고 설정 파일을 일일이 연결해야 하는데, 이 배선이 초보자에겐 큰 벽이다.
9개 컨테이너의 연결·포트·볼륨·의존 관계가 docker-compose.yml 한 곳에 선언돼 있고, Grafana 데이터소스·대시보드까지 코드로 자동 등록(provisioning)된다. 클릭 한 번 없이 "켜면 바로 관제실이 차려지는" 구조라, 사용자는 파이프라인이 어떻게 맞물리는지를 동작하는 상태로 관찰할 수 있다.
프론트 · 백엔드 · 데이터 · 관측 스택 한눈에.
크게 네 묶음이다 — ① 화면(Next.js 익스플로러), ② 자체 백엔드(Python 인덱서·사이드카), ③ 저장소(TimescaleDB), ④ 관측 스택(OTel·Prometheus·Grafana·Loki·Tempo). 버전이 거의 다 핀(pin) 고정돼 있어 재현·교육에 좋다.
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| 프론트엔드 | Next.js 14.2 (App Router) · React 18 · TypeScript 5.6 · Tailwind 3.4 | 블록 익스플로러 UI + 서버 /api 라우트. |
| 데이터 패칭 | SWR 2.2 (useLive 훅, 2초 폴링) · Recharts · react-simple-maps | 실시간 갱신 · 차트 · 피어 3D 지구본. |
| 인덱서 | Python 3.12 + psycopg2 (의존성 사실상 1개) | 노드 API를 3초마다 폴링 → TimescaleDB 적재. |
| 사이드카 | Python (pip 의존성 0개) + RocksDB ldb CLI | 노드 DB를 읽기전용으로 읽어 블록 원본 파싱·제공. |
| 저장소 | TimescaleDB (PostgreSQL 16 + 시계열 확장) | 블록·스냅샷을 하이퍼테이블+연속집계로 저장. |
| 관측 수집 | OTel Collector contrib 0.100 (OTLP 4317/4318) | 3종 신호를 받아 metrics/logs/traces로 분기. |
| 메트릭 | Prometheus v2.53 (9090, retention 30d) + node-exporter | 시계열 메트릭 수집(scrape) + 호스트 시스템 지표. |
| 로그·트레이스 | Loki 3.1 · Tempo 2.5 | 로그 집계 · 분산 트레이스 저장. |
| 시각화 | Grafana 11.1 (데이터소스 4종 자동 프로비저닝) | 대시보드 6종(overview/system/consensus/network/blockchain/wallet). |
| 인프라 | Docker Compose v2 (멀티스테이지 빌드 · 메모리/CPU 캡) | 9서비스 오케스트레이션 + 데이터 볼륨 보존. |
데이터가 노드에서 화면까지 어떻게 흐르는가.
이 시스템에는 목적이 다른 두 개의 데이터 경로가 한 compose 안에 공존한다. (A) 블록·트랜잭션을 보여주는 익스플로러 경로, (B) 시스템 건강을 보여주는 관측 경로. 먼저 독수리 시점으로 전체 그림을 보자.
이제 대표 흐름 한 줄기를 따라가자 — "노드 메트릭이 Grafana 그래프에 찍히기까지". 여기엔 초보자가 자주 헷갈리는 "push인데 pull로 바뀌는" 다리가 있다.
핵심은 ③④다. OTel은 데이터를 밀어 보내는(push) 방식인데, Prometheus는 끌어오는(pull/scrape) 방식이다. 둘을 잇기 위해 Collector가 받은 메트릭을 :8889에 Prometheus 형식으로 다시 펼쳐 놓고, Prometheus가 그걸 긁어간다. "택배(push)로 받은 물건을 진열대(:8889)에 올려두면, 손님(Prometheus)이 정기적으로 와서 가져가는(pull)" 구조다.
또 하나의 핵심 설계는 인덱서의 폴링 주기 분할이다. 모든 작업을 매번 다 하면 노드에 부하가 몰린다. 그래서 indexer.py는 3초 사이클을 돌되 작업마다 주기를 다르게 둔다:
# indexer.py — 작업별로 주기를 나눠 부하 분산 (3초 사이클)
매 사이클 : cryptarchia/info(높이·슬롯) , network/info(피어 수)
3사이클(~9s) : cryptarchia/headers → blocks 적재 (같은 높이 다른 해시 = reorg)
10사이클(~30s): 노드 로그 tail로 피어 IP 추출 → 신규만 지오로케이션
200사이클(~10m): 시간당 통계 롤업이 프로젝트 특유의 관례: 설정을 최대한 코드로 선언한다. Grafana 데이터소스·대시보드도 클릭이 아니라 YAML/JSON 파일로 자동 등록되고(grafana/provisioning/), 보안을 위해 공개 포트를 모두 127.0.0.1에 묶고 사이드카는 RocksDB를 읽기전용으로만 연다. "설정을 손이 아니라 git으로 관리"하는 GitOps식 사고가 곳곳에 배어 있다.
:8889 노출, pull)으로 변환한다. 표준 프로토콜로 받아 표준 도구에 넘기는 "어댑터"의 실전 예다./api/* 라우트가 대신 접근해 결과만 내려준다. 그래서 DB 비밀번호·노드 주소가 브라우저에 노출되지 않는다. "프론트 전용 백엔드"를 한 겹 두는 보안·구조 패턴.어디부터 열어봐야 하나.
최상위에 오케스트레이션 파일들(compose·스크립트)이 있고, 그 아래로 ① app/(화면) ② indexer/·sidecar/(백엔드) ③ 각 관측 도구별 설정 폴더가 평평하게 놓여 있다. 처음엔 docker-compose.yml 하나만 읽어도 전체 배선이 보인다.
| 위치 | 역할 |
|---|---|
docker-compose.yml | 전체 배선의 단일 진실원. 9서비스의 이미지·포트·볼륨·의존·리소스 캡이 다 여기. 첫 정독 대상. |
otel-collector/config.yaml | 관측의 심장. receiver→processor→exporter 3단과 metrics/logs/traces 3개 파이프라인이 한 파일에서 갈라진다. |
indexer/indexer.py | 노드 API를 폴링해 DB에 적재. 주기 분할·reorg(고아블록) 감지·로그 tail의 실전 패턴. |
indexer/init.sql | TimescaleDB 스키마. create_hypertable·연속집계·retention 정책을 SQL로 본다. |
grafana/provisioning/ | 데이터소스 4종(Prometheus·Loki·Tempo·TimescaleDB)과 대시보드를 코드로 자동 등록. |
app/src/lib/ | DB 풀·노드 클라이언트·트랜잭션 디코더. 프론트가 데이터를 어떻게 가져오는지의 핵심. |
이 레포에서 배울 만한 것 + 어느 파일을 펴면 되는지.
otel-collector/config.yaml 하나에서 receiver→processor→exporter 3단과 metrics/logs/traces 3개 파이프라인이 어떻게 분기하는지 본다. memory_limiter·batch·attributes 프로세서의 역할이 손에 잡힌다. 실습: attributes에 새 라벨을 추가하고 Grafana에서 확인.
prometheus/prometheus.yml로 "끌어오는(pull)" 수집 방식, scrape_configs·라벨·retention을 익힌다. 특히 OTel이 push한 메트릭을 Prometheus가 다시 pull하는 브리지 패턴이 백미. 대시보드 JSON에서 rate()·histogram_quantile() PromQL 실전 예제를 본다.
grafana/provisioning/의 YAML이 Prometheus·Loki·Tempo·TimescaleDB 4종 데이터소스와 대시보드를 자동 등록한다. 클릭으로 만든 설정은 재현이 안 되지만, 코드로 선언하면 git으로 관리·복원된다 — GitOps식 운영의 표본. 실습: dashboards/에 새 JSON을 넣고 자동 로드 확인.
메트릭만으로는 "왜"를 모른다. Loki의 LogQL({service="logos-node"} |= "ERROR")로 로그를, Tempo로 트레이스를 보며 세 신호를 연결(correlation)하는 감각을 배운다. 숫자→글→경로로 좁혀 들어가는 디버깅의 정석.
빌드 vs 이미지, expose vs ports(127.0.0.1 바인딩), depends_on/healthcheck, named volume로 데이터 보존, deploy.resources.limits로 메모리 캡, override 파일(-f dev.yml)로 hot-reload까지 — 실전 compose의 거의 모든 요소가 한 파일에 있다. 실습: 코어-온리(up timescaledb indexer sidecar explorer)만 띄워보기.
/api/*를 BFF로 두고 비밀을 서버에만 두는 구조, SWR useLive 폴링, 동적 라우트([height]·[hash])를 익힌다. 백엔드 쪽은 폴링 주기 분할, 로그 tailing(오프셋 기억), reorg 감지 같은 "불완전 데이터 다루기" 패턴을 본다.
예컨대 전부 띄우지 않고 익스플로러 핵심만 가볍게 돌려보려면, 코어 서비스 4개만 지정하면 된다:
# 관측 스택 없이 익스플로러만 — 가볍게 첫 구동
docker compose up -d timescaledb indexer sidecar explorer
# 잘 뜨면 localhost:3333 접속 → 이후 풀스택으로 확장돌리려면 무엇이 필요한가.
특별한 하드웨어는 필요 없다 — 라즈베리파이에서도 돈다. 진짜 전제 조건은 도달 가능한 Logos 노드(HTTP API + RocksDB·로그를 호스트에서 읽을 수 있어야 함)와 약간의 수동 설정이다.
| 항목 | 요구사항 |
|---|---|
| 공통 | Docker + Docker Compose v2, 풀스택 기준 약 2GB 여유 RAM. |
| 노드 연결 | 실행 중인 Logos 노드(API :8080 도달 + state/db RocksDB·로그를 호스트에서 읽기 가능). |
| 메모리 캡 | prometheus·timescaledb 각 1G, explorer·otel 각 512M, loki·tempo 각 512M, sidecar 256M, indexer 128M. |
| 라즈베리파이 | 64-bit OS 필수. Pi(4GB)는 코어-온리, Pi 5(8GB)는 풀스택. DB를 microSD 말고 USB3 SSD/NVMe에. |
| 필수 수동 설정 | compose의 인덱서/사이드카 노드 데이터 마운트 경로를 자기 환경으로 수정(원문은 작성자 로컬 경로 하드코딩). |
| 관측 켜기 | node-config-patch.yaml을 노드 설정에 병합해야 OTLP/로그/metrics가 흐른다. |
이 레포는 '계기판 키트'다. 자동차(=노드)는 따로 있어야 하고, 키트의 센서 배선(데이터 마운트 경로·텔레메트리 설정)을 내 차에 맞게 연결해줘야 계기판에 바늘이 움직인다. 키트 자체는 가볍지만, "내 차에 맞춰 꽂는" 한 단계가 빠지면 화면이 비어 있다.
읽기만 하지 말고 손에 익히는 단계.
timescaledb indexer sidecar explorer만 올려 localhost:3333을 연다. 관측 스택 없이도 익스플로러가 도는 걸 확인한 뒤 풀스택으로 확장. compose가 서비스 단위로 켜진다는 감각을 먼저 잡는다.
Grafana(:3000)에서 node_load1 패널을 새로 추가하고, Explore에서 {service="logos-node"} |= "ERROR" 로그를 조회한다. 메트릭과 로그가 어떻게 다르게 보이는지 체감하는 단계.
prometheus.yml의 retention을 7d로 바꾸고 재기동해 TSDB 변화를 관찰한다. 이어 otel-collector/config.yaml의 attributes 프로세서에 라벨 하나를 추가하고, 그게 Prometheus 라벨로 노출되는지 확인한다.
indexer/init.sql에 "시간당 블록 수" 같은 연속집계(continuous aggregate)를 만들고 갱신 정책을 붙인다. Grafana의 TimescaleDB 데이터소스나 /api에서 조회해, 시계열 DB가 요약을 미리 계산해 두는 이점을 본다.
app/src/lib/tx.ts에 새 opcode 디코딩을 추가하거나, "슬롯별 통계" 같은 새 /api 라우트 + 페이지를 만들어 useLive로 실시간 표시한다. dev 오버라이드(-f docker-compose.dev.yml)로 hot-reload 개발을 경험.
docs/PEER_STATUS_LOGIC.md를 읽고 peers/page.tsx의 online/offline 임계값을 자기 노드의 로그 주기에 맞게 조정한다. "불완전한 데이터로 정직한 상태를 표시하는" 설계를 직접 다뤄보는, 이 레포의 백미 실습.
한 주씩 따라가는 6주 계획.
| 주차 | 주제 | 학습 자료 |
|---|---|---|
| 1주차 | Docker Compose 기본 + 이 레포 전체 기동 | README + docker-compose.yml + 실습 1 |
| 2주차 | Prometheus·PromQL — pull 모델과 메트릭 | Prometheus 공식 문서 · prometheus.yml · 대시보드 JSON + 실습 2 |
| 3주차 | OpenTelemetry Collector — 3종 신호 파이프라인 | OTel 문서 · otel-collector/config.yaml + 실습 3 |
| 4주차 | Grafana 프로비저닝 + Loki/Tempo 로그·트레이스 | Grafana provisioning 문서 · grafana/ · LogQL |
| 5주차 | TimescaleDB — 하이퍼테이블·연속집계·retention | Timescale 문서 · indexer/init.sql + 실습 4 |
| 6주차 | Next.js App Router(BFF) + 데이터 엔지니어링 패턴 | Next.js 문서 · app/src/ · indexer.py + 실습 5·6 |
본문에 나온 용어 빠른 참조.
| 용어 | 의미 |
|---|---|
| 옵저버빌리티 | 시스템 내부를 바깥에서 들여다보는 능력. 메트릭+로그+트레이스 3종 신호로 구성. |
| OTel Collector | 관측 데이터를 받아(receiver)·가공(processor)·전달(exporter)하는 중앙 우체국. |
| OTLP | OpenTelemetry 전송 프로토콜(gRPC 4317 / HTTP 4318). |
| scrape | Prometheus가 타깃의 /metrics를 주기적으로 끌어오는(pull) 행위. |
| exporter | (1) OTel exporter=신호를 백엔드로 내보냄, (2) node-exporter=호스트 시스템 지표 노출. |
| PromQL | Prometheus 질의어. rate(...[5m])·histogram_quantile() 등. |
| LogQL | Loki 질의어. 라벨 스트림 {service="..."} + 필터 |=·정규식 |~. |
| trace / span | 요청 하나가 거쳐간 경로(trace)와 그 한 구간(span). Tempo가 저장. |
| provisioning | Grafana에 데이터소스·대시보드를 YAML·JSON으로 코드 선언해 자동 등록하는 것. |
| hypertable | TimescaleDB가 시간으로 자동 파티셔닝하는 테이블. |
| continuous aggregate | "시간당 블록 수" 같은 요약을 점증적으로 미리 계산해 두는 머티리얼라이즈드 뷰. |
| retention policy | 오래된 데이터를 자동 삭제하는 정책(여기 30d/90d). |
| reorg / orphan | 같은 높이에 다른 해시가 나타나면 reorg → 이전 블록을 고아(orphaned)로 표시. |
| sidecar | 본체를 안 건드리고 옆에서 기능을 더하는 보조 프로세스(여기선 RocksDB 읽기전용 리더). |
| BFF | Backend For Frontend. /api/*가 DB·노드 접근을 대신해 비밀을 숨김. |
| Cryptarchia / Nomos / Logos | Logos 프로젝트의 합의·노드. API cryptarchia/info로 높이·슬롯 조회. |
| faucet | 테스트넷 토큰 지급기(수도꼭지). 서버가 drip 후 DB에 기록. |