Skip to content

CM‐ANT Simple & Sample API Usage guide

Jump to bottom
MZC-CSC edited this page Nov 21, 2024 · 7 revisions

Simple & Sample API Usage Guide

비용 추정 api 호출 흐름

  1. 추천 모델 조회
  2. 비용 추정 데이터 업데이트 혹은 조회
  3. 마이그레이션 프로세스
  4. 추정 사용 비용 데이터 업데이트
  5. 추정 사용 비용 데이터 조회

비용 추정 api 명세

1. 비용 추정 데이터 업데이트 혹은 조회 API

엔드포인트

POST /api/v1/cost/estimate

설명

providerName, regionName, instanceType, image(optional) 정보에 대한 비용 추정 데이터를 제공합니다. 만일 Ant 의 데이터베이스에 존재하지 않는 스펙이거나 존재하지만 7 일 이내의 데이터가 아닌 경우 서브 시스템 호출을 통해 비용 정보를 가져와 저장 후 응답을 제공합니다.

요청 본문

{
  "specsWithFormat": [
    {
      "commonImage": "aws+ap-northeast-2+ubuntu22.04",
      "commonSpec": "aws+ap-northeast-2+c4.2xlarge"
    },
    {
      "commonImage": "aws+ap-northeast-2+ubuntu22.04",
      "commonSpec": "aws+ap-northeast-2+t3.large"
    }
  ],
  "specs": [
    {
      "providerName":"aws",
      "regionName": "eu-south-1",
      "instanceType":"t3a.medium",
      "image": "ubuntu22.04"
    }
  ]
}
  • specsWithFormat 과 specs 는 둘중 하나만 넘어와도 괜찮습니다.
  • 모든 요청의 스펙은 취합되어 결과를 제공합니다. 위의 예시 요청의 경우 총 3개의 응답 결과를 반환합니다.
  • os, lisence 에 따라 제공되는 가격이 다를 수 있습니다.

specsWithFormat

  • commonSpec (required): + 구분자로 연결된 providerName+region+instanceType 정보입니다.

  • commonImage (Optional): + 구분자로 연결된 providerName+region+machineImage 정보입니다.

specs

  • providerName (required): 요청 프로바이더명 (aws | azure | alibaba | tencent | gcp | ibm)

  • regionName (required): CSP 와 매칭되는 region 명

  • instanceType (required): CSP 와 매칭되는 instance type

  • image(optional): CSP 에 사용되는 os 이미지 정보입니다.

2. 추정 사용 비용 데이터 업데이트 API

엔드포인트

POST /api/v1/cost/estimate/forecast

설명

마이그레이션 된 워크로드에 대한 운영 비용 데이터를 ant 로 불러와 저장합니다. 저장 가능한 기간은 현재 부터 최대 14일간의 비용데이터만 저장 가능하며, 호출 1건당 Cost Explorer Api 사용 비용 0.01$ 가 연결된 aws 계정에 청구됩니다.

Tumblebug 에서 사용하는 nsId 와 mcsId 에 해당하는 리소스 (현재는 instance id 만 취득 가능) 의 정보를 가지고 와 해당하는 가격 정보를 업데이트합니다.

현재 제공되는 provider 는 aws 이며 추후 확장 예정입니다.

요청 파라미터

{
    "nsId": "ns01",
    "mciId": "mci01"
}

3. 추정 사용 비용 데이터 조회 API

엔드포인트

GET /api/v1/cost/estimate/forecast

설명

사용자의 필터 조건에 맞는 추정 사용 비용 데이터를 ant 의 데이터베이스에서 조회합니다. 추정 사용 비용 데이터 업데이트를 진행한 후 조회를 진행해야 합니다. ant 의 데이터베이스에서 조회하기 때문에 별도의 api 호출 비용이 발생하지 않습니다.

Query Param: startDate(format 2024-09-10), endDate(format 2024-09-15), costAggregationType, providerName, nsIds, mciIds, resourceTypes, resourceIds, dateOrder, resourceTypeOrder

