hubble-v3-guide

Table of Contents

1) 개요

2) 설치

3) 설정 및 실행

1) 개요

구성 요소

arcus-hubble-v3의 구성 요소는 다음과 같습니다.

Exporter(ARCUS Exporter, Node Exporter, ZK Exporter)

• metric 데이터를 수집하여 제공하는 하나의 HTTP 서버입니다.

• Prometheus로부터 요청이 오면 metric 데이터를 수집하여 전달합니다.

• Exporter 종류

  • Arcus Exporter: Arcus 캐시 프로세스 상태 수집

  • Node Exporter: Arcus 장비의 system resource 수집

  • Zk Exporter: ZooKeeper 서버 상태 수집

Orbiter

• Grafana 요청(dashboard 템플릿 변수)에 대한 ARCUS 클러스터 구성 정보를 ZooKeeper에 질의하여 전달합니다.

• Grafana는 커스텀이 제한적이어서, 복잡한 조건에 의한 값을 결정하는 것이 불가능합니다. 이러한 로직을 구현하여 제공하는 기능도 있습니다.

Prometheus

• 정해진 주기로 exporter의 url 호출하여 metrics 데이터를 받아, 시계열 데이터로 저장하고 이를 효율적으로 관리합니다.

• 시간별 데이터의 difference를 구하는 방식으로 유의미하게 metrics 데이터를 압축해 저장합니다.

• grafana로부터 promQL 질의가 오면, 해당하는 metrics 데이터를 반환해줍니다.

• Pull 방식으로 metrics 수집하므로, 다양한 운영 환경에 유연하게 대처할 수 있습니다.

Grafana

• promQL을 사용해 prometheus에 질의를 보내 metrics 데이터를 가져와 시각화합니다.

• Dashboard의 템플릿 변수 값에 해당하는 ARCUS 클러스터 구성 정보는 Orbitor에 요청하여 얻어옵니다.

구성도

아래 그림은 arcus-hubble-v3의 구성도 예제 입니다.

• 2대의 캐시 장비(m1, m2)에는 서비스 코드가 "test"와 "repl"인 캐시 노드가 각각 구동되어 있습니다.

• 1대의 hubble 장비에는 hubble 대부분 구성 요소들이 설치되고, Node Exporter만 캐시 장비에 설치됩니다.

• ZooKeeper 클러스터는 zk-1:2181, zk-2:2181, zk-3:2181 세 개의 호스트로 구성되어 있습니다.

image

2) 설치

Dependency

• Go ≥ 1.17

• Prometheus ≥ 2.24

• Grafana ≥ 8

설치하게 될 목록

• Exporter

  • ARCUS Exporter (stats, prefix metric)

  • Zookeeper Exporter

  • Node Exporter

• Prometheus

• Grafana

• Orbiter

설치 시작

아래 스크립트를 이용해 arcus-hubble-v3를 다운 받습니다.

git clone https://github.com/jam2in/arcus-hubble-v3.git

설치 방법은 통합설치와 개별설치가 있습니다. 먼저 통합 설치에 대해 설명드리겠습니다.

통합 설치

arcus-hubble-v3/scripts 디렉토리로 이동하여 통합 설치를 진행합니다. 디렉토리는 아래의 구조로 구성되어 있습니다.

설치 디렉토리 구조

arcus-hubble-v3/scripts
├── arcus_exporter
├── config.sh
├── downsampled
├── go
├── grafana
├── install.sh
├── node_exporter
├── orbiter
├── prometheus
├── promxy
└── zookeeper-exporter

config 파일 수정

통합 설치를 진행하기 위해 config.sh 파일의 INSTALL_DIR 변수, GRAFANA, PROMETHEUS 등의 여러 설정 값을 확인하고 변경하여야 합니다.

#############################
# COMMON
#############################
INSTALL_DIR=/home/arcus/app
GO_VERSION=1.19.2
GO_INSTALL_DIR="$HOME/go"
GOPATH="$GO_INSTALL_DIR/bin"
...
#############################
# GRAFANA
#############################
GRAFANA_VERSION=11.2.2
GRAFANA_PLUGIN_VERSION=0.6.5
GRAFANA_INSTALL_DIR=$INSTALL_DIR/grafana
...

