Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.
Режими виводу
Результати запитів StackQL можна виводити в табличному форматі (table), а також у форматах json, jsonl (JSON, розділений символами нового рядка), csv, text або otel (записи журналу OpenTelemetry). Формати JSON, JSONL і CSV можна використовувати для обміну даними з іншими програмами; формат otel надсилає набір результатів у бекенд OpenTelemetry як знімок із позначкою часу. Потрібний формат виводу вказують за допомогою прапорця StackQL --output.
Формат виводу table
Результати можна відформатувати як таблицю за допомогою значення table параметра --output, як показано нижче (це значення за замовчуванням для інтерактивної оболонки 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
Результати можна отримати у форматі JSON за допомогою значення json параметра --output, як показано нижче; цей формат виводу зручний, якщо результати запиту потрібно передати зовнішньому процесу або скрипту:
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
Результати можна отримати у форматі JSON, розділеному символами нового рядка (JSON Lines), за допомогою значення jsonl параметра --output, як показано нижче (також приймається псевдонім 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
Результати можна отримати у форматі CSV за допомогою значення csv параметра --output, як показано нижче; цей формат виводу зручний для обробки результатів в 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 (з альтернативним роздільником)
Для формату виводу csv можна вказати інший роздільник за допомогою прапорця -d, як показано нижче:
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
Результати можна отримати як звичайний текст за допомогою значення text параметра --output. Кожен рядок результату виводиться як його значення через кому, а перед рядками виводиться рядок заголовків, якщо не вказано -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
Результати можна виводити як записи журналу OpenTelemetry за допомогою значення otel параметра --output. Кожен рядок результату записується в окремий рядок виводу як один об'єкт OTLP/JSON LogsData і скидається у вивід одразу під час запису, як у форматі jsonl; після них іде один запис про завершення інструкції. Цей формат виводу перетворює запит на знімок хмарної конфігурації у формі телеметрії: запускайте запит інвентаризації за розкладом, надсилайте записи в бекенд із підтримкою 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
Один запис рядка у відформатованому вигляді (у файлі кожен запис займає один рядок):
{"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. Він повідомляє бекенду, що знімок повний, і навіть інструкція, яка не повертає рядків, виводить його, тому ресурс, що зник, видно як дрейф, а не як відсутність даних. Інструкція, що завершилася помилкою, створює запис ERROR з атрибутами error.type і error.message, якщо StackQL запущено з прапорцем --errorpresentation record; за замовчуванням помилки, як і для всіх інших форматів виводу, надходять у 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 | рядок | Позиція в наборі результатів, починаючи з нуля |
stackql.row.fingerprint | рядок | sha256: канонічного JSON рядка, тож дрейф визначається одним порівнянням на кожну ідентичність замість порівняння всіх атрибутів |
stackql.snapshot.complete | завершення | true |
stackql.rows_returned | завершення | Кількість рядків інструкції |
stackql.duration_ms | завершення | Фактична тривалість від початку інструкції |
Набір атрибутів у виводі - це версіонований інтерфейс: область інструментування - github.com/stackql/stackql/internal/stackql/output версії 1.0.0, а schemaUrl закріплює стабільні конвенції на https://opentelemetry.io/schemas/1.44.0.
Ідентичність ресурсу не визначається автоматично: відбиток - це значення, а ключ вибирає бекенд (id, arn, selfLink або кортеж стовпців). Щоб відстежувати права доступу як сутності, розкладіть прив'язки в SQL на окремі рядки, один рядок на кожну пару principal і роль; телеметрія відповідає гранулярності результату.
Атрибути ресурсу
Ресурс містить service.name (stackql або значення OTEL_SERVICE_NAME) і service.version, хмарні конвенції OpenTelemetry, якщо їх можна вивести з інструкції SELECT з однією таблицею (cloud.provider - з провайдера; cloud.account.id - з умови рівності для project або subscriptionId у реченні WHERE; cloud.region - з region; cloud.availability_zone - з 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 на рядок - саме в такій формі приймач otlp_json_file з OpenTelemetry Collector приймає дані без процесора transform:
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/JSON LogsData, який кінцева точка OTLP/HTTP POST /v1/logs приймає як тіло запиту. Вбудований експортер для надсилання використовує те саме кодування, але групує записи в пакети, як описано нижче.
Надсилання до кінцевої точки OTLP
Записи можна надсилати безпосередньо в кінцеву точку журналів OTLP/HTTP, а також записувати у файл або stdout, налаштувавши експортер у прапорці --otel.config - рядку 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 (одна обгортка ресурсу та області, один елемент у logRecords на кожен запис), а великий набір результатів під час потокового надходження рядків розбивається на запити, кожен з яких містить не більше ніж batch_size записів, причому останній запит надсилається після запису про завершення. Для відповідей 429 і 5xx та в разі збоїв з'єднання виконується до чотирьох спроб із подвоєнням затримки, починаючи з 500ms; якщо сервер надсилає заголовок Retry-After із затримкою в секундах, його враховують (з обмеженням у 30 секунд); інші помилки не повторюються. Файл або потік записується в будь-якому разі, тому невдале надсилання залишає локальну копію та рядок помилки в stderr. Експортер працює з OTLP/JSON через HTTP; кінцевій точці, яка приймає лише protobuf, потрібен Collector перед нею.
Змінні середовища OTEL_EXPORTER_OTLP_* не зчитуються; усі налаштування експортера беруться з прапорця --otel.config. Неправильно сформоване значення --otel.config або об'єкт exporter без endpoint призводить до помилки під час запуску.
Цей експортер розраховано на приймання OTLP у ClickStack (http://<host>:4318/v1/logs, заголовок authorization: <ingestion API key>), приймач OTLP у Datadog Agent або приймання OTLP у Datadog (dd-api-key: <key>) і будь-який приймач otlp в OpenTelemetry Collector. Запити інвентаризації, дрейфу й прав доступу на стороні приймання див. на сторінці Рецепти для бекендів OTel.