요청 파라미터

  • startDate: 2024-10-08 형식의 시작 날짜(포함)
  • endDate: 2024-10-08 형식의 종료 날짜(포함)
  • costAggregationType: 비용 데이터 조회 묶음 간격 (*daily|weekly|monthly)
  • providerName: provider 로 필터링 하기 위한 값 (현재는 aws 만 제공)
  • nsIds: 조회 원하는 nsId 목록
  • mciIds: 조회 원하는 mciId 목록
  • resourceType: 조회를 원하는 리소스 타입 (VM|VNet|DataDisk|Etc|)
  • resourceIds: 조회 원하는 리소스 id 목록
  • dateOrder: 날짜 기준 오름차순 내림차순 (asc|desc)
  • resourceTypeOrder: resourceType 오름차순 내림차순 (asc|desc)

응답 결과

{
        "code": 200,
        "result": {
            "getEstimateForecastCostInfoResults": [
                {
                    "category": "Amazon Elastic Compute Cloud - Compute",
                    "date": "2024-11-08T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-0e6a610a7111e574e",
                    "resourceType": "VM",
                    "totalCost": 0.6912,
                    "unit": "USD"
                },
                {
                    "category": "EC2 - Other",
                    "date": "2024-11-08T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-0e6a610a7111e574e",
                    "resourceType": "VM",
                    "totalCost": 0.0002170775,
                    "unit": "USD"
                },
                {
                    "category": "Amazon Elastic Compute Cloud - Compute",
                    "date": "2024-11-09T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-0e6a610a7111e574e",
                    "resourceType": "VM",
                    "totalCost": 0.6912,
                    "unit": "USD"
                },
                {
                    "category": "EC2 - Other",
                    "date": "2024-11-09T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-0e6a610a7111e574e",
                    "resourceType": "VM",
                    "totalCost": 0.0000351517,
                    "unit": "USD"
                },
                {
                    "category": "Amazon Elastic Compute Cloud - Compute",
                    "date": "2024-11-10T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-0e6a610a7111e574e",
                    "resourceType": "VM",
                    "totalCost": 0.6912,
                    "unit": "USD"
                },
                {
                    "category": "EC2 - Other",
                    "date": "2024-11-10T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-0e6a610a7111e574e",
                    "resourceType": "VM",
                    "totalCost": 0.0000353784,
                    "unit": "USD"
                },
                {
                    "category": "Amazon Elastic Compute Cloud - Compute",
                    "date": "2024-11-11T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-0e6a610a7111e574e",
                    "resourceType": "VM",
                    "totalCost": 0.6912,
                    "unit": "USD"
                },
                {
                    "category": "EC2 - Other",
                    "date": "2024-11-11T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-xxxxxxx",
                    "resourceType": "VM",
                    "totalCost": 0.0000362429,
                    "unit": "USD"
                },
                {
                    "category": "Amazon Elastic Compute Cloud - Compute",
                    "date": "2024-11-12T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-xxxxxxx",
                    "resourceType": "VM",
                    "totalCost": 0.6912,
                    "unit": "USD"
                },
                {
                    "category": "EC2 - Other",
                    "date": "2024-11-12T00:00:00Z",
                    "provider": "aws",
                    "resourceId": "i-xxxxxxx",
                    "resourceType": "VM",
                    "totalCost": 0.0000465391,
                    "unit": "USD"
                }
            ],
            "resultCount": 27
        },
        "successMessage": "Successfully get estimate forecast cost"
    }

5. 사용 비용 추정 RAW 데이터 업데이트 API

설명

마이그레이션 된 워크로드에 대한 운영 비용 데이터를 ant 로 불러와 저장합니다. 저장 가능한 기간은 현재 부터 최대 14일간의 비용데이터만 저장 가능하며, 호출 1건당 Cost Explorer Api 사용 비용 0.01$ 가 연결된 aws 계정에 청구됩니다.

이는 ns와 mci 와 상관없이 원하는 리소스의 id 를 통해서 비용 데이터를 ant 로 저장할 수 있습니다.

{
  "migrationId": "1",  ## 현재 사용되지 않으나 추후 마이그레이션 id 를 통해 관련 리소스에 대한 정보를 조회할 수 있을 것으로 생각하고 넣어둔 값
  "connectionName": "aws-us-east-1",
  "costResources": [
    {
      "resourceType": "VM",
      "resourceIds": [
        "i-02dxxxxxxdec4"
      ]
    },
    {
      "resourceType": "VNet",
      "resourceIds": [
          "eni-06cxxxxxx02e34"
      ]
    },
    {
      "resourceType": "DataDisk",
      "resourceIds": [
          "vol-0917xxxxxxe2f6"
      ]
    }
  ],
  "awsAdditionalInfo": {  # eni 추가 시 자원 별 사용 가격 데이터 조회를 위한 id 조합을 위해 필요한 데이터
    "ownerId": "xxxxxxxxxxxx",  # 12 자리 숫자
    "regions": [
      "ap-northeast-2"
    ]
  }
}

요청 파라미터

  • migrationId (현재 사용하지 않습니다.): 현재 사용되지 않으나 추후 마이그레이션 id 를 통해 관련 리소스에 대한 정보를 조회할 수 있을 것으로 생각하고 넣어둔 값
  • connectionId : 조회를 위해 사용되는 등록된 aws connection 이름 (변경 예정)
  • costResources: 비용 정보를 조회하기 위해 필요한 내용
    • resourceType: 어떤 리소스의 비용 정보를 조회할 것인지 정의 (VM|VNet|DataDisk)
    • resourceIds: 해당 타입에 해당하는 리소스 id 리스트
  • awsAdditionalInfo: aws 비용 조회에 추가적으로 필요한 데이터
    • ownerId: 12자리 숫자로 구성된 aws 값
    • regions: eni 조합시 필요한 region 이름 (VNet 비용 조회 용도)

성능 평가 api 호출 흐름

  1. migration 된 워크로드 선택
    • nsId, mciId, vmId
  2. metrics agent 설치 요청
  3. 성능 평가를 위한 시나리오 사용자 입력 후 성능 평가 수행
  4. 워크로드를 대상으로 수행한 성능 평가 상태 조회
    • 워크로드에 상태 표시가 가능하도록
  5. 워크로드를 대상으로 수행한 성능 평가 결과 조회

참고 사항

현재 마이그레이션 된 워크로드와 성능 평가 실행 사이에 연결 관계가 프레임워크에 정의되어 있지 않습니다.
성능 평가 흐름상 워크로드와 성능 평가는 링크가 필요해 보이며 지난번 말씀주셨던 것 처럼 연결 고리를 추가 예정입니다.

성능 평가 api 명세

1. 성능평가 지표 수집 에이전트 설치 (optional)

엔드포인트

POST /api/v1/load/monitoring/agent/install

설명

성능 평가시 추가적으로 지표 정보를 수집하기 위해 사용할 메트릭 에이전트를 설치하는 단계입니다. 메트릭 에이전트를 통해 부하 발생 시 인프라의 CPU, 메모리, 네트워크 I/O, 디스크 I/O 등의 지표 정보를 수집합니다.

별도로 설치하지 않고 성능 평가를 진행하는 경우 latency 와 request per second 등 http 요청에 대한 지표만 수집합니다.

성능 평가를 수행하면 agent 로 metrics 를 수집하는 옵션을 선택할 수 있습니다.

{
  "nsId": "nsId",
  "mcisId": "mcisId",
  "vmId": "vmId"  # optional 
}

요청 프로퍼티

  • nsId: 네임스페이스 ID
  • mciId: MCI ID
  • vmId: VM ID

2. 성능 평가용 Load Generator 설치 (optional)

엔드포인트

POST /api/v1/load/generators

설명

성능 평가 실행을 위해 부하를 발생하기 위한 Load Generator를 설치하는 단계입니다. Local 또는 Remote 환경에 설치할 수 있습니다.

별도로 설치하지 않고 성능 평가를 실행하는 경우 부하 발생 실행 요청의 프로퍼티인 installLocation 을 확인하여 부하 발생기 설치를 진행합니다.

{
  "installLocation": "local"  // local | remote
}