통합 설치 진행

config.sh파일의 설정이 완료되었다면 install.sh 파일을 실행하여 설치를 진행합니다.

./install.sh

설치가 완료되면 아래와 같은 구조로 파일이 구성됩니다.

설치 완료 디렉토리 구조

INSTALL_DIR
├── arcus-exporter
│   ├── arcus_exporter
│   ├── config.json
│   ├── log
│   └── start.sh
├── grafana
│   ├── bin
│   ├── conf
│   ├── data
│   ├── grafana-server.pid
│   ├── LICENSE
│   ├── log
│   ├── NOTICE.md
│   ├── plugins-bundled
│   ├── public
│   ├── README.md
│   ├── scripts
│   ├── start.sh
│   └── VERSION
├── node_exporter
│   ├── node_exporter
│   └── start.sh
├── orbiter
│   ├── config.json
│   ├── log
│   ├── orbiter
│   └── start.sh
├── prometheus
│   ├── conf
│   ├── console_libraries
│   ├── consoles
│   ├── data
│   ├── LICENSE
│   ├── NOTICE
│   ├── prometheus
│   ├── prometheus.yml
│   ├── promtool
│   └── start_raw.sh
└── zookeeper-exporter
    ├── start.sh
    └── zookeeper-exporter

개별 설치

통합 설치가 아닌 개별 설치를 원할 경우 arcus-hubble-v3/scripts에서 설치를 원하는 구성 디렉토리로 이동하여 download.sh, install.sh를 실행합니다. 개별 설치 시에도 상위 디렉토리의 config.sh 파일의 설치 경로 및 설치 대상의 설정이 필요합니다.

config 파일 수정

#############################
# COMMON
#############################
INSTALL_DIR=/home/arcus/app
GO_VERSION=1.19.2
GO_INSTALL_DIR="$HOME/go"
GOPATH="$GO_INSTALL_DIR/bin"
...

개별 설치 예제

# arcus_exporter 설치
cd /arcus_exporter
./install.sh

# node_exporter 설치
cd /node_exporter
./download.sh
./install.sh

node_exporter의 경우 상단의 구성도 그림과 같이 각 VM 장비에 개별 설치가 필요합니다.

개별 설치의 결과는 통합 설치의 설치 완료 디렉토리 구조를 참조하시기 바랍니다.

3) 설정 및 실행

ARCUS Exporter

실행 설정 파일

ARCUS Exporter의 실행을 위해 아래와 같은 설정 파일을 작성해야 합니다. (conf/example.json 참고) 하나의 zk ensemble에 대해서만 수집이 가능하므로, 여러 zk ensemble 사용 시 여러 arcus exporter를 구동해야 합니다.

{
    "listen": "hubble-host:13111",
    "ensemble": [
      "zk-1:2181",
      "zk-2:2181",
      "zk-3:2181"
    ],
    "serviceCodes": [
        "test",
        "repl"
    ],
    "collectPrefixes": false,
    "serviceCodesToCollectPrefixes": {
        "serviceCode01": ["*"],
        "serviceCode02": ["prefix01", "prefix02"],
        "serviceCode03": []
    },
    "log": {
      "level": "warn",
      "filename": "INSTALL_DIR/arcus_exporter/log/arcus_exporter.log",
      "maxSize": 20,
      "maxBackups": 10,
      "maxAge": 30,
      "compress": false
    }
}

해당 인자의 의미는 아래와 같습니다.

