DQL 데이터 조회(레거시)¶
POST /api/v1/df/query_data
개요¶
DQL 데이터 조회
Query 요청 파라미터¶
| 파라미터 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
| body | string | dql 조회 query 구조체 빈 값 허용: False |
|
| queries_body | string | dql 조회 query 구조체(2023-08-11에 제거된 파라미터) 빈 값 허용: False |
|
| search_after | string | 페이지네이션 조회 요청 파라미터(2023-08-11에 제거된 파라미터) 빈 값 허용: False |
파라미터 추가 설명¶
조회 설명
본 엔드포인트는 레거시 호환 진입점입니다. 신규 연동은 POST /api/v1/df/query_data_v1 사용을 권장합니다. 레거시 GET은
계속 body=<URL 인코딩된 JSON> 방식으로 파라미터를 전달하며, JSON을 이중으로 인코딩하지 마십시오.
본 엔드포인트는 POST와 GET을 모두 지원하며, 두 방식 모두 동일한 JSON object 파라미터 구조를 사용합니다.
- POST: 전체 파라미터를
application/jsonrequest body로 전달합니다. - GET: HTTP entity body를 사용하지 않으며 query string에서
body=<전체 JSON object 문자열>로 전달합니다. 클라이언트는body파라미터를 URL 인코딩해야 합니다. - 최상위는 반드시 JSON object여야 하며, 이중 JSON 인코딩된 string, array, null, number 또는 boolean은 허용되지 않습니다.
워크스페이스 간/사이트 간 조회 시 한 요청의 모든 queries[*]는 동일한
targetRegion만 가리킬 수 있습니다. 여러 사이트를 조회해야 하는 경우 사이트별로 요청을 분리하고 클라이언트에서 결과를 병합해야 합니다.
대상 워크스페이스와 targetRegion은 /api/v1/wksp_share/granted_ws_list를 통해 가져와야 하며,
자세한 내용은 OpenAPI 사이트 간 데이터 조회를 참조하세요.
응답의 content.data[i].warnings[]에는 DQLDataAccessScopeRestricted가 포함될 수 있습니다.
details[0].metadata.namespace는 현재 릴리스에서logging으로 고정됩니다.details[0].metadata.restriction=partial은 권한이 있는 로그 인덱스의 데이터만 반환함을 의미합니다.details[0].metadata.restriction=all은 관련 로그 인덱스에 모두 데이터 액세스 권한이 없으며 빈 결과를 반환함을 의미합니다.-
HTTP 상태 코드는 여전히 200이며, warning은 GuanceDB/Kodo의 기존 warning과 함께 존재합니다.
-
조회 문자열 요소 필드 설명
| 파라미터 이름 | type | 필수 | 설명 |
|---|---|---|---|
| body | string | queries_body와 둘 중 하나 | 조회 요청 본문 |
| queries_body[*] | string | body와 둘 중 하나 | (레거시 파라미터, 2023-08-10에 제거됨) 조회 목록 |
| search_after | string | (레거시 파라미터, 2023-08-10에 제거됨. 신규 버전에서는 파라미터 위치가 query 구조체로 이동됨) 조회 페이지네이션 데이터. 첫 조회 시 기본값은 []이며, 추가 페이지네이션 데이터가 필요하면 이전 조회 결과의 search_after 필드를 포함하여 후속 데이터를 조회합니다. |
body와 호환 파라미터 queries_body는 모두 조건부 필수 파라미터입니다. 비어 있지 않고 유효한 JSON 값을 하나 이상 제공하십시오. 동시에 제공하는 경우 비어 있지 않은 queries_body가 우선 사용됩니다.
- body의 JSON 구조 파라미터 설명
| 파라미터 이름 | type | 필수 | 설명 |
|---|---|---|---|
| queries | array | Y | 다중 커맨드 조회이며, 내용은 query 객체로 구성된 목록입니다. |
| fieldTagDescNeeded | boolean | field 또는 tag 설명 정보가 필요한지 여부 |
- queries[*] 멤버 파라미터 구조 설명
| 파라미터 이름 | type | 필수 | 설명 |
|---|---|---|---|
| qtype | string | Y | 조회문 유형 dql: DQL 조회문, promql: PromQL 조회문 |
| query | json | Y | 조회 구조 |
| query.q | string | qtype 유형과 일치하는 조회문(예: dql 또는 promql 조회문) | |
| query.ignore_cache | boolean | 캐시 비활성화 여부. 기본값은 false이며 캐시를 사용함을 의미합니다. |
|
| query.promqlType | enum | qtype=promql일 때 적용됩니다. 선택 값은 instantQuery, rangeQuery이며 기본값은 rangeQuery입니다. |
|
| query.highlight | boolean | 하이라이트 데이터 표시 여부 | |
| query.timeRange | array | 시간 범위의 타임스탬프 목록. DQL/PromQL의 시작 및 종료 시간은 동일한 단위(초, 밀리초, 마이크로초 또는 나노초)를 사용해야 하며, 단위를 혼용하면 HTTP 400 ft.TimeRangeUnitMismatch가 반환됩니다. 페이지네이션 커서는 별개로 유지됩니다. |
|
| query.disableMultipleField | bool | 단일 열 모드 활성화 여부. 기본값은 true입니다. |
|
| query.showLabel | bool | 객체의 labels 표시 여부. 기본값은 false입니다. |
|
| query.funcList | array | DQL 반환 값을 다시 집계하여 가공합니다. disableMultipleField=false일 때 이 파라미터는 무효입니다. |
|
| query.slimit | integer | 시계열 그룹 크기. 메트릭 조회에만 유효합니다. | |
| query.soffset | integer | 시계열 그룹 오프셋 | |
| query.limit | integer | 페이지 크기 | |
| query.offset | integer | 페이지 오프셋 | |
| query.orderby | array | 정렬 목록. 구조는 {fieldName: method}입니다. 메저먼트 조회는 fieldName=time만 지원하며 method는 desc, asc를 선택할 수 있습니다. |
|
| query.density | string | 응답의 포인트 밀도. 우선순위는 autoDensity보다 낮고 dql 문에서 설정한 밀도보다 높습니다. | |
| query.interval | number | 시간 분할 간격. Kodo int64 범위로 변환 가능하고 1ms 이상인 정수 밀리초의 양수만 허용됩니다. 기본 단위는 초이며 interval_unit으로 밀리초를 지정할 수 있습니다. | |
| query.interval_unit | string | interval의 단위. s, ms를 선택할 수 있으며 기본값은 s입니다. |
|
| query.search_after | array | 페이지네이션 마커. 현재 엔드포인트에서 반환된 페이지네이션 마커로, 다음 요청 시 전달하는 데 사용합니다. | |
| query.maxPointCount | integer | 최대 포인트 수 | |
| query.workspaceUUID | string | 조회할 단일 권한 부여자 워크스페이스 UUID. *는 targetRegion 내 모든 권한이 부여된 워크스페이스를 조회함을 의미합니다. |
|
| query.workspaceUUIDs | array | 조회할 권한 부여자 워크스페이스 UUID 목록. 비어 있지 않으면 query.workspaceUUID보다 우선합니다. 동일한 목록은 반드시 같은 사이트에 속해야 합니다. ["*"]는 targetRegion 내 모든 권한이 부여된 워크스페이스를 조회함을 의미합니다. 두 필드를 동시에 전달하지 않는 것이 좋습니다. |
|
| query.targetRegion | string | 권한 부여자 워크스페이스가 속한 사이트의 regionCode. /wksp_share/granted_ws_list에서 대상 workspaceUUID와 같은 그룹의 regionCode로 가져옵니다. 명시적 사이트 간 조회 시 전달하는 것이 좋으며, * 조회 시에는 반드시 전달해야 합니다. |
|
| query.output_format | string | lineprotocol: 라인 프로토콜 출력. 기본값을 입력하지 않으면 기존 출력 형식이 유지됩니다. | |
| query.cursor_time | integer | 세그먼트 조회 임계값. 첫 번째 세그먼트 조회 시 end_time으로 설정하고, 이후에는 응답의 next_cursor_time을 전달합니다. |
|
| query.cursor_token | string | 페이지네이션 조회 토큰(엔진이 반환하는 cursor_token 값). 페이지네이션 조회 시 이전 조회에서 반환된 next_cursor_token을 이번 조회의 cursor_token으로 설정해야 합니다. cursor_token이 없는 요청은 페이지를 넘길 때 동일한 타임스탬프의 데이터가 건너뛰어질 수 있습니다. | |
| query.disable_sampling | bool | 샘플링 비활성화 스위치. 기본값은 false입니다. | |
| query.disable_truncate | bool | 반환 내용 잘림 비활성화 여부. 기본값은 false이며 잘림을 허용함을 의미합니다. |
- 응답 포인트 밀도
density파라미터 값 설명
| 선택 값 | 설명 |
|---|---|
| lower | 상대적으로 낮음, 60개 포인트 |
| low | 낮음, 180개 포인트 |
| medium | 중간, 360개 포인트 |
| high | 높음, 720개 포인트 |
-
포인트 밀도 파라미터의 우선순위에 유의하십시오. 최대 밀도는
density[high]입니다. * maxPointCount > interval > density > dql 문의 제어 파라미터 -
일반적인 조회 설명
- OpenAPI 사이트 간 데이터 조회
참고: OpenAPI 엔드포인트로 데이터를 조회할 때 기본 역할은 관리자입니다. 데이터 액세스 규칙의 제한을 받을 수 있으므로 유의하십시오.
요청 예시¶
curl 'https://openapi.guance.com/api/v1/df/query_data?body=\{%22queries%22:\[\{%22uuid%22:%2205ea25f0-2fa3-11ee-aa03-57233270ef0c%22,%22qtype%22:%22dql%22,%22query%22:\{%22q%22:%22L::re(`.*`):(`*`)\{+`index`+IN+\[%27default%27\]+\}%22,%22highlight%22:true,%22limit%22:50,%22orderby%22:\[\{%22time%22:%22desc%22\}\],%22_funcList%22:\[\],%22funcList%22:\[\],%22disableMultipleField%22:false,%22align_time%22:false,%22is_optimized%22:true,%22offset%22:0,%22search_after%22:\[1690808645037,538070,%22L_1690808645037_cj3r2itnel8fnfu5tlag%22\],%22timeRange%22:\[1690807857000,1690808757999\],%22tz%22:%22Asia/Shanghai%22\}\}\],%22expensiveQueryCheck%22:true\}' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--compressed
응답¶
{
"code": 200,
"content": {
"data": [
{
"AsyncTaskPayload": null,
"async_id": "",
"column_names": [
"container_id",
"source",
"filepath",
"image",
"index",
"df_metering_size",
"__namespace",
"host",
"log_read_offset",
"__docid",
"filename",
"service",
"image_name",
"image_short_name",
"image_tag",
"log_read_lines",
"message",
"log_read_time",
"container_name",
"container_type",
"message_length",
"create_time",
"container_runtime_name",
"date_ns",
"status"
],
"complete": false,
"cost": "19ms",
"index_name": "",
"index_names": "",
"index_store_type": "es",
"is_running": false,
"points": null,
"query_type": "",
"raw_query": "{\\\"aggs\\\":{},\\\"_source\\\":{\\\"excludes\\\":[\\\"message@json\\\"],\\\"includes\\\":[]},\\\"query\\\":{\\\"bool\\\":{\\\"filter\\\":[{\\\"term\\\":{\\\"__namespace\\\":\\\"logging\\\"}},{\\\"range\\\":{\\\"date\\\":{\\\"gte\\\":\\\"1680187562081\\\",\\\"lte\\\":\\\"1680230762081\\\"}}},{\\\"bool\\\":{\\\"should\\\":[{\\\"terms\\\":{\\\"index\\\":[\\\"default\\\"]}}]}}]}},\\\"size\\\":50,\\\"sort\\\":[{\\\"date\\\":{\\\"missing\\\":\\\"_last\\\",\\\"order\\\":\\\"desc\\\",\\\"unmapped_type\\\":\\\"long\\\"}},{\\\"date_ns\\\":{\\\"missing\\\":\\\"_last\\\",\\\"order\\\":\\\"desc\\\",\\\"unmapped_type\\\":\\\"long\\\"}},{\\\"__docid\\\":{\\\"missing\\\":\\\"_first\\\",\\\"order\\\":\\\"desc\\\",\\\"unmapped_type\\\":\\\"string\\\"}}],\\\"search_after\\\":[1680226330509,8572,\\\"L_1680226330509_cgj4hqbrhi85kl1m6os0\\\"],\\\"timeout\\\":\\\"54s\\\"}",
"search_after": [
1680226330508,
82936,
"L_1680226330508_cgj4hbdepb7fcn07sf60"
],
"series": [
{
"columns": [
"container_id",
"time",
"source",
"filepath",
"image",
"index",
"df_metering_size",
"__namespace",
"host",
"log_read_offset",
"__docid",
"filename",
"service",
"image_name",
"image_short_name",
"image_tag",
"log_read_lines",
"message",
"log_read_time",
"container_name",
"container_type",
"message_length",
"create_time",
"container_runtime_name",
"date_ns",
"status"
],
"values": [
[
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
1680226330509,
"test",
"/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test:test",
"default",
1,
"logging",
"izbp152ke14timzud0du15z",
149232879,
"L_1680226330509_cgj4hqbrhi85kl1m6org",
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test",
"test",
"test",
"test",
147890,
"ddtrace.profiling.exporter.http.UploadFailed: [Errno 101] Network is unreachable",
1680226330508872700,
"compose_python_ddtrace_web_b_1",
"docker",
80,
1680230633485,
"compose_python_ddtrace_web_b_1",
8571,
"unknown"
],
[
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
1680226330509,
"test",
"/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test:test",
"default",
1,
"logging",
"izbp152ke14timzud0du15z",
149232879,
"L_1680226330509_cgj4hqbrhi85kl1m6or0",
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test",
"test",
"test",
"test",
147889,
" raise retry_exc from fut.exception()",
1680226330508872700,
"compose_python_ddtrace_web_b_1",
"docker",
40,
1680230633485,
"compose_python_ddtrace_web_b_1",
8570,
"unknown"
],
[
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
1680226330509,
"test",
"/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test:test",
"default",
1,
"logging",
"izbp152ke14timzud0du15z",
149232879,
"L_1680226330509_cgj4hqbrhi85kl1m6oqg",
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test",
"test",
"test",
"test",
147888,
" File \\\"/usr/local/lib/python3.7/site-packages/tenacity/__init__.py\\\", line 361, in iter",
1680226330508872700,
"compose_python_ddtrace_web_b_1",
"docker",
87,
1680230633485,
"compose_python_ddtrace_web_b_1",
8569,
"unknown"
],
[
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380",
1680226330508,
"test",
"/var/lib/docker/containers/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380/2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test:test",
"default",
1,
"logging",
"izbp152ke14timzud0du15z",
149228783,
"L_1680226330508_cgj4hbdepb7fcn07sf60",
"2fef685801c80b5cb7d04b7b5e859007de94752aadbe801df812a058acf5e380-json.log",
"test",
"test",
"test",
"test",
147841,
"KeyError: 'dd.service'",
1680226330507918000,
"compose_python_ddtrace_web_b_1",
"docker",
22,
1680230573234,
"compose_python_ddtrace_web_b_1",
82936,
"unknown"
]
]
}
],
"total_hits": 10000
}
]
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-CD50CBBD-E29B-4F58-BD6B-618EED50920A"
}