OpenAgent 설정

OpenAgent는 Prometheus 엔드포인트에서 메트릭을 수집하여 와탭 서버로 전송하는 에이전트입니다. 에이전트 동작에 필요한 설정은 두 개의 파일로 분리되어 있습니다.

whatap.conf: 에이전트의 기본 설정(라이센스, 서버 주소, 로그 레벨 등)
scrape_config.yaml: 수집 타겟(Prometheus 엔드포인트) 정의

에이전트는 환경변수에 지정된 위치에서 설정 파일을 읽습니다. 별도 설정이 없는 경우 에이전트는 현재 실행 디렉터리에서 whatap.conf 파일을 찾습니다. 5초마다 whatap.conf 파일의 변경 여부를 확인해 다시 읽으므로 에이전트 재시작 없이 대부분의 설정 변경 사항을 적용할 수 있습니다.

와탭 모니터링 서비스 화면에서도 에이전트 설정을 변경할 수 있습니다.

노트

OpenAgent 설치 방법은 OpenAgent 설치 문서를 참고하세요.

기본 설정

whatap.conf

OpenAgent는 최소한 라이센스 키와 서버 주소가 설정돼 있어야 동작합니다.

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

# 로그 레벨: DEBUG(0), INFO(1), WARN(2), ERROR(3)
log_level=INFO
debug=false

OpenAgent는 동일한 설정 값을 여러 키 형식으로 받을 수 있도록 지원합니다. 환경변수와 whatap.conf 어느 쪽에도 설정할 수 있으며, 설정 파일 값이 우선 적용되고 없을 경우 환경변수 값을 사용합니다.

Setting	Key	Environment Variable	Default
라이센스 키	license, WHATAP_LICENSE	WHATAP_LICENSE	(필수)
서버 호스트	whatap.server.host, WHATAP_HOST	WHATAP_HOST, WHATAP_SERVER_HOST	(필수)
서버 포트	whatap.server.port, WHATAP_PORT	WHATAP_PORT, WHATAP_SERVER_PORT	6600
에이전트 이름	whatap.oname, app_name	WHATAP_ONAME	자동 생성

설정 파일 경로

OpenAgent는 다음 환경변수를 사용해 설정 파일 위치와 에이전트 홈 디렉터리를 식별합니다.

WHATAP_HOME: whatap.conf 파일이 위치한 디렉터리. 기본값은 현재 디렉터리(.)
WHATAP_OPEN_HOME: OpenAgent의 실행 홈 디렉터리(로그 파일 등 저장 위치)

환경변수가 설정되지 않으면 에이전트가 실행 중인 디렉터리를 기준으로 whatap.conf 파일을 찾습니다.

export WHATAP_HOME=/app/whatap
export WHATAP_OPEN_HOME=/app/whatap
./openagent

서버 연결 및 데이터 전송

OpenAgent는 whatap.conf에 설정한 서버 주소로 TCP 세션을 연결합니다.

whatap.server.host=10.10.1.1
whatap.server.port=6600

TCP 세션을 연결하면 license를 이용해 서버로부터 통신 키를 전달 받습니다. 잘못된 license를 설정하면 서버는 세션을 종료합니다.
TCP 연결이 반복적으로 종료되면 방화벽 문제를 확인하거나 license 값이 올바른지 확인하세요.
TCP 세션을 연결하면 서버로부터 받은 비밀키를 기반으로 보안 통신으로 데이터를 전송합니다.
여러 서버 주소를 / 또는 ,로 구분해 나열하면 장애 조치(failover)용으로 사용합니다.

whatap.server.host=10.10.1.1/10.10.1.2

로그 레벨 설정

로그는 log_level 또는 debug 설정으로 제어할 수 있습니다. 두 설정이 모두 있을 경우 log_level이 우선합니다.

log_level=INFO   # DEBUG(0) | INFO(1) | WARN(2) | ERROR(3)
debug=false      # true로 설정하면 DEBUG 레벨로 동작

로그 레벨도 whatap.conf 리로딩 대상이므로 에이전트 재시작 없이 변경이 반영됩니다.

스크래핑 타겟 설정 (scrape_config.yaml)

OpenAgent의 핵심 동작인 Prometheus 엔드포인트 수집은 $WHATAP_HOME/scrape_config.yaml 파일로 정의합니다. 아래 3가지 타겟 타입을 지원합니다.

