본문으로 건너뛰기
번역된 페이지

이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.

출력 모드

참고 항목:
[exec] [shell]

StackQL 쿼리에서 반환된 결과는 표 형식(table)뿐 아니라 json, jsonl(줄 바꿈으로 구분된 JSON), csv, text 또는 otel(OpenTelemetry 로그 레코드) 형식으로 지정할 수 있습니다. JSON, JSONL, CSV 형식은 다른 프로그램과 데이터를 교환하는 데 사용할 수 있으며, otel 형식은 결과 집합을 타임스탬프가 지정된 스냅샷으로 OpenTelemetry 백엔드에 전송합니다. 원하는 출력 형식은 StackQL의 --output 플래그로 구성합니다.

table 출력 형식​

아래와 같이 --output 매개 변수에 table 값(StackQL 대화형 셸의 기본값)을 사용하면 결과를 표 형식으로 지정할 수 있습니다:

stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' \
and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output table

|---------------------|-----------------|
| ID | NAME |
|---------------------|-----------------|
| 1257085253691867467 | demo-instance-1 |
|---------------------|-----------------|
| 2586731219281477960 | demo-instance-2 |
|---------------------|-----------------|
| 5584456226809282885 | demo-instance-3 |
|---------------------|-----------------|

json 출력​

아래와 같이 --output 매개 변수에 json 값을 사용하면 결과를 JSON 형식으로 반환할 수 있습니다. 이 출력 형식은 쿼리 결과를 외부 프로세스나 스크립트에 전달해야 하는 경우에 유용합니다:

stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' \
and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output json

[{"id":"5584456226809282885","name":"demo-instance-3"}
,{"id":"1257085253691867467","name":"demo-instance-1"}
,{"id":"2586731219281477960","name":"demo-instance-2"}]

jsonl 출력​

아래와 같이 --output 매개 변수에 jsonl 값을 사용하면 결과를 줄 바꿈으로 구분된 JSON(JSON Lines) 형식으로 반환할 수 있습니다(ndjson 값도 별칭으로 허용됩니다). 각 행은 한 줄에 하나의 JSON 객체로 기록되고 기록되는 즉시 플러시되므로, 이 출력 형식은 줄 단위로 처리하는 도구로 결과를 스트리밍하거나 큰 결과 집합을 다른 프로그램으로 파이프하는 데 유용합니다:

stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' \
and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output jsonl

{"id":"5584456226809282885","name":"demo-instance-3"}
{"id":"1257085253691867467","name":"demo-instance-1"}
{"id":"2586731219281477960","name":"demo-instance-2"}

csv 출력​

아래와 같이 --output 매개 변수에 csv 값을 사용하면 결과를 CSV 형식으로 반환할 수 있습니다. 이 출력 형식은 Excel에서 결과를 구문 분석하거나 다른 시스템에 데이터 인터페이스를 제공하는 데 유용합니다:

stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' \
and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output csv

id,name
1257085253691867467,demo-instance-1
2586731219281477960,demo-instance-2
5584456226809282885,demo-instance-3

Csv 출력 예제(대체 구분 기호 사용)​

아래와 같이 -d 스위치를 사용하여 csv 출력 형식에 대체 구분 기호를 지정할 수 있습니다:

stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' \
and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output csv -d "|"

id|name
1257085253691867467|demo-instance-1
2586731219281477960|demo-instance-2
5584456226809282885|demo-instance-3

text 출력​

--output 매개 변수에 text 값을 사용하면 결과를 일반 텍스트로 반환할 수 있습니다. 각 행은 값을 쉼표로 연결한 형태로 기록되며, -H(--hideheaders) 플래그를 설정하지 않으면 그 앞에 머리글 행이 출력됩니다. csv 형식과 달리 값을 따옴표로 묶거나 이스케이프하지 않고 -d 구분 기호도 무시하므로, 쉼표나 큰따옴표가 포함된 값은 그대로 기록됩니다:

stackql exec "SELECT 'a,b' AS letters, 'say \"hi\"' AS greeting" --output text

letters,greeting
a,b,say "hi"

