본문으로 건너뛰기

Azure Monitor Exporter 설정

주의

Azure Metrics Exporter 사용 시 비용 안내

Azure Metrics Exporter는 Azure Monitor API를 통해 메트릭을 조회하는 방식이므로, 조회되는 메트릭 수와 API 호출량에 따라 Azure Monitor 사용 요금이 발생할 수 있습니다. 요금은 Azure Monitor의 메트릭 쿼리, API 요청 등의 사용량 기준으로 부과되며, 자세한 내용은 Azure 공식 요금표를 참고하시기 바랍니다.

사전 준비 사항​

Azure 구독 및 권한 요구사항​

Azure 리소스 메트릭을 수집하기 위해 다음 권한이 필요합니다.

권한설명범위
Monitoring ReaderAzure Monitor 메트릭 읽기 권한Subscription 또는 Resource Group
Reader리소스 정보 조회(서비스 디스커버리용)Subscription 또는 Resource Group
노트

권장 설정

  • 최소 권한 원칙에 따라 Monitoring Reader 역할 사용
  • 특정 리소스 그룹만 모니터링할 경우 해당 범위로 제한

필수 Azure 리소스 정보 수집​

Exporter 설정에 필요한 정보를 미리 수집합니다.

항목설명예시
Subscription IDAzure 구독 식별자xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Tenant IDAzure AD 테넌트 식별자xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Client ID등록된 앱의 Application IDxxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Client Secret앱 인증용 비밀키xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Resource Group리소스 그룹명xxxxxxxxxx
Resource Name리소스 이름(서버명/캐시명/네임스페이스명/클러스터명 등)xxxxxxxxxx

Azure Metrics Exporter 설치​

Exporter 다운로드​

# linux/amd64 (x86_64)
wget https://repo.whatap.io/exporter/azure_metrics_exporter/amd64/azure_metrics_exporter

# linux/arm64 (aarch64)
wget https://repo.whatap.io/exporter/azure_metrics_exporter/arm64/azure_metrics_exporter

실행 권한 부여 및 설치​

chmod +x azure_metrics_exporter
sudo mv azure_metrics_exporter /usr/local/bin/azure_metrics_exporter
sudo mkdir -p /etc/azure_metrics_exporter

azure.yml 파일 설정​

팁

Azure Metrics Exporter를 사용하기 위해서는 수집 대상 리소스와 메트릭을 정의하는 azure.yml 설정 파일이 필요합니다. 수집할 서비스와 메트릭 항목을 선택한 후 설정 파일을 다운로드하여 Exporter가 설치된 서버에 배치합니다.

지원 서비스 목록​

주요 지원 서비스는 아래와 같으며 각 서비스의 상세 메트릭 정의는 Azure 공식 문서를 통해 확인할 수 있습니다. 아래 목록 외 추가 서비스 및 메트릭 정의는 Azure Monitor 공식 문서에서 확인할 수 있습니다.

ServiceAzure Docs
Microsoft.Compute virtualMachineshttps://learn.microsoft.com/en-us/azure/azure-monitor/reference/supported-metrics/microsoft-compute-virtualmachines-metrics
Microsoft.ContainerService managedClustershttps://learn.microsoft.com/en-us/azure/aks/monitor-aks-reference
Microsoft.Storage storageAccountshttps://learn.microsoft.com/en-us/azure/azure-monitor/reference/supported-metrics/microsoft-storage-storageaccounts-metrics
Microsoft.Sql servers databaseshttps://learn.microsoft.com/en-us/azure/azure-sql/database/monitoring-sql-database-azure-monitor-reference
Microsoft.DBforPostgreSQL flexibleServershttps://learn.microsoft.com/en-us/azure/postgresql/flexible-server/concepts-monitoring
Microsoft.DBforMySQL flexibleServershttps://learn.microsoft.com/en-us/azure/mysql/flexible-server/concepts-monitoring
Microsoft.DocumentDB databaseAccountshttps://learn.microsoft.com/en-us/azure/cosmos-db/monitor-cosmos-db
Microsoft.Cache redishttps://learn.microsoft.com/en-us/azure/redis/monitor-cache
Microsoft.EventHub namespaceshttps://learn.microsoft.com/en-us/azure/event-hubs/monitor-event-hubs-reference
Microsoft.ServiceBus namespaceshttps://learn.microsoft.com/en-us/azure/service-bus-messaging/monitor-service-bus-reference
Microsoft.KeyVault vaultshttps://learn.microsoft.com/en-us/azure/key-vault/general/monitor-key-vault
Microsoft.Network applicationGatewayshttps://learn.microsoft.com/en-us/azure/application-gateway/monitor-application-gateway

azure.yml 예시 파일​

# =============================================================================
# azure.yml example
#   - credentials:     authentication info (values collected in section 1.2)
#   - targets:         collect by directly specifying a resource
#   - resource_groups: auto-discover by resource group + name regex
#   - resource_tags:   auto-discover by tag
# =============================================================================

credentials:
  subscription_id: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  tenant_id:       "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  client_id:       "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  client_secret:   "xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