인자	의미
listen	arcus_exporter의 listen address 설정
ensemble	zk ensemble 주소 설정, ZK 서버 목록이나 ZK 도메인 이름을 설정
serviceCodes	수집 대상 service_codes 목록 설정, 설정하지 않으면 ensemble 내의 모든 service codes 수집함
collectPrefixes	true인 경우 모든 prefix 정보를 수집, false인 경우 prefix metric 수집하지 않음
serviceCodesToCollectPrefixes	서비스 코드별로 수집할 prefix 목록 지정. 이 옵션에 포함된 service code는 collectPrefixes 옵션 무시
log.level	arcus_exporter의 log level 설정, default는 warn이며 debug, warn, error, fatal, panic 중 하나를 사용할 수 있음
log.filename	arcus_exporter의 log 출력 위치를 설정, 기본 설정은 stdout
log.maxSize	arcus_exporter의 log 파일 하나의 용량을 설정, 기본 설정은 20MB
log.maxBackups	arcus_exporter의 백업 log 파일의 개수 지정, 기본 설정은 10개
log.maxAge	arcus_exporter의 log 보존 기간을 설정, 기본은 30일 (24h * 30)
log.compress	arcus_exporter의 백업용 log를 압축해 저장할지 여부를 설정, 기본 설정은 false

serviceCodesToCollectPrefixes에서 각 service code에 대한 prefix 설정의 의미는 아래와 같습니다. serviceCodesToCollectPrefixes에 명시된 service codes에 대해서는 collectPrefixes 옵션은 적용되지 않습니다.

• ["*"]: 모든 prefix 수집

• ["prefix01", "prefix02"]: 주어진 prefix만 수집

• []: prefix 수집 않음

실행 방법

• start.sh 스크립트를 사용하여 ARCUS Exporter를 실행할 수 있습니다.

• 아래 예시의 경우, INSTALL_DIR/arcus_exporter/conf/example1.json을 사용하여 exporter를 실행합니다.

• 다수의 exporter를 일괄 구동할 수 있습니다.

INSTALL_DIR/arcus_exporter/start.sh example1
# INSTALL_DIR/arcus_exporter/start.sh example1 example2 ...

• 또는 아래와 같이 arcus_exporter 바이너리를 직접 실행할 수 있습니다.

INSTALL_DIR/arcus_exporter/arcus_exporter -config-file=INSTALL_DIR/arcus_exporter/conf/example.json

• http://<listenAddress>:<port>/metrics 경로에서 default stats metric 데이터를 조회할 수 있습니다.

• http://<listenAddress>:<port>/metrics/prefixes 경로에서 default stats metric 데이터를 조회할 수 있습니다.

Node Exporter

ARCUS 캐시 장비(PM or VM)마다 하나씩 가동해야 합니다. 해당 캐시 장비에서 CPU, 메모리, 네트워크 등의 system resource 정보를 수집합니다.

실행 방법

INSTALL_DIR/node_exporter/start.sh 파일을 실행하거나 아래 스크립트와 같이 실행할 수 있습니다. ARCUS 캐시 장비에서 구동되는 exporter이므로, 캐시 노드의 동작에 영향을 주지 않아야 한다. 이를 위해, 최소한의 리소스만 사용하여 반드시 필요한 metrics만 수집하는 구동 옵션을 사용하도록 설정하였습니다.

GOMAXPROCS=1 INSTALL_DIR/node_exporter/node_exporter --collector.disable-defaults \
             --collector.cpu --collector.meminfo --collector.stat --collector.vmstat \
             --collector.diskstats --collector.netstat --collector.netdev \
             --collector.loadavg --collector.filefd \
             --web.listen-address=0.0.0.0:9100 --log.level=error

예시에 나온 인자의 의미는 다음과 같습니다.

인자	의미
GOMAXPROCS	go routine이 사용할 수 있는 최대 core 개수
collector.disable-default	default metric을 수집하지 않습니다.
collector.*	arcus-hubble에서 필요한 metric을 수집하도록 설정합니다.
web.listen-address	Prometheus의 요청을 받기 위해 listen 하는 주소
log.level	로그 레벨을 지정합니다.(debug, info, warn, error)

• http://<listenAddress>:<port>/metrics 경로에서 metric 데이터를 조회할 수 있습니다.

ZooKeeper Exporter