--output csv 플래그를 사용하면 같은 쿼리의 데이터 행은 "a,b","say ""hi"""로 반환됩니다.

otel 출력​

--output 매개 변수에 otel 값을 사용하면 결과를 OpenTelemetry 로그 레코드로 내보낼 수 있습니다. 각 행은 한 줄에 하나의 OTLP/JSON LogsData 객체로 기록되고 jsonl 형식처럼 기록되는 즉시 플러시되며, 그 뒤에 해당 문의 완료 레코드 1개가 이어집니다. 이 출력 형식은 쿼리를 텔레메트리 형태의 클라우드 구성 스냅샷으로 변환합니다. 인벤토리 쿼리를 일정에 따라 실행하고, 레코드를 OTLP를 지원하는 백엔드(ClickHouse, Datadog 또는 다른 백엔드 앞에 둔 OpenTelemetry Collector)로 전송한 다음, 그곳에서 "현재 자산은 어떤 상태인가", "마지막 실행 이후 무엇이 변경되었나", "누가 어떤 사용 권한을 언제부터 가지고 있었나"에 답할 수 있습니다. StackQL v0.11.660 이상에서 사용할 수 있습니다.

stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' \
and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output otel -f instances.otlp.jsonl

다음은 보기 좋게 출력한 행 레코드 1개입니다(파일에는 각 레코드가 한 줄에 저장됩니다):

{"resourceLogs":[{"resource":{"attributes":[
{"key":"service.name","value":{"stringValue":"stackql"}},
{"key":"service.version","value":{"stringValue":"0.11.660"}},
{"key":"cloud.provider","value":{"stringValue":"gcp"}},
{"key":"cloud.account.id","value":{"stringValue":"stackql-demo"}},
{"key":"cloud.availability_zone","value":{"stringValue":"australia-southeast1-a"}}
]},"scopeLogs":[{"scope":{"name":"github.com/stackql/stackql/internal/stackql/output","version":"1.0.0"},
"logRecords":[{
"timeUnixNano":"1788739200000000000","observedTimeUnixNano":"1788739203412000000",
"severityNumber":9,"severityText":"INFO",
"body":{"stringValue":"{\"id\":\"1257085253691867467\",\"name\":\"demo-instance-1\"}"},
"attributes":[
{"key":"id","value":{"stringValue":"1257085253691867467"}},
{"key":"name","value":{"stringValue":"demo-instance-1"}},
{"key":"stackql.snapshot.id","value":{"stringValue":"1e0d4a6c-4b0f-4b4e-9f7d-2a6c9a1f3b21"}},
{"key":"stackql.query","value":{"stringValue":"select id, name from google.compute.instances where project = 'stackql-demo' and zone = 'australia-southeast1-a'"}},
{"key":"stackql.query.hash","value":{"stringValue":"9c1d2e..."}},
{"key":"stackql.provider","value":{"stringValue":"google"}},
{"key":"stackql.service","value":{"stringValue":"compute"}},
{"key":"stackql.resource","value":{"stringValue":"instances"}},
{"key":"stackql.row.index","value":{"intValue":"0"}},
{"key":"stackql.row.fingerprint","value":{"stringValue":"sha256:7f3a..."}}
],
"traceId":"4bf92f3577b34da6a3ce929d0e0e4736","spanId":"a1b2c3d4e5f60718"
}],"schemaUrl":"https://opentelemetry.io/schemas/1.44.0"}],"schemaUrl":"https://opentelemetry.io/schemas/1.44.0"}]}

스냅샷​

하나의 문은 하나의 스냅샷입니다. 문의 모든 레코드는 동일한 timeUnixNano 값(문 시작 시간), 동일한 stackql.snapshot.id 값, 동일한 spanId 값을 가지므로, 행이 여러 페이지에 걸쳐 몇 초 동안 도착하더라도 특정 시점 기준 쿼리, 차이 비교, 최신 상태 쿼리가 작동합니다. observedTimeUnixNano 값은 각 레코드가 실제로 기록된 시간을 나타냅니다. 한 번의 호출에 포함된 모든 문은 하나의 traceId 값을 공유합니다. 이 값은 TRACEPARENT 환경 변수가 설정되어 있으면 그 값을 사용하고(CI 파이프라인의 관례), 그렇지 않으면 생성됩니다.

문의 마지막 레코드는 완료 레코드입니다. 완료 레코드의 본문은 snapshot complete <provider.service.resource> 형식이며, stackql.snapshot.complete=true, stackql.rows_returned, stackql.duration_ms 속성을 포함합니다. 이 레코드는 스냅샷이 완전하다는 것을 백엔드에 알립니다. 행을 반환하지 않는 문도 이 레코드를 내보내므로, 사라진 리소스는 아무 신호 없이 사라지는 대신 드리프트로 나타납니다. StackQL이 --errorpresentation record 플래그로 실행되는 경우 실패한 문은 error.type 속성과 error.message 속성을 포함하는 ERROR 레코드를 생성합니다. 기본적으로 오류는 다른 모든 출력 형식과 마찬가지로 stderr로 출력됩니다.

레코드 형태​

본문은 중첩된 객체를 그대로 유지한 압축 JSON 형식의 전체 행이며, 전체 문서의 단일 정보 출처입니다. 속성은 각 열을 해당 열 이름으로 전달하며, 값이 스칼라인 경우 형식이 지정됩니다(stringValue, intValue, doubleValue, boolValue). 중첩된 열은 JSON 문자열로 전달되므로 기본 속성 스키마가 문자열 값인 백엔드 간에 이식할 수 있으며, null 열은 생략됩니다. 예약된 stackql.* 속성은 다음과 같습니다:

속성레코드값
stackql.snapshot.id모두문 실행마다 생성되는 UUID
stackql.query모두제출된 쿼리 텍스트(원문 그대로)
stackql.query.hash모두쿼리 텍스트의 SHA-256으로, 반복 작업에서 SQL 자체보다 비용이 적게 드는 시리즈 키
stackql.provider, stackql.service, stackql.resource모두문의 기본 테이블이며, 여러 테이블에 걸친 조인과 뷰에서는 생략됨
stackql.row.index행결과 집합에서 0부터 시작하는 위치
stackql.row.fingerprint행정규화된 행 JSON의 sha256: 값으로, 모든 속성을 비교하는 대신 identity당 한 번만 비교하면 드리프트를 확인할 수 있음
stackql.snapshot.complete완료true
stackql.rows_returned완료문의 행 수
stackql.duration_ms완료문 시작부터 경과한 실제 시간

내보내는 속성 집합은 버전이 지정된 인터페이스입니다. 계측 범위는 버전 1.0.0의 github.com/stackql/stackql/internal/stackql/output이며, schemaUrl 값은 안정 규칙을 https://opentelemetry.io/schemas/1.44.0으로 고정합니다.

리소스 ID는 유추되지 않습니다. 지문은 값이고, 키는 백엔드가 선택합니다(id, arn, selfLink 또는 열의 튜플). 사용 권한을 엔터티로 추적하려면 SQL에서 바인딩을 보안 주체 및 역할당 1행으로 펼치세요. 텔레메트리는 결과의 세분성을 따릅니다.

리소스 속성​

리소스에는 service.name 속성(stackql 또는 OTEL_SERVICE_NAME 값)과 service.version 속성이 포함됩니다. 또한 단일 테이블 SELECT 문에서 도출할 수 있는 경우 OpenTelemetry 클라우드 규칙의 속성(프로바이더에서 cloud.provider; WHERE 절의 project 또는 subscriptionId 등호 조건에서 cloud.account.id; region에서 cloud.region; zone에서 cloud.availability_zone)과 표준 OTEL_RESOURCE_ATTRIBUTES 환경 변수의 모든 쌍이 포함됩니다. 따라서 파이프라인 단계에서 추가 플래그 없이 deployment.environment, 작업 이름 또는 계정 태그를 기록할 수 있습니다:

TRACEPARENT=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01 \
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=prod,stackql.job=gce-inventory \
stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output otel -f instances.otlp.jsonl

레코드 전송​

