OpenAgent 설치

OpenAgent는 Prometheus 엔드포인트에서 메트릭을 수집하여 와탭 서버로 전송하는 에이전트입니다. 이 문서는 리눅스 호스트에 OpenAgent를 설치하고 실행하는 절차를 안내합니다.

OpenAgent 동작에 필요한 파일은 다음 세 가지입니다.

openagent: 메트릭 수집 및 전송 실행 파일
whatap.conf: 에이전트의 기본 설정 파일 (라이센스, 서버 주소 등)
scrape_config.yaml: 스크래핑 타겟 정의 파일

노트

설치 이후 상세 설정은 OpenAgent 설정 문서를 참고하세요.

노트

쿠버네티스 환경에서 OpenAgent를 설치하려는 경우, 별도의 OpenAgent 쿠버네티스 구성 문서를 참고하세요. 본 문서는 리눅스 호스트(바이너리) 설치를 기준으로 작성되어 있습니다.

사전 준비 사항

OpenAgent를 설치하기 전에 다음 사항을 준비하세요.

와탭 프로젝트의 액세스 키(라이센스)
와탭 수집 서버 호스트 주소와 포트(기본값 6600)
리눅스 호스트 환경 (AMD64 또는 ARM64)
수집할 Prometheus 엔드포인트 정보 (주소, 포트, 메트릭 경로)

노트

macOS Apple Silicon은 지원되지 않습니다. Linux AMD64(Intel/AMD 64비트) 또는 Linux ARM64에서만 동작합니다.

에이전트 다운로드

설치 디렉터리 생성

OpenAgent 관련 파일은 모두 하나의 디렉터리 안에 배치하는 것을 권장합니다. 설치 디렉터리를 생성하고 해당 경로로 이동하세요.

mkdir -p /opt/whatap/openagent
cd /opt/whatap/openagent

바이너리 다운로드

CPU 아키텍처에 맞는 바이너리를 다운로드합니다.

AMD64 (Intel/AMD 64비트)

wget https://repo.whatap.io/openagent/latest/amd/openagent

ARM64 (Linux ARM 프로세서)

wget https://repo.whatap.io/openagent/latest/arm/openagent

실행 권한 설정

다운로드한 바이너리에 실행 권한을 부여하세요.

chmod +x openagent

에이전트 설치 파일 구성

설치 후 디렉터리 구조는 다음과 같습니다.

/opt/whatap/openagent/
├── openagent          # 실행 파일
├── whatap.conf        # 기본 설정 파일
└── scrape_config.yaml # 스크래핑 타겟 설정 파일

openagent: 메트릭 수집 및 전송을 담당하는 실행 파일입니다.
whatap.conf: 라이센스, 수집 서버 정보, 로그 레벨 등 에이전트 동작의 기본 설정을 담는 파일입니다.
scrape_config.yaml: 어떤 Prometheus 엔드포인트로부터 메트릭을 수집할지 정의하는 파일입니다.

whatap.conf 기본 정보 입력

OpenAgent는 최소한 라이센스 키와 서버 주소가 설정돼 있어야 동작합니다. 설치 디렉터리 안에 whatap.conf 파일을 생성하고 아래 내용을 작성하세요.

echo "WHATAP_LICENSE=your-whatap-license" >> whatap.conf
echo "WHATAP_HOST=your-whatap-host"       >> whatap.conf
echo "WHATAP_PORT=your-whatap-port"       >> whatap.conf

완성된 whatap.conf 예시는 다음과 같습니다.

license=xxxxxxxxxxxxx-xxxxxxxxxx-xxxxxxxxxxxxx
whatap.server.host=10.10.0.1
whatap.server.port=6600

노트

로그 레벨, 환경변수 매핑, 디버그 옵션 등 상세 설정은 OpenAgent 설정 문서를 참고하세요.

scrape_config.yaml 기본 설정

설치 디렉터리 안에 scrape_config.yaml 파일을 생성하고 수집할 엔드포인트를 정의합니다. 아래는 가장 단순한 형태인 StaticEndpoints 예시입니다.

features:
  openAgent:
    enabled: true
    targets:
      - targetName: dcgm-exporter
        type: StaticEndpoints
        enabled: true
        endpoints:
          - address: "192.168.49.2:30400"
            path: "/metrics"
            scheme: "http"
            interval: "30s"
            metricRelabelConfigs:
              - source_labels: [__name__]
                regex: "DCGM.*"
                action: keep

노트

PodMonitor, ServiceMonitor, params, metricRelabelConfigs 등 상세 설정은 OpenAgent 설정 문서의 스크래핑 타겟 설정 섹션을 참고하세요. scrape_config.yaml 파일은 수정 시 자동으로 변경사항이 감지되며 에이전트 재시작이 불필요합니다.

에이전트 실행

