REST API를 사용하여 Azure 리소스에 대한 사용자 지정 메트릭 수집

아티클
01/08/2024

이 문서에서는 REST API를 통해 Azure Monitor 메트릭 저장소에 Azure 리소스에 대한 사용자 지정 메트릭을 보내는 방법을 보여 줍니다. Azure Monitor에 메트릭이 있으면 표준 메트릭으로 수행하는 모든 작업을 해당 메트릭으로 수행할 수 있습니다. 예를 들어, 차트 및 경고를 생성하고 메트릭을 다른 외부 도구로 라우팅할 수 있습니다.

참고 항목

REST API는 Azure 리소스에 대한 사용자 지정 메트릭 보내기만 허용합니다. 다른 환경이나 온-프레미스의 리소스에 대한 메트릭을 보내려면 Application Insights를 사용합니다.

사용자 지정 메트릭을 수집하기 위해 REST 요청 보내기

Azure Monitor에 사용자 지정 메트릭을 보낼 때 메트릭에 보고되는 각 데이터 요소 또는 값은 다음 정보를 포함해야 합니다.

인증 토큰
주제
지역
Timestamp
네임스페이스
이름
차원 키
차원 값
메트릭 값

인증

사용자 지정 메트릭을 Azure Monitor로 전송하려면 메트릭을 전송하는 엔터티에 유효한 Microsoft Entra 토큰이 요청의 전달자 헤더에 있어야 합니다. 유효한 전달자 토큰을 획득하는 지원되는 방법은 다음과 같습니다.

Azure 리소스에 대한 관리 ID 관리 ID를 사용하여 리소스에 특정 작업을 수행할 수 있는 권한을 부여할 수 있습니다. 예를 들어, 리소스가 해당 지표를 내보낼 수 있도록 허용합니다. 리소스 또는 해당 관리 ID에 다른 리소스에 대한 모니터링 메트릭 게시자 권한을 부여할 수 있습니다. 이 권한을 사용하면 관리 ID가 다른 리소스에 대한 지표도 내보낼 수 있습니다.
Microsoft Entra 서비스 주체. 이 시나리오에서는 Azure 리소스에 대한 메트릭을 내보내는 권한을 Microsoft Entra 애플리케이션 또는 서비스에 할당할 수 있습니다. 요청을 인증하기 위해 Azure Monitor는 Microsoft Entra 공개 키를 사용하여 애플리케이션 토큰의 유효성을 검사합니다. 기존 모니터링 메트릭 게시자 역할에는 이 사용 권한이 이미 있으며, Azure Portal에서 사용할 수 있습니다.

서비스 주체는 사용자 지정 메트릭을 내보낼 리소스에 따라 필요한 범위에서 모니터링 메트릭 게시자 역할을 부여받을 수 있습니다. 범위의 예로 구독, 리소스 그룹 또는 특정 리소스가 있습니다.

팁

사용자 지정 메트릭을 내보내기 위해 Microsoft Entra 토큰을 요청하는 경우 토큰이 요청되는 대상 그룹 또는 리소스가 https://monitoring.azure.com/이어야 합니다. 후행 슬래시를 포함해야 합니다.

권한 부여 토큰 가져오기

관리 ID 또는 서비스 주체를 만들고 모니터링 메트릭 게시자 권한을 할당한 후에는 다음 요청을 사용하여 권한 부여 토큰을 가져올 수 있습니다.

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.com'

응답 본문의 형식은 다음과 같습니다.

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "https://monitoring.azure.com",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

다음 HTTP 요청에 사용할 응답의 액세스 토큰을 저장합니다.

Subject

주체 속성은 사용자 지정 메트릭이 보고되는 Azure 리소스 ID를 캡처합니다. 이 정보는 API 호출의 URL에 인코딩됩니다. 각 API는 단일 Azure 리소스에 대해서만 메트릭 값을 제출할 수 있습니다.

참고 항목

리소스 그룹 또는 구독의 리소스 ID에 대해서는 사용자 지정 메트릭을 내보낼 수 없습니다.

지역

지역 속성은 메트릭을 내보내는 리소스가 배포되는 Azure 지역을 캡처합니다. 메트릭은 리소스가 배포되는 지역과 동일한 Azure Monitor 지역 엔드포인트에 배포되어야 합니다. 예를 들어, 미국 서부에 배포된 VM에 대한 사용자 지정 메트릭은 WestUS 지역별 Azure Monitor 엔드포인트에 전송되어야 합니다. 또한 지역 정보는 API 호출의 URL에 인코딩됩니다.

타임스탬프

Azure Monitor에 전송되는 각 데이터 요소는 타임스탬프를 사용하여 표시되어야 합니다. 이 타임스탬프는 메트릭 값이 측정 또는 수집된 날짜 및 시간을 캡처합니다. Azure Monitor는 과거 20분 및 미래 5분까지의 타임스탬프가 지정된 메트릭 데이터를 허용합니다. 타임스탬프는 ISO 8601 형식이어야 합니다.

네임스페이스

네임스페이스는 유사한 메트릭을 함께 분류 또는 그룹화하는 방법입니다. 네임스페이스를 사용하면 각기 다른 인사이트 또는 성능 지표를 수집할 수 있는 메트릭 그룹을 격리할 수 있습니다. 예를 들어, 앱을 프로파일링하는 메모리 사용 메트릭을 추적하는 ContosoMemoryMetrics라는 네임스페이스가 있을 수 있습니다. contosoapptransaction이라는 또 다른 네임스페이스는 애플리케이션의 사용자 트랜잭션에 대한 모든 메트릭을 추적할 수 있습니다.

이름

이름 속성은 보고되는 메트릭의 이름입니다. 일반적으로 이름은 측정 대상을 식별하기에 충분한 정보를 제공합니다. 예를 들어, VM에서 사용된 메모리 바이트 수를 측정하는 메트릭이 있습니다. 메트릭 이름은 사용 중인 메모리 바이트일 수 있습니다.

차원 키

차원은 수집 중인 메트릭에 대한 다른 특성을 설명할 수 있도록 하는 키/값 쌍입니다. 다른 특성을 사용하면 메트릭에 대한 더 많은 정보를 수집할 수 있으므로 더 깊은 인사이트를 얻을 수 있습니다.

예를 들어, 사용 중인 메모리 바이트 메트릭에는 VM의 각 프로세스에서 사용 중인 메모리 바이트 수를 캡처하는 프로세스라는 차원 키가 있을 수 있습니다. 이 키를 사용하여 메트릭을 필터링하면 특정 프로세스에서 사용하는 메모리 양을 확인하거나 메모리 사용량에 따른 상위 5개 프로세스를 식별할 수 있습니다.

차원은 선택 사항이며, 모든 메트릭에 차원이 포함되는 것은 아닙니다. 사용자 지정 메트릭에는 최대 10개의 차원이 있을 수 있습니다.

차원 값

메트릭 데이터 요소를 보고하는 경우 보고된 메트릭의 각 차원 키에 해당하는 차원 값이 있습니다. 예를 들어, VM의 ContosoApp에서 사용하는 메모리를 보고하려는 경우

메트릭 이름은 사용 중인 메모리 바이트가 됩니다.
차원 키는 프로세스가 됩니다.
차원 값은 ContosoApp.exe가 됩니다.

메트릭 값을 게시하는 경우 차원 키당 단일 차원 값만 지정할 수 있습니다. VM의 여러 프로세스에 대해 수집한 메모리 사용률이 동일한 경우 해당 타임스탬프에 여러 개의 메트릭 값을 보고할 수 있습니다. 각 메트릭 값은 프로세스 차원 키에 대해 다른 차원 값을 지정합니다.

차원은 선택 사항이지만 메트릭 게시물에서 차원 키를 정의하는 경우 해당 차원 값은 필수입니다.

메트릭 값

Azure Monitor는 모든 메트릭을 1분 세분성 간격으로 저장합니다. 지정된 1분 동안 메트릭을 여러 번 샘플링해야 하는 경우도 있습니다. 예를 들면 CPU 사용률이 있습니다. 또는 로그인 트랜잭션 대기 시간과 같은 여러 개별 이벤트에 대해 메트릭을 측정해야 할 수도 있습니다.

내보내야 하는 원시 값의 수를 제한하고 Azure Monitor에서 요금을 지불하려면 다음 값을 로컬로 미리 집계하고 집계한 값을 내보낼 수 있습니다.

최소: 1분 동안 모든 샘플 및 측정값에서 관찰된 최솟값입니다.
최대: 1분 동안 모든 샘플 및 측정값에서 관찰된 최댓값입니다.
합계: 1분 동안 모든 샘플 및 측정값에서 관찰된 모든 값의 합계입니다.
개수: 1분 동안 수행된 샘플 및 측정값 수입니다.

참고 항목