targets:
  # (1) No aggregations specified: collects all supported (Total/Average/Minimum/Maximum)
  - resource: /resourceGroups/example-rg/providers/Microsoft.DBforPostgreSQL/flexibleServers/myserver
    metrics:
      - name: cpu_percent
      - name: memory_percent

  # (2) Resource-level aggregation: applied as the default to all metrics in this target
  - resource: /resourceGroups/example-rg/providers/Microsoft.DBforPostgreSQL/flexibleServers/myserver
    aggregations:
      - Average
    metrics:
      - name: cpu_percent
      - name: memory_percent

  # (3) Metric-level aggregation: per-metric override (overrides the resource-level value)
  - resource: /resourceGroups/example-rg/providers/Microsoft.DBforPostgreSQL/flexibleServers/myserver
    aggregations:
      - Average                      # default for this target
    metrics:
      - name: cpu_percent            # -> Average (default applied)
      - name: memory_percent         # -> Average (default applied)
      - name: storage_percent
        aggregations:
          - Maximum                  # -> Maximum (overridden at metric level)
      - name: iops
        aggregations:
          - Total
          - Maximum                  # -> Total, Maximum

# Auto-discover by resource group + name regex
resource_groups:
  - resource_group: "webapps"
    resource_types:
      - "Microsoft.Compute/virtualMachines"
    resource_name_include_re:
      - "testvm.*"                   # include VMs whose name starts with testvm
    resource_name_exclude_re:
      - "testvm12"                   # exclude testvm12
    metrics:
      - name: "CPU Credits Consumed"
        aggregations:
          - "Average"

# Auto-discover by tag (resources tagged monitoring=enabled)
resource_tags:
  - resource_tag_name: "monitoring"
    resource_tag_value: "enabled"
    resource_types:
      - "Microsoft.Compute/virtualMachines"
    metrics:
      - name: "CPU Credits Consumed"
        aggregations:
          - "Average"
          - "Maximum"

서비스 등록 및 실행​

방법 A: systemd 서비스 등록​

sudo tee /etc/systemd/system/azure-metrics-exporter.service > /dev/null <<EOF
[Unit]
Description=Azure Metrics Exporter
After=network.target

[Service]
User=root
ExecStart=/usr/local/bin/azure_metrics_exporter --config.file=/etc/azure_metrics_exporter/azure.yml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable azure-metrics-exporter
sudo systemctl start azure-metrics-exporter
sudo systemctl status azure-metrics-exporter

방법 B: nohup 실행​

nohup /usr/local/bin/azure_metrics_exporter \
  --config.file=/etc/azure_metrics_exporter/azure.yml \
  > /var/log/azure_metrics_exporter.log 2>&1 &

메트릭 수집 확인 및 트러블슈팅​

# 전체 메트릭 확인
curl http://localhost:9276/metrics

# PostgreSQL 메트릭 필터링
curl http://localhost:9276/metrics | grep -i postgres
  • 정상 출력 예시
# HELP azure_microsoft_dbforpostgresql_flexibleservers_cpu_percent_percent_average
# TYPE azure_microsoft_dbforpostgresql_flexibleservers_cpu_percent_percent_average gauge
azure_microsoft_dbforpostgresql_flexibleservers_cpu_percent_percent_average{...} 3.5
  • 메트릭 이름 변환 규칙: azure_{namespace}_{metric명}_{단위}_{집계방식}

트러블슈팅​

증상원인해결 방법
401 UnauthorizedAzure 인증 실패credentials 입력값 확인
403 Forbidden권한 부족서비스 주체에 Monitoring Reader 권한 부여
메트릭 값 없음Enhanced 메트릭 비활성화서버 파라미터 활성화
서버 중지 상태DB 중지됨az postgres flexible-server start 실행

OpenAgent 다운로드 및 설정​

모든 파일은 동일한 디렉토리에 위치해야 합니다.

## Example
/opt/whatap/openagent/
├── openagent          # Executable file
├── whatap.conf        # Configuration file
└── scrape_config.yaml # Scraping configuration file

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

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

## AMD64 (Intel/AMD 64-bit processor)
wget https://repo.whatap.io/openagent/latest/amd/openagent

## ARM64 (ARM processor in Linux environment)
## CAUTION: macOS Apple Silicon not supported
wget https://repo.whatap.io/openagent/latest/arm/openagent

실행 권한 설정​

chmod +x openagent

scrape_config.yaml 생성​

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

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

기본 실행​

./openagent standalone

백그라운드 실행​

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

로그 확인​

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

프로세스 관리​

# Check process
ps aux | grep openagent

# Terminate process
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 등 특정 파라미터가 필요한 엑스포터와 연동할 때 유용합니다.

params 설정 형태​

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

지원되는 파라미터 값 타입​

  • 문자열: 단일 값

  • 문자열 배열: 여러 값을 콤마로 연결

  • 기타 타입: 자동으로 문자열로 변환

메트릭 재라벨링 설정(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. 특정 메트릭만 유지

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

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

  • 동작 예시
# 원본
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

# 적용 후
http_requests_total{method="GET", status="200"} 100

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

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

# 적용 후
node_cpu_seconds_total{cpu="0", mode="idle"} 1000
node_memory_MemTotal_bytes{} 16777216

4. 레이블 이름 변경

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="GET", path="/api", status="200", http_method="GET"} 100

5. 여러 소스 레이블 조합

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

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

6. 정적 레이블 추가

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

# 적용 후
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
  1. 첫 번째 룰(keep apiserver_request_total) 적용: apiserver_request_total 유지, some_other_metric 드롭
  2. 두 번째 룰(replace verb → http_verb) 적용: verb 레이블 값을 http_verb 레이블로 복사
  • 최종 수집 메트릭
apiserver_request_total{code="200", resource="pods", verb="GET", http_verb="GET"} 100
최종 수정: