hubble-v3-guide

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 세 개의 호스트로 구성되어 있습니다.

2) 설치

Dependency

Go ≥ 1.17
Prometheus ≥ 2.24
Grafana ≥ 8

설치하게 될 목록

Exporter
- ARCUS Exporter (stats, prefix metric)
- Zookeeper Exporter
- Node Exporter
- 설정한 https://<listenAddress>:<port>/metrics 경로에서 metric 데이터를 조회할 수 있습니다.
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=8.0.0
GRAFANA_PLUGIN_VERSION=0.3.0
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의 실행을 위해 아래의 config.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 수집 않음

실행 방법

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

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

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)

ZooKeeper Exporter

실행 방법

INSTALL_DIR/zookeeper_exporter/start.sh 파일 내에 --zk-hosts 인자를 설정한 후 실행하거나 아래 script와 같이 실행할 수 있습니다. Exporter의 listen 주소와 수집할 zookeeper host 리스트를 인자로 주어 실행합니다. zookeeper exporter를 사용하려면 'mntr' 명령어가 4 letter word whitelist에 포함되어 있어야 합니다.

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

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

인자

의미

listen

Prometheus의 요청을 받기 위해 listen 하는 주소

zk-hosts

쉼표로 구분된 주키퍼 주소 목록, 대표 endpoint 하나가 아니라 반드시 모든 ZK host를 명시해주어야 합니다. 대표 endpoint 하나만 명시하면 여러 ZK host 데이터가 구분되지 않고 한 곳에 쌓이게 됩니다.

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 &

주의: 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 파일의 설정을 수정하여도 즉시 반영 되지는 않습니다. 수정 후 /-/reload API를 호출 하거나, 프로세스에 SIGHUP 시그널을 보내야 합니다. reload API를 호출하려면 prometheus 실행 옵션 --web.enable-lifecycle 선언해야 합니다. 자세한 사항은 [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 &

Grafana 설정

실행 설정 파일

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

hubble-v3.ini

구동을 위한 설정은 conf/hubble-v3.ini 파일을 수정합니다. listen ip:port 설정 및 log path를 변경할 경우 해당 파일을 수정합니다. 만약, 설치 script를 이용하지 않았다면,

해당 파일을 arcus-hubble-v3/server/settings/hubble-v3.ini 경로에서 복사해 와서 사용합니다.

hubble-v3_dashboards.yaml

대시보드 설정은 conf/provisioning/dashboards/hubble-v3_dashboards.yaml 경로의 파일을 수정합니다. 만약, 설치 script를 이용하지 않았다면,

해당 파일을 arcus-hubble-v3/server/settings/provisining/dashboard/hubble-v3_dashboards.yaml 경로에서 복사해 와서 합니다. 또한 파일의 providers.options.path는 provisionning할 dashboard의 path를 설정합니다.
```
path: INSTALL_DIR/grafana/conf/provisioning/dashboards
```
arcus-hubble-v3/server/settings/dashboards 하위 경로의 모든 파일을 복사하도록 합니다.

hubble-v3_datasources.yaml

datasource 설정은 conf/provisioning/datasources/hubble-v3_datasources.yaml 경로의 파일을 수정합니다. 만약, 설치 script를 이용하지 않았다면,

해당 파일을 arcus-hubble-v3/server/settings/provisining/datasources/hubble-v3_datasources.yaml 경로에서 복사해 오도록 합니다. 또한 simpod-json-datasource plugin 설치를 진행합니다.
```
INSTALL_DIR/grafana/bin/grafana-cli \\
      --homepath  INSTALL_DIR/grafana \\
      --pluginsDir  INSTALL_DIR/grafana/data/plugins plugins install simpod-json-datasource 0.3.0
```

실행방법

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

INSTALL_DIR/grafana/bin/grafana-server \
--homepath /home/arcus/app/grafana \
--config /home/arcus/app/grafana/conf/hubble-v3.ini \
--pidfile /home/arcus/app/grafana-server.pid &