설정이 완료되면 OpenAgent를 실행합니다.

기본 실행 (standalone)

./openagent standalone

백그라운드 실행 (nohup)

서비스 환경에서는 백그라운드로 실행하고 로그를 파일로 저장합니다.

nohup ./openagent standalone > /dev/null 2>&1 &

로그 확인

tail -f logs/whatap-boot-{yyyymmdd}.log

프로세스 관리

# 프로세스 확인
ps aux | grep openagent

# 프로세스 종료
pkill openagent

실행 모드

OpenAgent는 시작 인자에 따라 동작 모드를 구분합니다.

기본(worker) 모드: 인자 없이 실행하면 바로 워커로 동작합니다.
foreground 모드: ./openagent foreground 명령으로 부모 프로세스와 연동되는 워커 모드를 실행합니다.
standalone 모드: ./openagent standalone 또는 ./openagent foreground standalone 명령으로 실행하며, 쿠버네티스 ConfigMap 감시 없이 로컬 scrape_config.yaml만 사용합니다.

쿠버네티스 환경이 아닌 호스트에 OpenAgent를 설치할 때는 주로 standalone 모드를 사용합니다.

노트

Kubernetes 환경에서 설치하려면 오픈에이전트 구성 문서를 참고하세요.

오픈에이전트 바이너리 실행 파일 설치

모든 파일은 하나의 디렉토리에 위치해야 합니다.

## 예시
/opt/whatap/openagent/
├── openagent          # 실행 파일
├── whatap.conf        # 설정 파일
└── scrape_config.yaml # 스크래핑 설정 파일

디렉토리 이동 및 실행 파일 다운로드

mkdir -p /opt/whatap/openagent
cd /opt/whatap/openagent

## AMD64 (Intel/AMD 64비트 프로세서)
wget https://repo.whatap.io/openagent/latest/amd/openagent

## ARM64 (Linux 환경의 ARM 프로세서)
## ⚠️ macOS Apple Silicon 미지원
wget https://repo.whatap.io/openagent/latest/arm/openagent

실행 권한 설정

chmod +x openagent

설정 파일 생성(whatap.conf)

# 실제 값으로 교체해서 입력하세요
echo "WHATAP_LICENSE=your-whatap-license" >> whatap.conf
echo "WHATAP_HOST=your-whatap-host" >> whatap.conf  
echo "WHATAP_PORT=your-whatap-port" >> whatap.conf

# 디버그시
# echo "debug=true" >> whatap.conf
# echo "log_level=debug" >> whatap.conf

스크래핑 설정 파일 생성(scrape_config.yaml)

scrape_config.yaml 파일을 수정하면 OpenAgent가 자동으로 변경 사항을 감지하고 설정을 재로드합니다. 별도의 재시작이 필요하지 않습니다.

#scrape_config.yaml
features:
  openAgent:
    enabled: true
    targets:
     - targetName: dcgm-exporter
       type: StaticEndpoints
       # Target is enabled by default (enabled: true), this can be omitted
       enabled: true
       endpoints:
         - address: "192.168.49.2:30400"
           path: "/metrics"
           scheme: "http"
           interval: "30s"
           metricRelabelConfigs:
             - source_labels: [ __name__ ]
               regex: "DCGM.*"
               action: keep

기본 실행

./openagent standalone

백그라운드 실행

nohup ./openagent standalone > openagent.log 2>&1 &

로그 확인

tail -f openagent.log

프로세스 관리

# 프로세스 확인
ps aux | grep openagent

# 프로세스 종료
pkill openagent

StaticEndpoints 설정 요소

targetName: 타겟 식별자
type: 타겟 유형 ("StaticEndpoints")
endpoints: 수집 대상
- address: IP:PORT 또는 HOSTNAME:PORT
- path: 메트릭 경로 (기본값: /metrics)
- scheme: 프로토콜 (http 또는 https, 기본값: http)
- interval: 수집 주기 (기본값: 60s)
- metricRelabelConfigs: 메트릭 재라벨링 설정

params 기능 설정

OpenAgent에 params 기능을 사용하면 HTTP 스크래핑 시 URL에 쿼리 파라미터를 추가할 수 있습니다. Azure Monitor Exporter 등 외부 서비스 연동 시 유용합니다.

endpoints:
  - address: "192.168.49.2:30400"
    path: "/metrics"
    scheme: "http"
    interval: "30s"
    params:
      subscription: ["50d91b57-a280-45b5-8d7c-be8005662738"]
      resourceGroup: ["WhaTap-Data-KR-MID"]
      target: ["/subscriptions/50d91b57-a280-45b5-8d7c-be8005662738/resourceGroups/WhaTap-Data-KR-MID/providers/Microsoft.Sql/managedInstances/openmetrics-instance-01"]
      metric: ["avg_cpu_percent,virtual_core_count,memory_usage_percent"]
      interval: ["PT1M"]
      aggregation: ["average"]

