생성¶
POST /api/v1/aggs_to_metric/add
개요¶
원본 데이터를 주기적으로 집계하여 새 메트릭을 생성하는 규칙을 생성합니다.
호출 전 및 사용 단계¶
먼저 원본 데이터와 q를 검증한 다음, 중복되지 않는 출력 metric+metricField를 정의하고 jsonScript와 extend를 완전하게 제공합니다. qtype=dql, qmode=selectorQuery 및 fieldKey/funcName을 명시적으로 지정하는 것을 권장합니다. 수동 작성 모드에서는 customQuery를 명시하며 extend는 {}로 지정할 수 있습니다. 새 규칙은 기본적으로 활성화되며, 이후 활성화/비활성화 API로 제어할 수 있습니다.
각 워크스페이스는 삭제되지 않은 모든 aggs 규칙을 기준으로 출력 metric+metricField를 검사하며, 비활성화된 규칙도 포함합니다. 중복이면서 skipRepeatNameCheck=false인 경우 저장/수정이 수행되지 않지만 HTTP 200, success=true가 반환되고, 최상위 code=409, content.metricRepeat=true 및 영문 content.message가 함께 반환됩니다. 따라서 HTTP 상태나 success만 판단하지 말고 반드시 code와 metricRepeat를 확인해야 합니다. skipRepeatNameCheck=true는 해당 검사만 건너뛸 뿐, 동일한 이름의 출력이 서로 영향을 주지 않는다는 것을 보장하지 않습니다.
선택 모드 Distribution은 extend.funcName=distribution이어야 하며, q에는 histogram_auto(실제 숫자 필드)를 사용해야 합니다. 필드 값, 그룹화 및 필터는 실제로 모두 q를 기준으로 하며, extend가 q를 자동으로 재작성하지 않습니다. unit은 표시 단위만 표기하므로, 값 변환은 쿼리 또는 수집 측에서 명시적으로 처리해야 합니다.
저장 시 주기적 스케줄링이 구성되고 메트릭 단위/설명이 동기화되지만, 구성된 집계 q를 동기적으로 실행하거나 새 메트릭 데이터를 생성하지는 않습니다. 다만 생성 시 필드 유형 검증을 위해 원본 필드 Schema를 동기적으로 조회할 수 있습니다. 이후 작업이 언제 실행되는지, 성공 여부 및 메트릭이 기록되는지는 작업/메트릭 조회에서 확인해야 합니다. 스케줄링 서비스와 데이터베이스/메트릭 메타데이터는 단계적으로 처리되므로 오류나 타임아웃 시 이미 일부가 갱신되었을 수 있으므로, 재시도 전에 먼저 규칙과 대상 메트릭을 조회해야 합니다. 현재 이 기능은 무료 플랜 워크스페이스에는 제공되지 않습니다.
요청 헤더¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| DF-API-KEY | string | Y | 워크스페이스의 OpenAPI 인증 자격 증명입니다. 예시: <DF-API-KEY>획득 또는 입력 방법: 대상 워크스페이스의 API Key 관리에서 해당 작업 권한이 있는 OpenAPI Key를 획득합니다. |
Body 요청 파라미터¶
| 파라미터 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| jsonScript.query.q | string | 쿼리 객체 내 필수 문자열입니다. 선택 모드에서도 완전한 q를 제공해야 하며, 자격 증명을 입력해서는 안 됩니다. Distribution 예시는 distribution(필드)가 아니라 histogram_auto(필드)를 사용합니다. 예시: L('default')::`nginx`:(count(`*`)) BY `host`획득 또는 입력 방법: DQL 또는 PromQL 실제 구문에 따라 집계 쿼리를 구성하고, 실제 로그 인덱스, 소스 및 필드를 사용합니다. |
|
| jsonScript.query.qtype | string | 선택적 쿼리 구문이며, 생략하면 기본값 dql로 실행됩니다. 명시적으로는 dql/promql만 사용할 수 있고 빈 문자열이나 null은 전달할 수 없습니다. 항상 명시적으로 입력하는 것을 권장합니다. PromQL은 즉시 쿼리로 실행되며, 이 객체를 통해 rangeQuery를 설정하지 않습니다. 예시: dql획득 또는 입력 방법: DQL은 dql, PromQL은 promql을 입력합니다. |
|
| jsonScript.query.qmode | string | 선택 사항이며 명시적으로 지정하는 것을 권장합니다. selectorQuery는 extend.fieldKey/funcName을 요구하고, customQuery는 해당 에코 필드를 요구하지 않습니다. 생략하면 컨트롤러가 선택 모드 구조 검증을 트리거하지 않지만, 플러그인이 여전히 선택 모드로 함수를 검증할 수 있으므로 생략으로 검증을 우회할 수 없습니다. 예시: selectorQuery획득 또는 입력 방법: 콘솔 선택 모드는 selectorQuery, 수동 작성 쿼리는 customQuery를 사용합니다. |
|
| extend.funcName | string | selectorQuery일 때 조건부 필수인 집계 함수 이름입니다. count는 개수, count_distinct는 중복 제거 수입니다. 숫자 집계 함수는 실제 숫자 필드가 필요하며, distribution은 q의 histogram_auto에 대응하여 에코됩니다. 예시: count획득 또는 입력 방법: count/avg/max/sum/min/count_distinct/distribution/p75/p95/p99 중에서 선택합니다. |
|
| extend.fieldKey | string | selectorQuery일 때 조건부 필수인 에코 집계 필드입니다. 생성 시 원본 필드 유형을 조회하여 숫자 함수 호환성을 검사하지만, 알 수 없는 필드가 반드시 거부되는 것은 아닙니다. 수정 시에는 동일한 필드 유형 검사를 반복 수행하지 않습니다. 예시: *획득 또는 입력 방법: 원본 데이터 필드에서 실제 키를 가져오며, count는 q에 따라 *를 사용할 수 있습니다. |
|
| extend.source | string | 선택적 소스 에코이며, 전체는 *로 표시할 수 있고 실제 범위는 여전히 q로 제한됩니다. RUM 목록을 조회할 때 이 값으로 sourceInfo를 추가할 수 있습니다. 예시: nginx획득 또는 입력 방법: 로그는 source, APM은 service, RUM은 app_id, 메트릭은 메저먼트, 보안은 category, 신서틱 테스트는 실제 신서틱 테스트 데이터 소스를 사용합니다. |
|
| extend.index | string | 선택적 로그 인덱스 에코이며, 이를 변경해도 q의 L 인덱스가 자동으로 변경되지 않습니다. 예시: default획득 또는 입력 방법: 현재 워크스페이스의 로그 인덱스 구성에서 가져오며, 기본 인덱스는 일반적으로 default입니다. |
|
| extend.groupBy | array | 선택적 그룹화 에코 배열이며, 생략하면 해당 에코 필드가 없습니다. 빈 배열은 그룹화하지 않습니다. 실제 그룹화는 q를 기준으로 합니다. 예시: ["host"]획득 또는 입력 방법: q의 BY 그룹화 또는 PromQL 레이블 집계에서 실제 필드를 선택합니다. |
|
| extend.groupBy[*] | string | 단일 그룹화 키입니다. 예시: host획득 또는 입력 방법: 원본 필드 이름 또는 레이블 이름을 가져옵니다. |
|
| extend.filterString | string | 선택적 로그 필터 에코 문자열이며, q에 자동으로 이어 붙이는 진입점이 아닙니다. 실제 필터링은 q에 작성해야 합니다. 예시: env:production획득 또는 입력 방법: 로그 선택 모드에서는 콘솔 필터에서 원본 FilterString을 복사할 수 있습니다. |
|
| extend.filters | array | 선택적 배열이며, 다른 인터페이스의 value와 달리 values(복수)를 사용합니다. 실제 실행 필터링은 q를 기준으로 합니다. 예시: [{"name": "env", "condition": "and", "op": "=", "values": ["production"]}]획득 또는 입력 방법: 로그 이외 선택기에서 사용하는 필터 에코입니다. |
|
| extend.filters[*] | json | 필터 에코 객체이며 클라이언트의 기존 형식을 재귀적으로 유지할 수 있습니다. 현재 에코 구조는 실행 쿼리로 변환되지 않습니다. 예시: {"name": "env", "condition": "and", "op": "=", "values": ["production"]}획득 또는 입력 방법: 각 항목에 선택기 조건 하나를 유지합니다. |
|
| extend.filters[*].name | string | 에코 필드입니다. 예시: env획득 또는 입력 방법: 실제 소스 필드 이름입니다. |
|
| extend.filters[*].condition | string | 이전 에코 조건과의 관계입니다. 예시: and획득 또는 입력 방법: and/or를 사용하며, 생략 시 표시 관례는 and입니다. |
|
| extend.filters[*].op | string | 에코 연산자이며, 이 인터페이스에서 쿼리 조건 변환을 실행하지 않습니다. 예시: =획득 또는 입력 방법: 클라이언트 선택기에 따라 =, !=, match, not match를 사용합니다. |
|
| extend.filters[*].values | array | 에코 값 배열이며, 실제 비교와 값 지정은 모두 q에 반영해야 합니다. 예시: ["production"]획득 또는 입력 방법: 원본 필드 값을 사용하고 문자열/숫자/부울 유형을 유지합니다. |
|
| extend.filters[*].values[*] | JSON | 단일 문자열, 숫자 또는 부울 값입니다. 예시: production획득 또는 입력 방법: 원본 데이터의 단일 필드 값을 가져옵니다. |
|
| extend | json | Y | 필수 에코 객체이며, 수정 시 전체가 교체됩니다. 모든 에코 옵션은 jsonScript.query를 대체하지 않습니다. 수동 작성 모드에서 에코가 필요 없으면 {}를 제공할 수 있습니다. null 허용: False 예시: {"funcName": "count", "fieldKey": "*", "source": "nginx", "index": "default", "groupBy": ["host"], "filters": [], "filterString": ""}획득 또는 입력 방법: 클라이언트 편집기 에코에 사용하며, 이미 q에 작성된 선택 사항과 일치시킵니다. |
| jsonScript | json | Y | 필수 규칙 객체이며, 수정 시 전체가 교체되고 필드 병합은 수행되지 않습니다. 이 페이지에 나열된 하위 필드만 제출하고, 상세 조회에서 반환된 전체 엔터티를 그대로 전달하지 마십시오. null 허용: False 예시: {"type": "logToMetric", "query": {"q": "L('default')::`nginx`:(count(`*`)) BY `host`", "qtype": "dql", "qmode": "selectorQuery"}, "metricInfo": {"every": "5m", "metric": "recording_rules", "metricField": "nginx_requests"}}획득 또는 입력 방법: 원본 데이터 카테고리, 쿼리 문 및 출력 메트릭 정의에 따라 구성하며, 수정 시 먼저 상세 조회에서 전체 객체를 읽습니다. |
| jsonScript.metricInfo | json | Y | 필수 출력 및 스케줄링 객체입니다. 수정 시 전체를 다시 채워야 하며 metric/metricField는 변경할 수 없습니다. 단위와 설명은 변경할 수 있고, 생략하면 빈 문자열로 동기화됩니다. null 허용: False 예시: {"every": "5m", "metric": "recording_rules", "metricField": "nginx_requests", "unit": "custom/[\"custom\",\"次\"]", "desc": "host별 nginx 요청 수를 집계합니다.", "delaySeconds": 60}획득 또는 입력 방법: 비즈니스 담당자가 출력 메트릭을 정의하며, 먼저 기존 메트릭 생성 규칙에서 중복 여부를 확인합니다. |
| jsonScript.metricInfo.delaySeconds | integer | 선택적 대기 시간(초)이며, 기본값 0은 지연 없음입니다. 정기 트리거 후 원본 데이터가 도착할 때까지 기다립니다. every에 해당하는 쿼리 윈도우는 변경하지 않으며, 이 필드를 제공하지 않으면 수정 후 0으로 복원됩니다. 반드시 JSON 정수여야 하고 부울이나 "60" 문자열은 허용되지 않습니다. 선택 가능한 값: [0, 60, 120, 180, 300, 600, 900, 1200, 1800] 예시: 60획득 또는 입력 방법: 0/60/120/180/300/600/900/1200/1800 중에서만 선택합니다. |
|
| jsonScript.metricInfo.desc | string | 선택적 메트릭 설명이며, 생략하거나 빈 문자열이면 빈 값으로 동기화됩니다. 규칙 이름이 아닙니다. 빈 문자열 허용: True 예시: host별 nginx 요청 수를 집계합니다.획득 또는 입력 방법: 출력 메트릭의 의미, 집계 로직 및 단위 설명을 입력합니다. |
|
| jsonScript.metricInfo.every | string | Y | 필수 주기이며 선행 0이 없고 60m, 0m, 초, 일 또는 Cron 표현식은 지원하지 않습니다. 스케줄링 주기 및 쿼리 윈도우 길이로 사용되며 지연 시간이 아닙니다. 빈 문자열 허용: False 예시: 5m획득 또는 입력 방법: 생성 주기에 따라 1m~59m 또는 1h~24h를 선택하고 m/h는 소문자로 입력합니다. |
| jsonScript.metricInfo.metric | string | Y | 필수 메저먼트 이름이며 영문자, 숫자, 밑줄만 사용할 수 있고 하이픈, 공백 또는 중국어는 포함할 수 없습니다. 수정 시 변경할 수 없습니다. 빈 문자열 허용: False 예시: recording_rules획득 또는 입력 방법: 출력 메저먼트 이름을 사용자 지정하며, 기존 메트릭 관리 또는 메트릭 생성 목록에서 이름을 확인합니다. |
| jsonScript.metricInfo.metricField | string | Y | 필수 메트릭 이름이며 명명 문자 제한은 metric과 동일합니다. 수정 시 변경할 수 없으며, 과거 예시의 001-test를 그대로 사용하지 마십시오. 빈 문자열 허용: False 예시: nginx_requests획득 또는 입력 방법: 해당 메저먼트 아래의 출력 메트릭 이름을 정의하며, 규칙 목록에서 동일한 metric+metricField를 확인합니다. |
| jsonScript.metricInfo.unit | string | 선택적 표시 단위 문자열이며, 생략하거나 빈 문자열이면 비웁니다. 단위에 따라 q의 값을 자동 환산하지 않으므로 쿼리 결과가 단위와 일치하는지 직접 보장해야 합니다. 빈 문자열 허용: True 예시: custom/["custom","次"]획득 또는 입력 방법: 단위 설명을 참고하며, 표준 형식은 custom/["time","ms"], 사용자 지정 형식은 custom/["custom","단위"]입니다. |
|
| jsonScript.query | json | Y | 필수 쿼리 객체이며, 실제 실행은 q를 기준으로 하고 extend 필드에서 쿼리를 자동 생성하거나 보정하지 않습니다. 저장 성공이 쿼리 구문, 데이터 가용성 또는 생성 결과가 기대에 부합함을 보장하지 않습니다. null 허용: False 예시: {"q": "L('default')::`nginx`:(count(`*`)) BY `host`", "qtype": "dql", "qmode": "selectorQuery"}획득 또는 입력 방법: 동일한 워크스페이스의 쿼리 도구에서 실제 데이터, 집계 결과 및 그룹화 필드를 먼저 검증합니다. |
| jsonScript.type | string | Y | 필수 데이터 카테고리이며, 공개 선언은 이 여섯 가지만 허용합니다. 내부 객체 플러그인은 현재 OpenAPI에서 공개 지원됨을 의미하지 않습니다. 수정 시 카테고리를 변경할 수 없습니다. 빈 문자열 허용: False null 허용: False 선택 가능한 값: ['logToMetric', 'rumToMetric', 'apmToMetric', 'metricToMetric', 'securityToMetric', 'dialingToMetric'] 예시: logToMetric획득 또는 입력 방법: 로그는 logToMetric, RUM은 rumToMetric, APM은 apmToMetric, 메트릭은 metricToMetric, 보안은 securityToMetric, 신서틱 테스트는 dialingToMetric입니다. |
| skipRepeatNameCheck | boolean | 선택 사항이며 기본값은 false입니다. true이면 동일 워크스페이스의 삭제되지 않은 생성 규칙에 대한 metric+metricField 중복 검사를 건너뛰지만, 출력 데이터가 충돌하지 않는다는 의미는 아니며 명명/구조/스케줄링 검증을 우회하지 않습니다. null 허용: False 예시: false획득 또는 입력 방법: 먼저 메트릭 생성 규칙 목록에서 동일한 출력 메저먼트+메트릭 이름을 확인하며, 일반적으로 false입니다. |
파라미터 추가 설명¶
단위는 단위 설명을 참고합니다. 원본 extend와 실제 query는 일치해야 하며, 생성 주기는 every를 사용하고 Cron 표현식은 제출하지 않습니다.
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/aggs_to_metric/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"jsonScript":{"type":"logToMetric","query":{"q":"L('"'"'default'"'"')::`nginx`:(count(`*`)) BY `host`","qtype":"dql","qmode":"selectorQuery"},"metricInfo":{"every":"5m","metric":"recording_rules","metricField":"nginx_requests","unit":"custom/[\"custom\",\"次\"]","desc":"host별 nginx 요청 수를 집계합니다.","delaySeconds":60}},"extend":{"funcName":"count","fieldKey":"*","source":"nginx","index":"default","groupBy":["host"],"filters":[],"filterString":""},"skipRepeatNameCheck":false}'
응답¶
HTTP 200, application/json 공통 래퍼입니다. 정상 시 code=200으로 규칙을 반환하고, 출력 중복 시 code=409이지만 success=true이므로 content.metricRepeat를 확인해야 합니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content.id | integer 또는 null | 레코드 번호입니다. 생성 스냅샷은 제출 전에 생성되므로 null일 수 있으며, uuid로 작업합니다. |
| content.uuid | string | rul_ 규칙 UUID입니다. |
| content.workspaceUUID | string | 소속 워크스페이스입니다. |
| content.monitorUUID | string | 연결된 모니터 UUID이며, 이 모듈에서는 보통 빈 문자열입니다. |
| content.type | string | 엔터티 유형은 aggs로 고정되며 jsonScript.type과 다릅니다. |
| content.refKey | string | 연결 키이며 보통 비어 있습니다. |
| content.secret | string | 엔터티 호환 필드이며 일반 메트릭 생성 규칙에서는 보통 비어 있습니다. 호출 자격 증명으로 사용하거나 실제 값을 기록하지 마십시오. |
| content.createdWay | string | manual/import/template 또는 과거의 빈 값입니다. |
| content.isLocked | integer 또는 boolean | 잠금 표시이며 보통 0/false입니다. |
| content.openPermissionSet | boolean | 사용자 지정 작업 권한 스위치이며, 이 모듈에서 생성 시 보통 false입니다. |
| content.permissionSet | array<string> |
사용자 지정 작업 주체 배열이며 보통 []입니다. |
| content.permissionSet[] | string | 단일 계정/팀/역할 식별자입니다. |
| content.status | integer | 0 활성화, 2 비활성화, 3 삭제이며, 상태가 최근 작업 실행 성공을 의미하지는 않습니다. |
| content.creator | string | 생성 주체입니다. |
| content.updator | string | 최근 갱신 주체이며 초기에는 비어 있을 수 있습니다. |
| content.createAt | integer | 생성 Unix 초입니다. |
| content.updateAt | integer | 갱신 Unix 초이며, 갱신되지 않은 경우 -1입니다. |
| content.deleteAt | integer | 삭제 Unix 초이며, 삭제되지 않은 경우 -1입니다. |
| content.crontabInfo | object | 스케줄링 구성 요약이며 작업 실행 결과가 아닙니다. |
| content.crontabInfo.id | string | 스케줄링 구성 식별자이며 시스템 유지 관리를 위한 값입니다. 규칙 작업에는 uuid를 사용합니다. |
| content.crontabInfo.crontab | string | 실제 6단계 스케줄링 표현식입니다. 예: 0 */5 * * * *. 요청 주기는 여전히 metricInfo.every를 사용합니다. |
| content.jsonScript | object | 저장된 구성: 필수 규칙 객체이며, 수정 시 전체가 교체되고 필드 병합은 수행되지 않습니다. 이 페이지에 나열된 하위 필드만 제출하고, 상세 조회에서 반환된 전체 엔터티를 그대로 전달하지 마십시오. |
| content.jsonScript.type | string | 저장된 구성: 필수 데이터 카테고리이며, 공개 선언은 이 여섯 가지만 허용합니다. 내부 객체 플러그인은 현재 OpenAPI에서 공개 지원됨을 의미하지 않습니다. 수정 시 카테고리를 변경할 수 없습니다. |
| content.jsonScript.query | json | 저장된 구성: 필수 쿼리 객체이며, 실제 실행은 q를 기준으로 하고 extend 필드에서 쿼리를 자동 생성하거나 보정하지 않습니다. 저장 성공이 쿼리 구문, 데이터 가용성 또는 생성 결과가 기대에 부합함을 보장하지 않습니다. |
| content.jsonScript.query.q | string | 저장된 구성: 쿼리 객체 내 필수 문자열입니다. 선택 모드에서도 완전한 q를 제공해야 하며, 자격 증명을 입력해서는 안 됩니다. Distribution 예시는 distribution(필드)가 아니라 histogram_auto(필드)를 사용합니다. |
| content.jsonScript.query.qtype | string | 저장된 구성: 선택적 쿼리 구문이며, 생략하면 기본값 dql로 실행됩니다. 명시적으로는 dql/promql만 사용할 수 있고 빈 문자열이나 null은 전달할 수 없습니다. 항상 명시적으로 입력하는 것을 권장합니다. PromQL은 즉시 쿼리로 실행되며, 이 객체를 통해 rangeQuery를 설정하지 않습니다. |
| content.jsonScript.query.qmode | string | 저장된 구성: 선택 사항이며 명시적으로 지정하는 것을 권장합니다. selectorQuery는 extend.fieldKey/funcName을 요구하고, customQuery는 해당 에코 필드를 요구하지 않습니다. 생략하면 컨트롤러가 선택 모드 구조 검증을 트리거하지 않지만, 플러그인이 여전히 선택 모드로 함수를 검증할 수 있으므로 생략으로 검증을 우회할 수 없습니다. |
| content.jsonScript.metricInfo | json | 저장된 구성: 필수 출력 및 스케줄링 객체입니다. 수정 시 전체를 다시 채워야 하며 metric/metricField는 변경할 수 없습니다. 단위와 설명은 변경할 수 있고, 생략하면 빈 문자열로 동기화됩니다. |
| content.jsonScript.metricInfo.every | string | 저장된 구성: 필수 주기이며 선행 0이 없고 60m, 0m, 초, 일 또는 Cron 표현식은 지원하지 않습니다. 스케줄링 주기 및 쿼리 윈도우 길이로 사용되며 지연 시간이 아닙니다. |
| content.jsonScript.metricInfo.metric | string | 저장된 구성: 필수 메저먼트 이름이며 영문자, 숫자, 밑줄만 사용할 수 있고 하이픈, 공백 또는 중국어는 포함할 수 없습니다. 수정 시 변경할 수 없습니다. |
| content.jsonScript.metricInfo.metricField | string | 저장된 구성: 필수 메트릭 이름이며 명명 문자 제한은 metric과 동일합니다. 수정 시 변경할 수 없으며, 과거 예시의 001-test를 그대로 사용하지 마십시오. |
| content.jsonScript.metricInfo.unit | string | 저장된 구성: 선택적 표시 단위 문자열이며, 생략하거나 빈 문자열이면 비웁니다. 단위에 따라 q의 값을 자동 환산하지 않으므로 쿼리 결과가 단위와 일치하는지 직접 보장해야 합니다. |
| content.jsonScript.metricInfo.desc | string | 저장된 구성: 선택적 메트릭 설명이며, 생략하거나 빈 문자열이면 빈 값으로 동기화됩니다. 규칙 이름이 아닙니다. |
| content.jsonScript.metricInfo.delaySeconds | integer | 저장된 구성: 선택적 대기 시간(초)이며, 기본값 0은 지연 없음입니다. 정기 트리거 후 원본 데이터가 도착할 때까지 기다립니다. every에 해당하는 쿼리 윈도우는 변경하지 않으며, 이 필드를 제공하지 않으면 수정 후 0으로 복원됩니다. 반드시 JSON 정수여야 하고 부울이나 "60" 문자열은 허용되지 않습니다. |
| content.extend | object | 저장된 구성: 필수 에코 객체이며, 수정 시 전체가 교체됩니다. 모든 에코 옵션은 jsonScript.query를 대체하지 않습니다. 수동 작성 모드에서 에코가 필요 없으면 {}를 제공할 수 있습니다. |
| content.extend.funcName | string | 저장된 구성: selectorQuery일 때 조건부 필수인 집계 함수 이름입니다. count는 개수, count_distinct는 중복 제거 수입니다. 숫자 집계 함수는 실제 숫자 필드가 필요하며, distribution은 q의 histogram_auto에 대응하여 에코됩니다. |
| content.extend.fieldKey | string | 저장된 구성: selectorQuery일 때 조건부 필수인 에코 집계 필드입니다. 생성 시 원본 필드 유형을 조회하여 숫자 함수 호환성을 검사하지만, 알 수 없는 필드가 반드시 거부되는 것은 아닙니다. 수정 시에는 동일한 필드 유형 검사를 반복 수행하지 않습니다. |
| content.extend.source | string | 저장된 구성: 선택적 소스 에코이며, 전체는 *로 표시할 수 있고 실제 범위는 여전히 q로 제한됩니다. RUM 목록을 조회할 때 이 값으로 sourceInfo를 추가할 수 있습니다. |
| content.extend.index | string | 저장된 구성: 선택적 로그 인덱스 에코이며, 이를 변경해도 q의 L 인덱스가 자동으로 변경되지 않습니다. |
| content.extend.groupBy | array | 저장된 구성: 선택적 그룹화 에코 배열이며, 생략하면 해당 에코 필드가 없습니다. 빈 배열은 그룹화하지 않습니다. 실제 그룹화는 q를 기준으로 합니다. |
| content.extend.groupBy[] | string | 저장된 구성: 단일 그룹화 키입니다. |
| content.extend.filterString | string | 저장된 구성: 선택적 로그 필터 에코 문자열이며, q에 자동으로 이어 붙이는 진입점이 아닙니다. 실제 필터링은 q에 작성해야 합니다. |
| content.extend.filters | array | 저장된 구성: 선택적 배열이며, 다른 인터페이스의 value와 달리 values(복수)를 사용합니다. 실제 실행 필터링은 q를 기준으로 합니다. |
| content.extend.filters[] | json | 저장된 구성: 필터 에코 객체이며 클라이언트의 기존 형식을 재귀적으로 유지할 수 있습니다. 현재 에코 구조는 실행 쿼리로 변환되지 않습니다. |
| content.extend.filters[].name | string | 저장된 구성: 에코 필드입니다. |
| content.extend.filters[].condition | string | 저장된 구성: 이전 에코 조건과의 관계입니다. |
| content.extend.filters[].op | string | 저장된 구성: 에코 연산자이며, 이 인터페이스에서 쿼리 조건 변환을 실행하지 않습니다. |
| content.extend.filters[].values | array | 저장된 구성: 에코 값 배열이며, 실제 비교와 값 지정은 모두 q에 반영해야 합니다. |
| content.extend.filters[].values[] | JSON | 저장된 구성: 단일 문자열, 숫자 또는 부울 값입니다. |
| content.__operation_info | object | 정상 생성 응답에 추가되는 작업 요약이며, 요청 파라미터가 아니고 중복 분기에서는 반환되지 않습니다. |
| content.__operation_info.uuid | string | 이번에 생성된 규칙 UUID이며 content.uuid와 동일합니다. |
| content.declaration | object | 워크스페이스 공통 선언입니다. |
| content.metricRepeat | boolean | 중복 분기에서만 true로 나타나며 정상 규칙 엔터티를 대체합니다. |
| content.message | string | 중복 분기에서만 나타나는 안내이며, 영문 값은 예시를 참고하십시오. |
| code | integer | 성공 시 200, 중복 분기에서는 409이지만 HTTP는 여전히 200이고 success도 true입니다. |
| content.retryable | boolean | 503 QueryServiceUnavailable 오류의 content에서만 true가 나타날 수 있으며, 성공 엔터티에는 없습니다. |
{
"code": 200,
"content": {
"id": null,
"uuid": "rul_aggs_example",
"workspaceUUID": "wksp_example",
"monitorUUID": "",
"type": "aggs",
"refKey": "",
"secret": "",
"jsonScript": {
"type": "logToMetric",
"query": {
"q": "L('default')::`nginx`:(count(`*`)) BY `host`",
"qtype": "dql",
"qmode": "selectorQuery"
},
"metricInfo": {
"every": "5m",
"metric": "recording_rules",
"metricField": "nginx_requests",
"unit": "custom/[\"custom\",\"次\"]",
"desc": "host별 nginx 요청 수를 집계합니다.",
"delaySeconds": 60
}
},
"extend": {
"funcName": "count",
"fieldKey": "*",
"source": "nginx",
"index": "default",
"groupBy": [
"host"
],
"filters": [],
"filterString": ""
},
"crontabInfo": {
"id": "cron_example",
"crontab": "0 */5 * * * *"
},
"createdWay": "manual",
"isLocked": 0,
"openPermissionSet": false,
"permissionSet": [],
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"declaration": {},
"__operation_info": {
"uuid": "rul_aggs_example"
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
출력 이름 중복, HTTP 200:
{
"code": 409,
"content": {
"message": "Data duplication cannot be added",
"metricRepeat": true,
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참고하십시오.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반함 | 파라미터 파싱 실패 | 파라미터 위치, 필드 이름, 유형 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | 예시에 따라 JSON 객체를 제출합니다. |
| 403 | ft.InvalidMetricsName | 메저먼트 또는 메트릭 이름이 영문자/숫자/밑줄 형식에 맞지 않음 | 메트릭 이름은 영문자, 숫자, 밑줄만 포함할 수 있습니다 | metric/metricField를 수정하며, 과거 예시의 하이픈을 사용하지 마십시오. |
| 400 | ft.ParamsValidateError | query/metricInfo 구조, 알 수 없는 jsonScript 필드, 주기 또는 지연 값이 비즈니스 검증에 맞지 않거나 선택 모드에서 fieldKey/funcName이 누락됨 | 파라미터 검증 실패: {} | 메시지의 필드 경로를 확인하고, 주기와 지연은 이 페이지의 선택 값만 사용하며 qmode와 qtype을 명시적으로 제공합니다. |
| 400 | ft.OuterFuncFailed | 스케줄링 서비스가 명확한 실패를 반환함 | 외부 함수 호출 실패 | 기존 규칙과 스케줄링을 확인한 후 재시도하고, 지속 실패 시 traceId를 제공합니다. |
| 400 | ft.SameSetTraggerExists | 스케줄링 서비스가 동일한 구성을 발견함 | 동일한 구성의 트리거가 이미 존재합니다 | 기존 규칙과 작업을 먼저 조회하여 중복 스케줄링을 방지합니다. |
| 500 | ft.InternalServerError | 하위 서비스 타임아웃/일반 5xx, 데이터베이스 또는 후속 메타데이터 처리 실패 | 내부 오류 | 먼저 규칙과 그 상태, 출력 메트릭 및 스케줄링 현황을 조회한 후 재시도를 결정하고 traceId를 제공합니다. |
| 406 | ft.UnsupportAggregateFunction | 생성 시 플러그인이 선택 모드로 funcName이 지원 집합에 없다고 판단함( qmode 생략 및 extend 불완전 포함) | 지원하지 않는 집계 함수 | qmode를 명시적으로 입력하고 선택 모드에서 유효한 funcName을 제공합니다. |
| 406 | ft.FieldTypeUnsupportFunc | 생성 시 선택 모드의 숫자 집계 필드가 숫자 유형이 아닌 것으로 확인됨 | 이 field {} 유형 {}은(는) 이 계산 함수 {}를 지원하지 않습니다 | 숫자 필드 또는 호환되는 집계 함수를 선택하며, 수정 시 동일 검사를 반복하지 않습니다. |
| 400 | ft.FiledCreateTrigger | 생성 스케줄링이 유효한 id를 반환하지 않음 | 트리거 구성 생성 실패, 다시 시도하십시오 | 먼저 기존 규칙/스케줄링이 있는지 확인하고, 지속 실패 시 traceId를 제공합니다. |
| 503 | ft.QueryServiceUnavailable | 생성 시 원본 필드 유형 조회 중 쿼리 서비스 503이 재시도 가능한 503으로 정규화되고 content.retryable=true | 쿼리 서비스를 일시적으로 사용할 수 없습니다. 잠시 후 다시 시도하십시오 | 백오프 후 재시도하고, 지속 실패 시 traceId를 제공합니다. |
| 429 | ft.KodoServerOverloaded | 생성 필드 조회 과부하 | 현재 요청이 너무 많습니다. 잠시 후 다시 시도하십시오. | 백오프 재시도하고 동시성을 낮춥니다. |
| 403 | ft.Forbidden | API Key 권한 부족 또는 워크스페이스 플랜이 이 기능을 지원하지 않음 | 작업 권한이 없습니다 | 해당 권한을 가진 API Key와 메트릭 생성을 지원하는 워크스페이스를 사용합니다. |