Перейти до основного вмісту
Перекладена сторінка

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

Режими виводу

Див. також:
[exec] [shell]

Результати запитів 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.