지원되는 파라미터 값 타입
- 문자열: 단일 값
- 문자열 배열: 여러 값을 콤마로 연결
- 기타 타입: 자동으로 문자열로 변환

예제

예제. Azure Monitor 스타일
params:
  subscription: ["50d91b57-a280-45b5-8d7c-be8005662738"]
  target: ["/subscriptions/50d91b57-a280-45b5-8d7c-be8005662738/resourceGroups/MyRG/providers/Microsoft.Compute/virtualMachines/vm1"]
  metric: ["Percentage CPU,Available Memory Bytes"]
  interval: ["PT5M"]
  aggregation: ["average,maximum"]

예제. 단순 파라미터
params:
  format: "prometheus"
  version: "v1"
  debug: true

메트릭 재라벨링 설정 (metricRelabelConfigs)

OpenAgent는 프로메테우스의 metric_relabel_configs와 유사한 메트릭 재라벨링 기능을 제공하며, 스크래핑 후 메트릭을 필터링하거나 레이블을 변경할 수 있습니다.

재라벨링 설정 항목

source_labels: 소스 레이블 목록(배열)
separator: 소스 레이블 값을 연결할 때 사용할 구분자(기본값: ;)
target_label: 대상 레이블(결과를 저장할 레이블)
regex: 소스 레이블 값에 적용할 정규식
replacement: 대체 값(정규식 캡처 그룹 참조 가능, 예: ${1})
action: 수행할 작업(keep, drop, replace)

지원 작업 유형(action)

keep: 정규식과 일치하는 메트릭만 유지
drop: 정규식과 일치하는 메트릭 제거
replace: 대상 레이블의 값을 대체 값으로 변경

특수 레이블

name: 메트릭 이름을 나타내는 특수 레이블

예제 1. 모든 메트릭 수집

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: ".*"
    action: keep

예제 2. 특정 메트릭만 유지

이 설정은 http_requests_total 메트릭만 유지하고 나머지는 모두 제거합니다.

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: "http_requests_total"
    action: keep

동작 예시

다음과 같은 메트릭이 수집되었다고 가정합니다.

http_requests_total{method="GET", status="200"} 100
http_errors_total{method="GET", status="500"} 5
node_cpu_seconds_total{cpu="0", mode="idle"} 1000

위 metricRelabelConfigs를 적용하면 http_requests_total 메트릭만 유지되고 다른 메트릭들은 모두 제거됩니다.

http_requests_total{method="GET", status="200"} 100

예제 3. 정규식을 사용한 메트릭 필터링

이 설정은 node_cpu나 node_memory로 시작하는 메트릭만 유지합니다.

metricRelabelConfigs:
  - source_labels: [__name__]
    regex: "node_(cpu|memory).*"
    action: keep

동작 예시

다음과 같은 메트릭이 수집되었다고 가정합니다.

node_cpu_seconds_total{cpu="0", mode="idle"} 1000
node_memory_MemTotal_bytes{} 16777216
node_disk_io_time_seconds_total{device="sda"} 100
http_requests_total{method="GET", status="200"} 100

위 metricRelabelConfigs를 적용하면, node_cpu나 node_memory로 시작하는 메트릭만 유지되고 다른 메트릭들은 모두 제거됩니다. 정규식을 사용하여 여러 메트릭 패턴을 한 번에 필터링할 수 있습니다.

node_cpu_seconds_total{cpu="0", mode="idle"} 1000
node_memory_MemTotal_bytes{} 16777216

예제 4. 레이블 이름 변경

이 설정은 method 레이블의 값을 http_method 레이블로 복사합니다.

metricRelabelConfigs:
  - source_labels: [method]
    target_label: http_method
    replacement: "${1}"
    action: replace

동작 예시

다음과 같은 메트릭이 수집되었다고 가정합니다.

http_requests_total{method="GET", path="/api", status="200"} 100
http_requests_total{method="POST", path="/api/users", status="201"} 50

위 metricRelabelConfigs를 적용하면, 각 메트릭에 method 레이블의 값을 복사한 http_method 레이블이 추가됩니다. 원래 레이블은 유지되며 새 레이블이 추가됩니다. ${1}은 소스 레이블의 값을 참조합니다.

http_requests_total{method="GET", path="/api", status="200", http_method="GET"} 100
http_requests_total{method="POST", path="/api/users", status="201", http_method="POST"} 50

예제 5. 여러 소스 레이블 조합

이 설정은 http_requests_total 메트릭 중 status 레이블이 200 또는 500인 메트릭만 유지합니다.

metricRelabelConfigs:
  - source_labels: [__name__, status]
    regex: "http_requests_total;(200|500)"
    action: keep

동작 예시

다음과 같은 메트릭이 수집되었다고 가정합니다.