[!WARNING] zookeeper exporter를 사용하려면 mntr 명령어가 4 letter word whitelist에 포함되어 있어야 합니다.

실행 설정 파일

ZooKeeper Exporter의 실행을 위해 아래와 같은 설정 파일을 작성해야 합니다. (conf/example.env 참고) 하나의 zk ensemble에 대해서만 수집이 가능하므로, 여러 zk ensemble 사용 시 여러 zookeeper exporter를 구동해야 합니다.

LISTEN_PORT=9141
ZK_DOMAIN="example.arcus.com:2181"
#ZK_SERVERS=("10.0.0.1:2181" "10.0.0.2:2181" "10.0.0.3:2181")

해당 인자의 의미는 다음과 같습니다.

인자	의미
LISTEN_PORT	Prometheus의 요청을 받기 위해 listen 하는 port
ZK_DOMAIN	ZooKeeper ensemble을 구성하는 server로 구성된 domain
ZK_SERVERS	ZooKeeper ensemble을 구성하는 server 목록

ZK_DOMAIN과 ZK_SERVERS 중 하나의 설정만 사용해야 합니다.

실행 방법

• start.sh 스크립트를 사용하여 ZooKeeper Exporter를 실행할 수 있습니다.

• 아래 예시의 경우, INSTALL_DIR/zookeeper-exporter/conf/example1.env를 사용하여 exporter를 실행합니다.

• 다수의 exporter를 일괄 구동할 수 있습니다.

INSTALL_DIR/zookeeper-exporter/start.sh example1
# INSTALL_DIR/zookeeper-exporter/start.sh example1 example2 ...

• 또는 아래와 같이 zookeeper-exporter 바이너리를 직접 실행할 수 있습니다.

[!WARNING] zk-hosts 인자에는 모든 zk server의 endpoint를 명시해주어야 합니다. domain 주소 하나만 명시하면 여러 서버의 데이터가 구분되지 않고 하나의 metric으로 수집됩니다.

INSTALL_DIR/zookeeper-exporter/zookeeper-exporter --listen=hubble-host:9141 --zk-hosts=zk-1:2181,zk-2:2181,zk-3:2181

• http://<listenAddress>:<port>/metrics 경로에서 metric 데이터를 조회할 수 있습니다.

Orbiter

실행 설정 파일

실행하기에 앞서 아래의 config.json 파일을 설정해야 합니다.

{
    "listen": "0.0.0.0:8084",
    "ensembleByName": {
        "hubble-demo-community": ["zk-1:2195","zk-2:2195","zk-3:2195"],
        "hubble-demo-repl":["zk-4:12195","zk-5:12195","zk-6:12195"]
    },
    "serviceCodesByEnsembleName": {
        "hubble-demo-community": ["serviceCode01", "serviceCode03"]
    },
    "log": {
      "level": "warn",
      "filename": "INSTALL_DIR/orbiter/log/orbiter.log",
      "maxSize": 20,
      "maxBackups": 10,
      "maxAge": 30,
      "compress": false
    }
}

인자	의미
listen	Orbiter가 listen하는 주소
ensembleByName	앙상블의 논리적 이름을 부여하는 맵 (key: 앙상블의 논리적 이름, value: 물리적 주소)
serviceCodesByEnsembleName	앙상블에서 수집하고 싶은 service Code를 담는 맵 (key: 앙상블의 논리적 이름, value: service code 목록) 따로 목록을 지정하지 않을 경우 모든 service code를 사용하게 된다.
log.level	arcus_exporter의 log level 설정, default는 warn이며 debug, warn, error, fatal, panic 중 하나를 사용할 수 있음
log.filename	arcus_exporter의 log 출력 위치를 설정, 기본 설정은 stdout
log.maxSize	arcus_exporter의 log 파일 하나의 용량을 설정, 기본 설정은 20MB
log.maxBackups	arcus_exporter의 백업 log 파일의 개수 지정, 기본 설정은 10개
log.maxAge	arcus_exporter의 log 보존 기간을 설정, 기본은 30일 (24h * 30)
log.compress	arcus_exporter의 백업용 log를 압축해 저장할지 여부를 설정, 기본 설정은 false