파일에는 한 줄에 하나의 LogsData 객체가 있으며, 이는 OpenTelemetry Collector의 otlp_json_file 리시버가 변환 프로세서 없이 수집하는 형태입니다:

receivers:
otlp_json_file:
include: [/var/lib/stackql/inventory/*.otlp.jsonl]
exporters:
otlphttp:
endpoint: https://otlp.example.com
service:
pipelines:
logs:
receivers: [otlp_json_file]
exporters: [otlphttp]

각 줄은 또한 OTLP/HTTP POST /v1/logs 엔드포인트가 요청 본문으로 받아들이는 완전한 OTLP/JSON LogsData 객체입니다. 기본 제공 푸시 익스포터는 같은 인코딩을 보내지만, 아래에서 설명하는 것처럼 레코드를 배치로 묶어 보냅니다.

OTLP 엔드포인트로 푸시​

--otel.config 플래그에 익스포터를 구성하면 레코드를 파일이나 stdout에 기록하는 것과 함께 OTLP/HTTP 로그 엔드포인트로 직접 푸시할 수 있습니다. 이 플래그는 다른 구성 플래그와 마찬가지로 JSON 또는 YAML 문자열입니다(StackQL v0.12.732 이상에서 사용할 수 있습니다):

stackql exec "select id, name from google.compute.instances \
where project = 'stackql-demo' and zone = 'australia-southeast1-a'" \
--auth '{ "google": { "type": "service_account", "credentialsfilepath": "stackql-demo.json" } }' --output otel -f instances.otlp.jsonl \
--otel.config '{ "exporter": { "endpoint": "http://clickstack.example:4318/v1/logs", "headers": { "authorization": "'"$CLICKSTACK_INGESTION_KEY"'" } } }'
키용도
exporter.endpoint로그 엔드포인트의 전체 URL(예: http://localhost:4318/v1/logs). 익스포터를 활성화하려면 필수
exporter.headers내보내기마다 전송되는 요청 헤더로, 일반적으로 수집 토큰 또는 API 키
exporter.timeout_ms요청 시간 제한(밀리초), 기본값 10000
exporter.batch_size요청당 레코드 수, 기본값 512

각 문은 하나의 배치입니다. 문의 행 레코드와 완료 레코드는 하나의 OTLP/JSON LogsData 객체(리소스 및 범위 엔벨로프 1개, 레코드당 logRecords 항목 1개)로 전송됩니다. 큰 결과 집합은 행이 스트리밍되는 동안 최대 batch_size개 레코드의 요청으로 분할되며, 마지막 요청은 완료 레코드 뒤에 전송됩니다. 429 및 5xx 응답과 연결 실패는 500ms부터 두 배씩 늘어나는 백오프를 적용하여 최대 4회까지 시도하며, 서버가 지연 시간(초)을 지정한 Retry-After 헤더를 보내면 이를 따릅니다(최대 30초). 다른 오류는 재시도하지 않습니다. 파일 또는 스트림은 그와 관계없이 기록되므로, 푸시에 실패해도 로컬 사본과 stderr의 오류 줄이 남습니다. 익스포터는 HTTP를 통해 OTLP/JSON으로 통신합니다. protobuf만 허용하는 엔드포인트에는 앞단에 Collector가 필요합니다.

OTEL_EXPORTER_OTLP_* 환경 변수는 읽지 않습니다. 모든 익스포터 설정은 --otel.config 플래그에서 가져옵니다. --otel.config 값의 형식이 잘못되었거나 exporter 객체에 endpoint 키가 없으면 시작에 실패합니다.

이 기능은 ClickStack의 OTLP 수집 엔드포인트(http://<host>:4318/v1/logs, 헤더 authorization: <ingestion API key>), Datadog Agent의 OTLP 리시버 또는 Datadog OTLP 수집 엔드포인트(dd-api-key: <key>), 그리고 모든 OpenTelemetry Collector otlp 리시버를 대상으로 합니다. 수신 측의 인벤토리, 드리프트, 사용 권한 쿼리는 OTel 백엔드 레시피를 참조하세요.