http_requests_total{method="GET", path="/api", status="200"} 100
http_requests_total{method="POST", path="/api/users", status="201"} 50
http_requests_total{method="GET", path="/api/error", status="500"} 10
http_requests_total{method="GET", path="/api/error", status="404"} 5

위 metricRelabelConfigs를 적용하면, http_requests_total 메트릭 중에서 status 레이블이 200 또는 500인 메트릭만 유지됩니다. 여러 소스 레이블을 조합할 때는 기본적으로 ; 구분자로 연결되며, 이를 separator 필드로 변경할 수 있습니다.

http_requests_total{method="GET", path="/api", status="200"} 100
http_requests_total{method="GET", path="/api/error", status="500"} 10

예제 6. 정적 레이블 추가

이 설정은 모든 메트릭에 metric_src="whatap-open-agent" 레이블을 추가합니다. 소스 레이블을 지정하지 않으면 replacement 값이 직접 레이블 값으로 사용됩니다. 이 방법을 사용하여 모든 메트릭에 환경, 리전, 애플리케이션 이름 등의 정적 레이블을 추가할 수 있습니다.

metricRelabelConfigs:
  - target_label: metric_src
    replacement: "whatap-open-agent"
    action: replace

동작 예시

다음과 같은 메트릭이 수집되었다고 가정합니다.

http_requests_total{method="GET", path="/api", status="200"} 100
node_cpu_seconds_total{cpu="0", mode="idle"} 1000

위 metricRelabelConfigs를 적용하면, 모든 메트릭에 metric_src="whatap-open-agent" 레이블이 추가됩니다. 이 방법은 메트릭의 출처를 표시하거나, 환경(예: production, staging), 리전(예: us-east, eu-west), 애플리케이션 이름 등을 표시하는 데 유용합니다.

http_requests_total{method="GET", path="/api", status="200", metric_src="whatap-open-agent"} 100
node_cpu_seconds_total{cpu="0", mode="idle", metric_src="whatap-open-agent"} 1000

예제. 종합적인 동작

다음과 같은 메트릭이 수집되었다고 가정합니다.

apiserver_request_total{code="200", resource="pods", verb="GET"} 100
some_other_metric{label="value"} 50

위 metricRelabelConfigs를 적용하면 최종적으로 수집되는 메트릭은 다음과 같습니다.

첫 번째 룰(keep apiserver_request_total) 적용
- apiserver_request_total 메트릭은 유지됩니다.
- some_other_metric 메트릭은 드롭됩니다.
두 번째 룰(replace verb → http_verb) 적용
- 유지된 apiserver_request_total 메트릭에 verb 레이블이 있으므로, 이 레이블의 값(GET)이 http_verb라는 새로운 레이블로 복사됩니다.

apiserver_request_total{code="200", resource="pods", verb="GET", http_verb="GET"} 100

사전 준비 사항​

에이전트 다운로드​

설치 디렉터리 생성​

바이너리 다운로드​

실행 권한 설정​

에이전트 설치 파일 구성​

whatap.conf 기본 정보 입력​

scrape_config.yaml 기본 설정​

에이전트 실행​

기본 실행 (standalone)​

백그라운드 실행 (nohup)​

로그 확인​

프로세스 관리​

실행 모드​

오픈에이전트 바이너리 실행 파일 설치​

StaticEndpoints 설정 요소​

params 기능 설정​

예제​

메트릭 재라벨링 설정 (metricRelabelConfigs)​

재라벨링 설정 항목​

지원 작업 유형(action)​

특수 레이블​

예제 1. 모든 메트릭 수집​

예제 2. 특정 메트릭만 유지​

예제 3. 정규식을 사용한 메트릭 필터링​

예제 4. 레이블 이름 변경​

예제 5. 여러 소스 레이블 조합​

예제 6. 정적 레이블 추가​

예제. 종합적인 동작​

사전 준비 사항

에이전트 다운로드

설치 디렉터리 생성

바이너리 다운로드

실행 권한 설정

에이전트 설치 파일 구성

whatap.conf 기본 정보 입력

scrape_config.yaml 기본 설정

에이전트 실행

기본 실행 (standalone)

백그라운드 실행 (nohup)

로그 확인

프로세스 관리

실행 모드

오픈에이전트 바이너리 실행 파일 설치

StaticEndpoints 설정 요소

params 기능 설정

예제

메트릭 재라벨링 설정 (metricRelabelConfigs)

재라벨링 설정 항목

지원 작업 유형(action)

특수 레이블

예제 1. 모든 메트릭 수집

예제 2. 특정 메트릭만 유지

예제 3. 정규식을 사용한 메트릭 필터링

예제 4. 레이블 이름 변경

예제 5. 여러 소스 레이블 조합

예제 6. 정적 레이블 추가

예제. 종합적인 동작