OpenMetrics 설치

노트

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
  - source_labels: [__name__]
    regex: "node.*"
    action: drop

예제 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를 적용하면 최종적으로 수집되는 메트릭은 다음과 같습니다.

1. 첫 번째 룰(keep apiserver_request_total) 적용

   • apiserver_request_total 메트릭은 유지됩니다.
   • some_other_metric 메트릭은 드롭됩니다.

2. 두 번째 룰(replace verb → http_verb) 적용

   • 유지된 apiserver_request_total 메트릭에 verb 레이블이 있으므로, 이 레이블의 값(GET)이 http_verb라는 새로운 레이블로 복사됩니다.

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