오픈에이전트 구성

OpenAgent는 프로메테우스 엔드포인트에서 메트릭을 스크래핑하고, 이를 처리하여 와탭 서버로 전송하는 역할을 합니다. 프로메테우스 엔드포인트에서 메트릭을 수집하고 와탭 서버로 전송하는 Go 기반 에이전트입니다.

설정

단독 yaml로 설치하는 경우

기본적으로 오픈 에이전트는 whatap-monitoring 네임스페이스에 생성됩니다. 필요에 따라 조정할 수 있습니다.

# Whatap Open Agent standalone manifests
# 네임스페이스는 필요에 따라 조정하세요. 예시로 whatap-monitoring을 사용합니다.
---
#apiVersion: v1
#kind: Namespace
#metadata:
#  name: whatap-monitoring
---
# Whatap 접속 정보 (라이센스/호스트/포트)
# 이미 동일한 이름의 Secret을 별도로 만들어 두었다면 이 Secret 블록을 삭제하고,
# 아래 Deployment의 secretKeyRef.name을 기존 Secret 이름과 맞추면 됩니다.
apiVersion: v1
kind: Secret
metadata:
  name: whatap-open-credentials
  namespace: whatap-monitoring
type: Opaque
stringData:
  WHATAP_LICENSE: "<YOUR_LICENSE>"
  WHATAP_HOST: "<WHATAP_HOST>"
  WHATAP_PORT: "6600"

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: whatap-open-agent-sa
  namespace: whatap-monitoring

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: whatap-open-agent-role
rules:
  - apiGroups: ["*"]
    resources: ["pods", "services", "endpoints", "endpointslices", "namespaces", "secrets"]
    verbs: ["get", "list", "watch"]
  - nonResourceURLs: ["/metrics"]
    verbs: ["*"]
  - apiGroups: [""]
    resources: ["pods/exec"]
    verbs: ["create"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["*"]
  - nonResourceURLs: ["/metrics"]
    verbs: ["*"]

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: whatap-open-agent-role-binding
subjects:
  - kind: ServiceAccount
    name: whatap-open-agent-sa
    namespace: whatap-monitoring
roleRef:
  kind: ClusterRole
  name: whatap-open-agent-role
  apiGroup: rbac.authorization.k8s.io

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: whatap-open-agent-config
  namespace: whatap-monitoring
data:
  scrape_config.yaml: |
    features:
      openAgent:
        enabled: true
        globalInterval: "60s"
        globalPath: "/metrics"
        targets:
          - targetName: kube-apiserver
            type: ServiceMonitor
            namespaceSelector:
              matchNames:
                - "default"  # API 서버 서비스가 있는 네임스페이스로 변경
            selector:
              matchLabels:
                component: apiserver
                provider: kubernetes
            endpoints:
              - port: "https"
                path: "/metrics"
                interval: "30s"
                scheme: "https"
                timeout: "30s"
                tlsConfig:
                  insecureSkipVerify: true
                metricRelabelConfigs:
                  - source_labels: [__name__]
                    regex: "apiserver_request_total"
                    action: keep
                  - source_labels: [verb]
                    target_label: http_verb
                    replacement: "${1}"
                    action: replace
                  - target_label: metric_src
                    replacement: "whatap-open-agent"
                    action: replace

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: whatap-open-agent
  namespace: whatap-monitoring
  labels:
    name: whatap-open-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      name: whatap-open-agent
  template:
    metadata:
      labels:
        name: whatap-open-agent
    spec:
      serviceAccountName: whatap-open-agent-sa
      volumes:
        - name: config-volume
          configMap:
            name: whatap-open-agent-config
        - name: logs-volume
          emptyDir: {}
      containers:
        - name: whatap-open-agent
          image: public.ecr.aws/whatap/open_agent:latest
          imagePullPolicy: Always
          resources:
            requests:
              memory: "300Mi"
              cpu: "100m"
            limits:
              memory: "1000Mi"
              cpu: "1000m"
          env:
            - name: WHATAP_LICENSE
              valueFrom:
                secretKeyRef:
                  name: whatap-open-credentials
                  key: WHATAP_LICENSE
            - name: WHATAP_HOST
              valueFrom:
                secretKeyRef:
                  name: whatap-open-credentials
                  key: WHATAP_HOST
            - name: WHATAP_PORT
              valueFrom:
                secretKeyRef:
                  name: whatap-open-credentials
                  key: WHATAP_PORT
            - name: debug
              value: "false"
          volumeMounts:
            - name: config-volume
              mountPath: /app/scrape_config.yaml
              subPath: scrape_config.yaml
            - name: logs-volume
              mountPath: /app/logs
          # 필요 시 컨테이너/노드 톨러레이션, affinity 등을 추가하십시오.

helm 설치

1. 다음 명령어를 실행해 와탭 Helm 리포지토리를 추가하세요.

   helm repo add whatap https://whatap.github.io/helm/
   helm repo update

2. 에이전트를 처음 설치하는 사용자는 다음 명령어를 실행해 에이전트 애플리케이션을 설치하세요. values.yaml은 아래 예시를 참고합니다.

   처음 설치

   #에이전트를 처음 설치하는 사용자는 다음 명령어를 실행해 에이전트 애플리케이션을 설치하세요.
   kubectl create ns whatap-monitoring
   helm install whatap-kube-agent --namespace whatap-monitoring whatap/kube -f values.yaml

   기존 사용자

   #기존 와탭 쿠버네티스 에이전트 사용자는 다음 명령어를 실행해 에이전트를 설치하세요.
   #*기존 yaml 파일 방식으로 와탭 쿠버네티스 에이전트를 설치한 경우 Clean Install이 필요합니다. 기존 쿠버네티스 에이전트 삭제 후 Helm 차트를 통한 설치가 가능합니다.
   kubectl delete ns whatap-monitoring
   kubectl delete clusterrole whatap
   kubectl delete clusterrolebinding whatap
   kubectl create ns whatap-monitoring
   helm install whatap-kube-agent --namespace whatap-monitoring whatap/kube -f values.yaml

values.yaml

whatap:
  license: #라이센스 키 입력
  host: #수집서버 IP 입력
  port: #수집서버 Port 입력
  createSecret: true #default : true, if credentials already exist, set false
  existingSecretName: "whatap-credentials" #default : whatap-credentials
collect_custom_resources: true
containerRuntime: "containerd"
deployment:
  containers:
    controlPlaneHelper:
      enabled: false
      image: "whatap/kube_mon:1.8.8"
      name: "whatap-control-plane-helper"
      port: 9496
      resources:
        limits:
          cpu: "200m"
          memory: "350Mi"
        requests:
          cpu: "100m"
          memory: "300Mi"
    masterAgent:
      image: "whatap/kube_mon:1.8.8"
      name: "whatap-master-agent"
      port: 6600
      resources:
        limits:
          cpu: "200m"
          memory: "350Mi"
        requests:
          cpu: "100m"
          memory: "300Mi"
  label: "whatap-master-agent"
  name: "whatap-master-agent"
  replicas: 1

daemonSet:
  containers:
    nodeAgent:
      image: "whatap/kube_mon:1.8.8"
      limits:
        cpu: "200m"
        memory: "350Mi"
      name: "whatap-node-agent"
      requests:
        cpu: "100m"
        memory: "300Mi"
    nodeHelper:
      image: "whatap/kube_mon:1.8.8"
      limits:
        cpu: "200m"
        memory: "350Mi"
      name: "whatap-node-helper"
      requests:
        cpu: "100m"
        memory: "100Mi"
  initContainers:
    nodeDebugger:
      enabled: false
      image: "whatap/kube_mon:1.8.8"
      name: "whatap-node-debug"
  label: "whatap-node-agent"
  name: "whatap-node-agent"

clusterrole:
  extraResources:
  - "*"

deploymentOpen:
  enabled: true
  containers:
    openAgent:
      image: "public.ecr.aws/whatap/open_agent:latest"
  config:
    features:
      openAgent:
        enabled: true
        #globalInterval: "60s"
        #globalPath: "/metrics"
        targets:
          - targetName: "kube-apiserver"
            type: "ServiceMonitor"
            enabled: true
            namespaceSelector:
              matchNames:
                - "default"   # 클러스터 기본 레이블에 맞게 조정
            selector:
              matchLabels:
                component: "apiserver"
                provider: "kubernetes"
            endpoints:
              - port: "https"
                path: "/metrics"
                interval: "30s"
                scheme: "https"
                timeout: "30s"
                tlsConfig:
                  insecureSkipVerify: true   # 자체서명 인증서일 때 편의용, 보안 필요 시 false + CA 지정
                metricRelabelConfigs:
                  - source_labels: [__name__]
                    regex: "apiserver_request_total"
                    action: keep
                  - source_labels: [verb]
                    target_label: http_verb
                    replacement: "${1}"
                    action: replace
                  - target_label: metric_src
                    replacement: "whatap-open-agent"
                    action: replace

WhatapOperator 설치 후, 사용자는 WhatapAgent CR(Custom Resource)을 통해 OpenMetrics 대상을 설정합니다.

1. PodMonitor: Pod 레이블 셀렉터를 이용한 동적 디스커버리 (Prometheus Operator의 PodMonitor와 유사)

2. ServiceMonitor: Service 레이블 셀렉터를 이용한 동적 디스커버리 (Prometheus Operator의 ServiceMonitor와 유사)

3. StaticEndpoints: 고정된 IP 주소와 포트를 직접 입력 (Prometheus의 static_configs와 유사)

features:
  openAgent:
    enabled: true
    targets:
      # 1. PodMonitor: Pod 레이블 셀렉터를 이용한 동적 디스커버리
      - targetName: my-app-pod-metrics
        type: PodMonitor
        namespaceSelector:
          matchNames:
            - "production"
        selector:
          matchLabels:
            app: my-app
        endpoints:
        - port: "web-metrics"  # Pod Spec에 정의된 Port 이름 또는 실제 Port 번호
          path: "/metrics"     # 기본값은 /metrics, 필요시 재정의
          interval: "15s"      # 기본값은 전역 설정, 필요시 재정의
          scheme: "http"
          timeout: "10s"
          metricRelabelConfigs:  # 스크래핑 후 메트릭 재라벨링 설정
            - source_labels: [__name__]
              regex: "http_requests_total"
              action: keep
            - source_labels: [method]
              target_label: http_method
              replacement: "${1}"
              action: replace

      # 2. ServiceMonitor: Service 레이블 셀렉터를 이용한 동적 디스커버리
      - targetName: my-service-metrics
        type: ServiceMonitor
        namespaceSelector:
          matchNames:
            - "default"
        selector:
          matchLabels:
            service: my-backend-service
        endpoints:
        - port: "http-metrics"  # Service Spec에 정의된 Port 이름 또는 실제 Target Port 번호
          path: "/actuator/prometheus"
          interval: "30s"
          metricRelabelConfigs:
            - source_labels: [__name__]
              regex: "jvm_.*"
              action: keep
            - source_labels: [area]
              target_label: memory_area
              replacement: "${1}"
              action: replace

      # 3. StaticEndpoints: 고정된 IP 주소와 포트를 직접 입력
      - targetName: my-external-db-metrics
        type: StaticEndpoints
        # enabled: true  # 타겟 활성화 여부 (기본값: true, 생략 가능)
        endpoints:
          - address: "192.168.1.100:9100"
            scheme: "http"
            path: "/metrics"
            interval: "60s"
            metricRelabelConfigs:
              - source_labels: [__name__]
                regex: "node_(cpu|memory).*"
                action: keep
              - source_labels: [instance]
                target_label: server
                replacement: "${1}"
                action: replace

PodMetrics 및 ServiceMetrics 설정 요소

• targetName: 타겟의 이름(로깅 및 식별용)

• type: 타겟 유형("PodMetrics" 또는 "ServiceMetrics")

• namespaceSelector: 스크래핑할 네임스페이스

  • matchNames: 이름으로 네임스페이스 선택
  • matchLabels: 레이블로 네임스페이스 선택
  • matchExpressions: 표현식으로 네임스페이스 선택

• selector: 스크래핑할 파드 또는 서비스 선택

  • matchLabels: 레이블로 파드 또는 서비스 선택
  • matchExpressions: 표현식으로 파드 또는 서비스 선택

• relabelConfigs: 타겟 발견(Discovery) 단계에서 메타데이터(meta 라벨 등)를 기반으로 라벨을 추가하거나 변경합니다.(프로메테우스의 relabel_configs와 유사)

• endpoints: 스크래핑할 엔드포인트 정의

  • port: 스크래핑할 포트 이름 또는 번호
  • path: 메트릭 경로(기본값은 globalPath, 필요시 재정의)
  • interval: 스크래핑 간격(기본값은 globalInterval, 필요시 재정의)
  • scheme: 스크래핑 프로토콜(http 또는 https, 기본값 http)
  • timeout: 스크래핑 타임아웃
  • honorLabels: 대상에서 제공하는 레이블을 우선시할지 여부
  • metricRelabelConfigs: 스크래핑 후 메트릭 재라벨링 설정(프로메테우스의 metric_relabel_configs와 유사)

StaticEndpoints 설정 요소

• targetName: 타겟의 이름(로깅 및 식별용)

• type: 타겟 유형("StaticEndpoints")

• endpoints: 스크래핑할 엔드포인트 정의

  • address: 스크래핑할 대상 주소 (IP:PORT 또는 HOSTNAME:PORT)

  • path: 메트릭 경로 (기본값: /metrics)

  • scheme: 스크래핑 프로토콜 (http 또는 https, 기본값 http)

  • interval: 스크래핑 간격 (기본값: 60s)

  • tlsConfig: TLS 설정

  • metricRelabelConfigs: 스크래핑 후 메트릭 재라벨링 설정

addNodeLabel 기능

스크랩 대상이 노드에 스케쥴링 되어 있는 경우  addNodeLabel 옵션을 사용하여 스케줄링된 노드의 이름을 메트릭에 라벨로 추가할 수 있습니다.

• 설정 위치: 타겟 레벨 또는 엔드포인트 레벨에서 설정 가능

• 기본값: false

• 동작: true로 설정하면 모든 메트릭에 node 라벨이 추가되며, 오브젝트가 실행 중인 노드의 이름이 값으로 추가됨

사용 예제

# 타겟 레벨에서 addNodeLabel 설정
- targetName: node-exporter
  type: PodMonitor
  namespaceSelector:
    matchNames:
      - "monitoring"
  selector:
    matchLabels:
      app: node-exporter
  endpoints:
    - port: "metrics"
      path: "/metrics"
      interval: "30s"
      addNodeLabel: true  # 이 엔드포인트에 노드 라벨 추가
      metricRelabelConfigs:
        # 노드 라벨을 사용한 재라벨링 예제
        - source_labels: [node]
          target_label: kubernetes_node
          action: replace

# 엔드포인트 레벨에서 addNodeLabel 설정
- targetName: dcgm-exporter
  type: PodMonitor
  namespaceSelector:
    matchNames:
      - "kube-system"
  selector:
    matchLabels:
      app: dcgm-exporter
  endpoints:
  - port: "metrics"
    path: "/metrics"
    interval: "30s"
    addNodeLabel: true  # 이 엔드포인트에만 노드 라벨 추가
		metricRelabelConfigs:
      - source_labels: [node]
        target_label: gpu_node
        action: replace

Basic Auth 설정

OpenAgent는 인증이 필요한 엔드포인트를 스크래핑하기 위해 HTTP Basic Authentication을 지원합니다. 사용자 이름(username)과 비밀번호(password)는 Kubernetes Secret을 통해 안전하게 관리됩니다.

• 설정 위치: endpoints 하위의 basicAuth 항목에서 설정

• username: 사용자 이름을 담고 있는 Secret 정보

  • name: Secret의 이름
  • key: Secret 내의 Key
  • namespace: Secret이 위치한 네임스페이스 (생략 시 에이전트와 동일한 네임스페이스)

• password: 비밀번호를 담고 있는 Secret 정보

  • name: Secret의 이름
  • key: Secret 내의 Key
  • namespace: Secret이 위치한 네임스페이스

설정 예제

endpoints:
  - port: "metrics"
    path: "/metrics"
    basicAuth:
      username:
        name: my-auth-secret
        key: username
      password:
        name: my-auth-secret
        key: password
        namespace: monitoring # Secret이 다른 네임스페이스에 있는 경우 명시

TLS 설정

OpenAgent는 HTTPS 엔드포인트에 연결할 때 TLS(Transport Layer Security)를 지원합니다. 다음은 TLS 관련 설정 옵션입니다.

HTTP vs HTTPS 결정 방법

OpenAgent는 다음과 같은 규칙에 따라 HTTP 또는 HTTPS 프로토콜을 사용할지 결정합니다.

• PodMonitor 및 ServiceMonitor 타겟

  • 포트 이름이 "https"인 경우 기본적으로 HTTPS를 사용합니다.
  • 그 외의 경우 기본적으로 HTTP를 사용합니다.

• StaticEndpoints 타겟

  • TLS 설정이 존재하는 경우 기본적으로 HTTPS를 사용합니다.
  • 그 외의 경우 기본적으로 HTTP를 사용합니다.

• 모든 타겟 유형

  • 엔드포인트나 타겟에 명시적으로 scheme 설정이 있는 경우, 이 설정이 기본값을 재정의합니다.

TLS 설정 옵션

TLS 설정은 tlsConfig 섹션에서 구성할 수 있습니다.

endpoints:
  - port: "https"
    path: "/metrics"
    scheme: "https"  # 명시적으로 HTTPS 사용 지정
    tlsConfig:
      insecureSkipVerify: true  # 인증서 검증 건너뛰기

insecureSkipVerify

insecureSkipVerify 옵션은 서버 인증서의 유효성 검사를 건너뛰도록 설정합니다. 이 옵션은 다음과 같은 경우에 유용합니다.

• 자체 서명된 인증서를 사용하는 서버에 연결할 때
• 개발 또는 테스트 환경에서 인증서 검증이 필요하지 않을 때
• 내부 네트워크에서 신뢰할 수 있는 서버에 연결할 때

warning

주의

프로덕션 환경에서는 보안상의 이유로 insecureSkipVerify: false를 사용하는 것이 좋습니다. 자체 서명된 인증서를 사용하는 경우, 인증서를 신뢰할 수 있는 인증 기관(CA)으로 추가하는 것이 더 안전한 방법입니다.

설정 예제

ServiceMonitor에서 TLS 설정 예제

- targetName: kube-apiserver
  type: ServiceMonitor
  namespaceSelector:
    matchNames:
      - "default"
  selector:
    matchLabels:
      component: apiserver
      provider: kubernetes
  endpoints:
    - port: "https"  # 포트 이름이 "https"이므로 기본적으로 HTTPS 사용
      path: "/metrics"
      interval: "30s"
      scheme: "https"  # 명시적으로 HTTPS 지정 (선택사항)
      tlsConfig:
        insecureSkipVerify: true  # 인증서 검증 건너뛰기
      metricRelabelConfigs:
        - source_labels: [__name__]
          regex: "apiserver_request_total"
          action: keep
        - source_labels: [verb]
          target_label: http_verb
          replacement: "${1}"
          action: replace

타겟 재라벨링 설정(relabel Configs)

relabelConfigs는 스크래핑을 수행하기 전, 타겟(Target) 자체의 메타데이터를 기반으로 필터링하거나 라벨을 조작하는 기능입니다. (Prometheus의 relabel_configs와 유사)

1. 타겟 필터링 (Target Filtering)

   • 특정 메타데이터 조건을 만족하지 않는 타겟을 수집 대상에서 제외합니다.
   • 주요 Action: keep, drop

2. 메타 라벨 승격 (Meta Label Promotion)

   • __meta_로 시작하는 메타데이터는 스크래핑 후 사라집니다.
   • 영구적인 라벨로 저장하려면 이 단계에서 replace action을 사용하여 새로운 이름으로 변경해야 합니다.

Meta Labels 목록

OpenAgent에서 제공하는 주요 메타 라벨 목록입니다.

Common (공통)

• __meta_kubernetes_namespace: 오브젝트의 네임스페이스
• __address__: 타겟 주소 (IP:Port)

PodMonitor

• __meta_kubernetes_pod_name: Pod 이름
• __meta_kubernetes_pod_ip: Pod IP
• __meta_kubernetes_pod_ready: Pod 준비 상태 (true/false)
• __meta_kubernetes_pod_phase: Pod 상태 (Running, Pending 등)
• __meta_kubernetes_pod_node_name: Pod가 실행 중인 노드 이름
• __meta_kubernetes_pod_label_<labelname>: Pod의 라벨
• __meta_kubernetes_pod_annotation_<annotationname>: Pod의 어노테이션

ServiceMonitor

• __meta_kubernetes_service_name: Service 이름
• __meta_kubernetes_service_cluster_ip: Cluster IP
• __meta_kubernetes_service_label_<labelname>: Service의 라벨

targets:
  - targetName: my-pod-monitor
    type: PodMonitor
    selector:
      matchLabels:
        app: my-app
    # 타겟 발견 단계의 라벨링
    relabelConfigs:
      # 1. Pod 이름을 pod_name 라벨로 저장 (메트릭에 pod_name 라벨이 붙음)
      - source_labels: ["__meta_kubernetes_pod_name"]
        target_label: "pod_name"
        action: "replace"
      
      # 2. 특정 라벨(scrape_enabled=true)이 없는 Pod는 수집 제외
      - source_labels: ["__meta_kubernetes_pod_label_scrape_enabled"]
        regex: "true"
        action: "keep"

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

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

재라벨링 설정 요소

• source_labels: 소스 레이블 목록(배열)

• separator: 소스 레이블 값을 연결할 때 사용할 구분자(기본값: ;)

• target_label: 대상 레이블(결과를 저장할 레이블)

• regex: 소스 레이블 값에 적용할 정규식

• replacement: 대체 값(정규식 캡처 그룹 참조 가능, 예: ${1})

• action: 수행할 작업(keep, drop, replace)

지원되는 작업(action)

• keep: 정규식과 일치하는 메트릭만 유지

• drop: 정규식과 일치하는 메트릭 제거

• replace: 대상 레이블의 값을 대체 값으로 변경

특수 레이블

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

예제

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

이 설정은 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

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

이 설정은 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

예제 3. 레이블 이름 변경

이 설정은 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

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

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

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

• 동작 예시

  원래 스크랩된 메트릭이 다음과 같다고 가정합니다.

  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

예제 5. 정적 레이블 추가

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

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

• 동작 예시

  원래 스크랩된 메트릭이 다음과 같다고 가정해 봅시다:

  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

쿠버네티스 메트릭 수집 예제

다음은 쿠버네티스 API 서버에서 메트릭을 수집하는 예제입니다.

• 이 설정은 kube-system 네임스페이스에서 component=apiserver 및 provider=kubernetes 레이블을 가진 서비스를 찾아 해당 서비스의 엔드포인트에서 메트릭을 수집합니다.

• metricRelabelConfigs를 사용하여 apiserver_request_total 메트릭만 수집하고, verb 레이블을 http_verb 레이블로 변환하며, 모든 메트릭에 metric_src="whatap-open-agent" 정적 레이블을 추가하도록 지정할 수 있습니다.

쿠버네티스 메트릭 수집 예제

# scrape_config.yaml
features:
  openAgent:
    enabled: true
    targets:
      - targetName: kube-apiserver
        type: ServiceMonitor
        namespaceSelector:
          matchNames:
            - "kube-system"
        selector:
          matchLabels:
            component: apiserver
            provider: kubernetes
        endpoints:
          - port: "https"
            path: "/metrics"
            interval: "30s"
            metricRelabelConfigs:
              - source_labels: [__name__]
                regex: "apiserver_request_total"
                action: keep
              - source_labels: [verb]
                target_label: http_verb
                replacement: "${1}"
                action: replace
              # 정적 레이블 추가
              - target_label: metric_src
                replacement: "whatap-open-agent"
                action: replace