Azure Monitor는 사용자 지정 메트릭에 대한 단위 정의를 지원하지 않습니다.

예를 들어 1분 동안 앱에 네 번의 로그인 트랜잭션이 있었다면 각각에 대해 측정된 대기 시간은 다음과 같을 수 있습니다.

거래 1	거래 2	트랜잭션 3	트랜잭션 4
7ms	4밀리초	13ms	16밀리초

Azure Monitor에 대한 결과 메트릭 게시는 다음과 같습니다.

최소: 4
최대: 16
합계: 40
개수: 4

애플리케이션이 로컬로 미리 집계할 수 없고 각 불연속 샘플 또는 이벤트를 수집되는 즉시 내보내야 하는 경우 원시 측정 값을 내보낼 수 있습니다. 예를 들어, 앱에서 로그인 트랜잭션이 발생할 때마다 단일 측정값만 사용하여 메트릭을 Azure Monitor에 게시합니다. 따라서 12밀리초가 소요된 로그인 트랜잭션의 경우 메트릭 게시는 다음과 같습니다.

최소: 12
최대: 12
합계: 12
개수: 1

이 프로세스에서는 지정된 1분 동안 동일한 메트릭/차원 조합에 대해 여러 개의 값을 내보낼 수 있습니다. 그런 다음, Azure Monitor에서 지정된 1분 동안 내보낸 모든 원시 값을 가져와 집계합니다.

샘플 사용자 지정 메트릭 게시

다음 예제에서는 가상 머신에 대한 메모리 프로필 메트릭 네임스페이스에 사용 중인 메모리 바이트라는 사용자 지정 메트릭을 만듭니다. 이 메트릭에는 프로세스라는 단일 차원이 있습니다. 타임스탬프의 경우 두 프로세스에 대해 메트릭 값이 내보내집니다.

로컬 컴퓨터의 custommetric.json 파일에 다음 JSON을 저장합니다. 지난 20분 이내에 시간 매개 변수를 업데이트합니다. 20분 이상 지난 저장소에 메트릭을 입력할 수 없습니다.

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

다음 변수를 사용하여 다음 HTTP POST 요청을 제출합니다.

location: 메트릭을 내보낼 리소스의 배포 지역입니다.
resourceId: 메트릭을 추적 중인 Azure 리소스의 리소스 ID입니다.

accessToken: 권한 부여 토큰 가져오기 단계에서 획득한 권한 부여 토큰입니다.

curl -X POST 'https://<location>/.monitoring.azure.com<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

메트릭 보기

Azure Portal에 로그인합니다.
왼쪽 메뉴에서 모니터를 선택합니다.
모니터 페이지에서 메트릭을 선택합니다.
집계 기간을 지난 1시간으로 변경합니다.
범위 드롭다운 목록에서 메트릭을 보낼 리소스를 선택합니다.
메트릭 네임스페이스 드롭다운 목록에서 메모리 프로필을 선택합니다.
메트릭 드롭다운 목록에서 사용 중인 메모리 바이트를 선택합니다.

문제 해결

프로세스의 일부로 오류 메시지가 수신되면 다음 문제 해결 정보를 고려합니다.

구독, 리소스 그룹 또는 리소스에 대해 메트릭을 발급할 수 없는 경우 애플리케이션 또는 서비스 주체에 액세스 제어(IAM)에 할당된 메트릭 모니터링 게시자 역할이 있는지 확인합니다.
차원 이름의 수가 값의 수와 일치하는지 확인합니다.
올바른 Azure Monitor 지역 엔드포인트에 메트릭을 내보내고 있는지 확인합니다. 예를 들어 리소스가 미국 서부에 배포된 경우 미국 서부 지역 엔드포인트에 메트릭을 내보내야 합니다.
타임스탬프가 지난 20분 이내인지 확인합니다.
타임스탬프가 ISO 8601 형식인지 확인합니다.
메트릭 이름이 유효한지 확인합니다. 예를 들어 공백을 포함할 수 없습니다.

다음 단계

사용자 지정 메트릭에 대해 자세히 알아보세요.

REST API를 사용하여 Azure 리소스에 대한 사용자 지정 메트릭 수집

사용자 지정 메트릭을 수집하기 위해 REST 요청 보내기

인증

권한 부여 토큰 가져오기

Subject

지역

타임스탬프

네임스페이스

이름

차원 키

차원 값

메트릭 값

샘플 사용자 지정 메트릭 게시

메트릭 보기

문제 해결

다음 단계

추가 리소스