Orbiter에서는 여러 ZK ensemble에서 관리되는 캐시 클러스터 정보를 조회할 수 있으며, 각 ZK ensemble에서도 주어진 service codes 목록에 대해서만 정보를 조회할 수 있다. 이는 Grafana에서 관심 있는 service codes 정보만 보이게 하는 데 필요한 설정이다.

실행 방법

INSTALL_DIR/orbiter/start.sh 파일을 실행하거나 아래 script와 같이 실행할 수 있습니다.

INSTALL_DIR/orbiter/orbiter -config-file=/home/arcus/app/orbiter/config.json

[!WARNING] Orbiter가 실행되는 장비는 모든 캐시, zk 장비의 hostname을 인식할 수 있어야 하며, exporter가 인식하는 hostname과 달라서는 안 됩니다.

참고로, 아래와 같이 /etc/hosts 파일에 hostname 인식할 수 있도록 설정하면 됩니다.

vi /etc/hosts

###host file ###

192.168.0.1  arcus-zookeeper-1  arcus-zookeeper-1
192.168.0.2  arcus-zookeeper-2  arcus-zookeeper-2
192.168.0.3  arcus-zookeeper-3  arcus-zookeeper-3

Prometheus

실행 설정 파일

INSTALL_DIR/prometheus/conf/raw.yml 파일에서 prometheus 설정을 변경할 수 있습니다. Prometheus 설정은 가급적 수정하지 않고 그대로 유지하기 바랍니다.

global:
  scrape_interval:     5s
  evaluation_interval: 5s

rule_files:
  - recording/agg.yaml
  # do enable when you want downsampling
#  - recording/downsample.yaml

scrape_configs:
  - job_name: meta
    honor_timestamps: true
    scrape_interval: 5s
    scrape_timeout: 5s
    metrics_path: /metrics
    scheme: http
    follow_redirects: true
    static_configs:
      - targets:
          - 1.2.3.4:9090
        labels:
          host: demo-test
  - job_name: system_resource
    relabel_configs:
      - target_label: "resolution"
        replacement: "5s"
    file_sd_configs:
      - files:
          - 'INSTALL_DIR/prometheus/conf/exporter/node_exporter.json'

  - job_name: arcus
    relabel_configs:
      - target_label: "resolution"
        replacement: "5s"
    file_sd_configs:
      - files:
          - 'INSTALL_DIR/prometheus/conf/exporter/arcus_exporter.json'

  - job_name: arcus_prefixes
    scrape_interval: 1m
    metrics_path: /metrics/prefixes
    relabel_configs:
      - target_label: "resolution"
        replacement: "1m"
    file_sd_configs:
      - files:
          - 'INSTALL_DIR/prometheus/conf/exporter/arcus_exporter.json'

  - job_name: zookeeper
    scrape_interval: 1m
    relabel_configs:
      - target_label: "resolution"
        replacement: "1m"
    file_sd_configs:
      - files:
          - 'INSTALL_DIR/prometheus/conf/exporter/zookeeper_exporter.json'

프로퍼티	의미
scrape_interval	prometheus의 metric 수집 주기 설정
evaluation_interval	설정된 rule이 있다면, rule을 이용해 metric 데이터를 평가하기 위한 주기 설정
rule_files	수행하기 원하는 rule 설정 (home dashboard의 집계 데이터 활용을 위한 aggregation rule 설정)
scrape_configs	모니터링 대상 리소스 설정
job_name	모니터링 대상 리소스를 나타낼 이름
file_sd_configs	모니터링 대상 목록 설정

raw.yml 파일은 file_sd_configs를 통해 수집 대상을 설정하도록 되어 있습니다. INSTALL_DIR/prometheus/conf/exporter 디렉토리 내부에는 수집을 원하는 exporter들의 목록을 json 파일 형태로 구성하고 있습니다. 이 json 파일들을 raw.yml에 명시하여 prometheus가 exporter로부터 metric 데이터를 수집하도록 합니다. exporter 파일에는 구동된 arcus_exporter, node_exporter, zookeeper_exporter 목록을 명시합니다.