프로퍼티

  • installLocation: 설치 위치 (local 또는 remote)

    • local: 현재 ANT가 작동하는 환경(Ubuntu 기반)에 설치

    • remote: Tumblebug의 recommendVM을 통해 VM을 프로비저닝한 후 프로비저닝 된 VM 에 설치

      t2.medium 2 4.0

3. 성능 평가를 위한 부하 발생 시작

엔드포인트

POST /api/v1/load/tests/run

설명

성능 평가를 위한 부하 테스트를 실행하는 단계입니다.

앞선 단계인 성능평가 지표 수집 에이전트 설치 및 성능 평가 부하 발생기 설치하는 과정을 포함하고 있는 API 입니다.

{
        "agentHostname": "",
        "collectAdditionalSystemMetrics": true,
        "httpReqs": [
            {
                "bodyData": "",
                "hostname": "xx.xxx.xx.xxx",
                "method": "get",
                "path": "",
                "port": "80",
                "protocol": "http"
            }
        ],
        "installLoadGenerator": {
            "installLocation": "remote"
        },
        "nsId": "mig01",
        "mciId": "mmci01",
        "vmId": "vm01-1",
        "testName": "first test gogo",
        "virtualUsers": "10",
        "duration": "20",
        "rampUpTime": "20",
        "rampUpSteps": "3"
    }

프로퍼티

  • installLoadGenerator: Load Generator 설치 위치 (앞서 설치한 경우 설치 스킵)
    • installLocation: 설치 위치 (remote 또는 local)
  • testName: 테스트 이름
  • virtualUsers: 가상 사용자 수
  • duration: 테스트 실행 시간 (초 단위)
  • rampUpTime: 부하 증가 시간 (초 단위)
  • rampUpSteps: 부하 증가 단계 수
  • hostname: 테스트 대상 호스트명
  • port: 포트 번호
  • agentHostname: 에이전트가 설치된 호스트명 (Optional)
  • collectAdditionalSystemMetrics: 에이전트를 통해 메트릭 수집 여부 확인
  • httpReqs: HTTP 요청 리스트
    • method: HTTP 메소드 (GET, POST)
    • protocol: 통신 프로토콜 (http, https)
    • hostname: 요청할 호스트명
    • port: 포트 번호
    • path: 요청 경로
    • bodyData: 요청 본문 데이터 (Optional)

4. 부하 발생 상태 확인

엔드포인트

GET /api/v1/load/tests/state/{loadTestKey}

설명

부하 발생 상태를 확인합니다. 부하 발생이 진행되고 있는 상태와 정보를 반환합니다.

Path Param
loadTestKey: 성능 평가 실행 시 반환된 테스트 키

응답 예시

{
        "code": 200,
        "result": {
            "compileDuration": "436.008µs",
            "createdAt": "2024-11-05T06:22:08.832848Z",
            "executionDuration": "1m4.032562237s",
            "executionStatus": "successed",
            "id": 1,
            "loadGeneratorInstallInfo": {
                "createdAt": "2024-11-05T06:19:27.85666Z",
                "id": 1,
                "installLocation": "local",
                "installPath": "/opt/ant/jmeter",
                "installType": "jmeter",
                "installVersion": "5.6",
                "status": "installed",
                "updatedAt": "2024-11-05T06:22:08.824086Z"
            },
            "loadTestKey": "1730787567844-e1b27efd-0773-4480-9094-d304f84016a5",
            "startAt": "2024-11-05T06:22:08.828219Z",
            "totalExpectedExecutionSecond": 60,
            "updatedAt": "2024-11-05T06:23:12.869756Z"
        },
        "successMessage": "Successfully retrieved load test execution state information"
    }

5. 성능 평가 결과 확인

엔드포인트

GET /api/v1/load/tests/result

GET /api/v1/load/tests/result/metrics

설명

부하 발생이 완료된 후, 성능 평가 결과를 조회하는 단계입니다.

Query Param

loadTestKey: 성능 평가 실행 시 반환된 테스트 키
format: 결과 형식 (normal | aggregate)