PodMonitor: Pod 레이블 셀렉터를 이용한 동적 디스커버리 (쿠버네티스)
ServiceMonitor: Service 레이블 셀렉터를 이용한 동적 디스커버리 (쿠버네티스)
StaticEndpoints: 고정된 IP 주소와 포트를 직접 입력

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 예제 (쿠버네티스)

features:
  openAgent:
    enabled: true
    globalInterval: "60s"
    globalPath: "/metrics"
    targets:
      - targetName: my-app-pod-metrics
        type: PodMonitor
        namespaceSelector:
          matchNames: ["production"]
        selector:
          matchLabels:
            app: my-app
        endpoints:
          - port: "web-metrics"
            path: "/metrics"
            interval: "15s"
            scheme: "http"
            timeout: "10s"

StaticEndpoints 설정 요소

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

params 쿼리 파라미터 설정

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

Azure Monitor 스타일 예제

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"]

단순 파라미터 예제

params:
  format: "prometheus"
  version: "v1"
  debug: true

메트릭 재라벨링 (metricRelabelConfigs)

프로메테우스의 metric_relabel_configs와 유사한 메트릭 재라벨링 기능을 제공합니다.

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

지원 작업 유형

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

특수 레이블

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

재라벨링 예제

예제 1. 모든 메트릭 수집

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

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

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

http_requests_total 메트릭만 유지되고 나머지는 제거됩니다.

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

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

node_cpu나 node_memory로 시작하는 메트릭만 유지됩니다.

예제 4. 레이블 이름 변경

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

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

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

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

http_requests_total 메트릭 중 status가 200 또는 500인 메트릭만 유지됩니다.

예제 6. 정적 레이블 추가

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

모든 메트릭에 metric_src="whatap-open-agent" 레이블이 추가됩니다.

여러 OpenAgent 인스턴스의 설정 파일 관리

한 서버에서 여러 OpenAgent 인스턴스를 운영해야 할 경우, 각 인스턴스별로 홈 디렉터리를 분리하고 WHATAP_HOME 환경변수를 다르게 지정합니다.

# 인스턴스 A
WHATAP_HOME=/app/whatap/serviceA ./openagent standalone

# 인스턴스 B
WHATAP_HOME=/app/whatap/serviceB ./openagent standalone

각 홈 디렉터리에 별도의 whatap.conf와 scrape_config.yaml을 배치하면 인스턴스별로 독립된 설정을 유지할 수 있습니다.

pprof 프로파일링 엔드포인트

성능 분석이 필요한 경우 pprof HTTP 서버를 통해 런타임 정보를 확인할 수 있습니다.

export PPROF_PORT=6060   # 기본값 6060
./openagent standalone

사용 가능한 엔드포인트는 다음과 같습니다.

http://localhost:6060/debug/pprof/profile: CPU 프로파일
http://localhost:6060/debug/pprof/heap: Heap 프로파일
http://localhost:6060/debug/pprof/goroutine: Goroutine 프로파일

서비스 화면에서 에이전트 설정하기

관리 > 에이전트 설정

서버의 whatap.conf 파일을 직접 편집하지 않아도 와탭 모니터링 서비스에서 에이전트 설정 옵션을 추가, 수정, 삭제할 수 있습니다. 또한 설정 파일 다운로드 버튼을 클릭해 whatap.conf 파일을 다운로드할 수 있습니다.

이 기능은 수정 권한을 가진 멤버만 이용할 수 있습니다. 수정 권한이 없는 멤버는 설정 내용을 조회만 할 수 있습니다.
옵션값으로 설정할 수 있는 형식은 다음과 같습니다.
- Boolean 형식의 값은 true 또는 false를 선택하세요.
- 숫자 형식의 값은 숫자만 입력할 수 있습니다.
- 텍스트(String) 형식의 값을 입력 또는 수정할 경우 옵션 설명을 자세히 확인하세요.

추가 또는 수정, 삭제한 옵션에 따라 에이전트를 재시작해야 할 수 있습니다. OpenAgent의 경우 대부분의 whatap.conf 값은 5초 이내 자동 리로딩됩니다.

옵션 추가하기

openagent 옵션 추가