raw.yml 파일의 설정을 수정하여도 즉시 반영 되지는 않습니다. 수정 후 POST http://<listeniop>:<port>/-/reload API를 호출 하거나, 프로세스에 SIGHUP 시그널을 보내야 합니다. 자세한 사항은 [Prometheus 설정 문서] 참고 바랍니다.

실행 방법

raw.yml에 수집 대상 exporter에 대한 설정을 확인한 후 INSTALL_DIR/prometheus/start-raw.sh 파일을 실행하거나 아래 script와 같이 실행할 수 있습니다.

INSTALL_DIR/prometheus/prometheus \
--config.file=/home/arcus/app/prometheus/conf/raw.yaml \
--web.enable-lifecycle \
--web.enable-admin-api \
--storage.tsdb.retention.time=30d \
--storage.tsdb.retention.size=10GB \
--storage.tsdb.path=/home/arcus/app/prometheus/data/raw &

해당 인자의 의미는 다음과 같습니다.

인자	의미
config.file	수집 관련 설정이 포함된 설정 파일
web.enable-lifecycle	reload API를 통해 설정을 동적으로 변경하기 위한 옵션
web.enable-admin-api	http 요청을 통해 설정 등을 변경할 수 있도록 하는 admin API 활성화
storage.tsdb.retention.time	metric 데이터의 최대 보관 기간
storage.tsdb.retention.size	metric 데이터의 최대 보관 용량
storage.tsdb.path	metric 데이터의 저장 위치

Grafana 설정

실행 설정 파일

설치 script 이용하여 설치했을 경우, dashboard provisioning을 위한 json 파일 및 설정 파일, 플러그인이 모두 설치 됩니다.

grafana.ini

• listen ip:port, log 설정 등을 변경하려는 경우 INSTALL_DIR/grafana/conf/grafana.ini 파일을 수정합니다.

• 설치 스크립트 사용하지 않은 경우 arcus-hubble-v3/conf/grafana/grafana.ini 참고하여 작성합니다.

hubble-v3_dashboards.yaml

• dashboard provisioning 설정을 변경하려는 경우 INSTALL_DIR/grafana/conf/provisioning/dashboards/hubble-v3_dashboards.yaml 파일을 수정합니다.

• 설치 스크립트 사용하지 않은 경우 arcus-hubble-v3/conf/grafana/provisioning/dashboards/hubble-v3_dashboards.yaml 참고하여 작성합니다.

• arcus-hubble-v3에서 제공하는 dashboard는 arcus-hubble-v3/conf/grafana/dashboards 하위에 위치하고 있습니다.

hubble-v3_datasources.yaml

• datasource provisioning 설정을 변경하려는 경우 INSTALL_DIR/grafana/conf/provisioning/datasources/hubble-v3_dashboards.yaml 파일을 수정합니다.

• 설치 스크립트 사용하지 않은 경우 arcus-hubble-v3/conf/grafana/provisioning/datasources/hubble-v3_datasources.yaml 참고하여 작성합니다.

• JSON datasource 사용을 위해서는 플러그인 설치가 필요합니다.

INSTALL_DIR/grafana/bin/grafana cli\
 --homepath INSTALL_DIR/grafana\
 --pluginsDir INSTALL_DIR/grafana/data/plugins plugins install simpod-json-datasource 0.6.5

실행방법

INSTALL_DIR/grafana/start.sh 파일을 실행하거나 아래 스크립트와 같이 실행할 수 있습니다.

INSTALL_DIR/grafana/bin/grafana-server \
--homepath INSTALL_DIR/grafana \
--config INSTALL_DIR/grafana/conf/grafana.ini \
--pidfile INSTALL_DIR/grafana-server.pid

접속 및 기본 모니터링 설정

grafana 설치 시 설정했던 <listenip>:<port>로 접속합니다. 초기화면은 아래와 같습니다.