만약 모니터링 에이전트가 설치된 경우, 메트릭 에이전트를 통해 수집된 cpu, memory, disk, network 등 데이터를 metrics 결과 조회 API 호출을 통해 확인해볼 수 있습니다.

Query Param:
loadTestKey: 성능 평가 실행 시 반환된 테스트 키

성능 평가 결과 조회 응답

aggregate 의 경우 결과에 대한 집계된 값입니다. 데이터 샘플링 없이 모든 데이터에 대한 집계된 값을 제공합니다.

normal 은 시계열 데이터로 표현되는 응답값입니다. 결과데이터는 100ms 단위로 평균값을 계산하여 가장 근접한 값을 찾아내 샘플링한 결과값을 추출하여 제공합니다.

 "[aggregate]": {
    "code": 0,
    "errorMessage": "string",
    "result": [
      {
        "average": 0,  # 평균 latency (ms)
        "errorPercent": 0,  # error 비율
        "label": "string", # 테스트 이름
        "maxTime": 0,  # 최대 latency  (ms)
        "median": 0,  # 중간 값 latency (ms)
        "minTime": 0,   # 최소 latency (ms)
        "ninetyFive": 0,  # latency 95% 값 (ms)
        "ninetyNine": 0,  # latency 99% 값 (ms)
        "ninetyPercent": 0,  # latencyt 90% 값 (ms)
        "receivedKB": 0,  # 받은 KB / sec
        "requestCount": 0,  # 발생한 총 요청 count
        "sentKB": 0,  # 보낸 KB / sec
        "throughput": 0  # 요청에 대한 처리량 / sec
      }
    ],
    "successMessage": "string"
  },
  "[normal]": {
    "code": 0,
    "errorMessage": "string",
    "result": [
      {
        "label": "string",
        "results": [  # 단일 요청에 대한 단일 결과 값들의 목록
          {
            "bytes": 0,
            "connection": 0,
            "elapsed": 0,  # 개별 요청 총 소요 시간 (ms)
            "idleTime": 0,
            "isError": true,  # 에러 여부
            "latency": 0,  # 개별 요청 지연 시간 (ms)
            "no": 0,
            "sentBytes": 0,
            "timestamp": "string",  # 개별 요청 발생 시간
            "url": "string"
          }
        ]
      }
    ],
    "successMessage": "string"
  }
}

성능 평가 지표 조회 응답

{
  "code": 0,
  "errorMessage": "string",
  "result": [
    {
      "label": "string",  # 아래 수집 지표에 대한 목록에서 확인 가능
      "metrics": [  
        {
          "isError": true,  # 해당 요청에 대한 에러 여부
          "timestamp": "string",  # 개별 요청 발생 시간
          "unit": "string",  # 아래 수집 지표에 대한 목록에서 확인 가능
          "value": "string"  # 수집 지표에 대한 값
        }
      ]
    }
  ],
  "successMessage": "string"
}
성능 평가 수집 지표에 대한 목록
"cpu_all_combined": {  # 전체 cpu 사용률
        Unit:     "%",
    },
    "cpu_all_idle": {  # 유휴 cpu 비율
        Unit:     "%",
    },
    "memory_all_used": {  # 메모리 사용률
        Unit:     "%",
    },
    "memory_all_free": {  # 유휴 메모리 비율
        Unit:     "%",
    },
    "memory_all_used_kb": {  # 메모리 사용 kb
        Unit:     "mb",
    },
    "memory_all_free_kb": {  # 유휴 메모리 kb
        Unit:     "mb",
    },
    "disk_read_kb": {  # 디스크 읽기 kb
        Unit:     "kb",
    },
    "disk_write_kb": {   # 디스크 쓰기 kb
        Unit:     "kb",
    },
    "disk_use": {  # 디스크 사용율
        Unit:     "%",
    },
    "disk_total": {  # 총 디스크 용량 mb
        Unit:     "mb",
    },
    "network_recv_kb": {  # 네트워크 수신 kb
        Unit:     "kb",
    },
    "network_sent_kb": {  # 네트워크 발신 kb
        Unit:     "kb",
    },
Clone this wiki locally