에이전트 목록에서 옵션을 추가하려는 에이전트를 선택하세요.
옵션 작성에서 추가할 옵션 항목을 선택하세요.
- 검색에서 추가할 옵션을 찾을 수 있습니다. 텍스트를 입력하면 일치하는 옵션을 필터링합니다.
- 직접 입력을 선택하면 옵션 키와 값을 입력할 수 있습니다.
선택한 옵션 키에 대한 설명과 기본값을 확인한 다음 설정값을 입력하세요.
원하는 모든 옵션을 추가했으면 화면 오른쪽 위에 적용 버튼을 클릭하세요.

주의

옵션값으로 아무것도 입력하지 않은 상태에서 적용 버튼을 클릭하면 해당 옵션을 삭제합니다. 이미 추가한 옵션은 옵션 목록에서 선택할 수 없습니다. 애플리케이션 종류 및 에이전트 버전에 따라 적용할 수 있는 옵션 키는 다를 수 있습니다.

옵션 수정 또는 삭제하기

openagent 옵션 수정 또는 삭제

화면을 위/아래로 스크롤하거나 옵션 목록에서 수정 또는 삭제하려는 옵션을 선택하세요.
변경하려는 옵션에서 원하는 값을 선택하거나 수정하세요. 옵션을 삭제하려면 삭제 아이콘 버튼을 클릭하세요.
변경한 사항을 적용하려면 적용 버튼을 클릭하세요.

여러 에이전트에 동시 적용하기

프로젝트에 소속된 여러 개의 OpenAgent에 변경한 옵션을 동시에 적용할 수 있습니다.

화면 오른쪽 위에 다중 에이전트 적용 체크박스를 선택하면 각 옵션 항목에 체크박스가 생성됩니다.
동시에 적용하길 원하는 옵션의 체크박스를 선택하세요.
화면 오른쪽 위에 적용 버튼을 클릭하세요.
에이전트 적용 창이 나타나면 변경한 옵션을 적용할 에이전트를 선택한 뒤 적용 버튼을 클릭하세요.

에이전트 설정 옵션 안내

OpenAgent에서 사용할 수 있는 주요 whatap.conf 옵션은 다음과 같습니다.

Option	Type	Default	Description
`license` / `WHATAP_LICENSE`	`string`	(필수)	와탭 프로젝트 라이센스 키
`whatap.server.host` / `WHATAP_HOST`	`string`	(필수)	와탭 수집 서버 주소. `/` 또는 `,`로 여러 개 지정 가능
`whatap.server.port` / `WHATAP_PORT`	`integer`	6600	와탭 수집 서버 포트
`whatap.oname` / `WHATAP_ONAME`	`string`	자동 생성	에이전트의 오브젝트 이름
`app_name`	`string`	-	whatap.oname 미설정 시 대체로 사용
`debug`	`boolean`	false	디버그 로그 활성화
`log_level`	`string` / `integer`	INFO	로그 레벨 (DEBUG / INFO / WARN / ERROR 또는 0 ~ 3)
`tag_counter_enabled`	`boolean`	false	OpenMetrics 프로젝트를 별도 제품으로 사용할 때 활성화
`scrape_interval`	`string`	60s	스크래핑 전역 기본 주기 (scrape_config.yaml의 globalInterval과 별개의 하위 호환 키)
`scrape_timeout`	`string`	-	스크래핑 전역 기본 타임아웃

팁

tag_counter_enabled 옵션은 OpenMetrics 프로젝트가 다른 와탭 제품과 연동되지 않고 별도 제품으로 운영되는 경우에만 true로 설정하세요. 기본 구성에서는 사용하지 않습니다.

노트

애플리케이션 종류 및 에이전트의 버전에 따라 적용할 수 있는 옵션 키는 다를 수 있습니다. 수집 타겟 설정과 관련된 옵션은 위의 스크래핑 타겟 설정 섹션을 참고하세요.

기본 설정​

whatap.conf​

설정 파일 경로​

서버 연결 및 데이터 전송​

로그 레벨 설정​

스크래핑 타겟 설정 (scrape_config.yaml)​

StaticEndpoints 기본 예제​

PodMonitor 예제 (쿠버네티스)​

StaticEndpoints 설정 요소​

params 쿼리 파라미터 설정​

메트릭 재라벨링 (metricRelabelConfigs)​

재라벨링 예제​

여러 OpenAgent 인스턴스의 설정 파일 관리​

pprof 프로파일링 엔드포인트​

서비스 화면에서 에이전트 설정하기​

옵션 추가하기​

옵션 수정 또는 삭제하기​

여러 에이전트에 동시 적용하기​

에이전트 설정 옵션 안내​