Esta página foi traduzida do inglês com assistência de IA. Se houver diferenças entre as duas, a versão em inglês é a referência.
Modos de saída
Os resultados retornados pelas consultas do StackQL podem ser formatados em formato tabular (table), bem como nos formatos json, jsonl (JSON delimitado por quebras de linha), csv, text ou otel (registros de log do OpenTelemetry). Os formatos JSON, JSONL e CSV podem ser usados para trocar dados com outros programas; o formato otel envia um conjunto de resultados a um backend do OpenTelemetry como um snapshot com carimbo de data/hora. O formato de saída desejado é configurado com a opção --output do StackQL.
Formato de saída table
Os resultados podem ser formatados como tabela com o valor table do parâmetro --output, como mostrado abaixo (este é o valor padrão do shell interativo do 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 |
|---------------------|-----------------|
Saída json
Os resultados podem ser retornados em formato JSON com o valor json do parâmetro --output, como mostrado abaixo; este formato de saída é útil quando os resultados de uma consulta precisam ser passados para um processo ou script externo:
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"}]
Saída jsonl
Os resultados podem ser retornados em formato JSON delimitado por quebras de linha (JSON Lines) com o valor jsonl do parâmetro --output, como mostrado abaixo (ndjson é aceito como alias). Cada linha do resultado é gravada como um único objeto JSON em uma linha própria, e as linhas são liberadas (flush) à medida que são gravadas, o que torna este formato de saída útil para transmitir resultados em fluxo contínuo a ferramentas orientadas a linhas ou para encaminhar grandes conjuntos de resultados a outros programas por pipe:
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"}
Saída csv
Os resultados podem ser retornados em formato CSV com o valor csv do parâmetro --output, como mostrado abaixo; este formato de saída é útil para analisar resultados no Excel ou fornecer uma interface de dados a outro sistema:
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
Exemplo de saída csv (com delimitador alternativo)
Um delimitador alternativo pode ser especificado para o formato de saída csv com a opção -d, como mostrado abaixo:
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
Saída otel
Os resultados podem ser emitidos como registros de log do OpenTelemetry com o valor otel do parâmetro --output. Cada linha do resultado é gravada como um objeto OTLP/JSON LogsData em uma linha própria, liberada (flush) assim que é gravada, como em jsonl, seguida de um registro de conclusão da instrução. Este formato de saída transforma uma consulta em um snapshot da configuração na nuvem na forma de telemetria: execute uma consulta de inventário de forma agendada, envie os registros a um backend compatível com OTLP (ClickHouse, Datadog ou um OpenTelemetry Collector na frente de qualquer outro) e responda ali a "como está o parque agora", "o que mudou desde a última execução" e "quem teve qual direito de acesso, e desde quando". Disponível a partir do 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
Um registro de linha, formatado para leitura (o arquivo contém cada registro em uma única linha):
{"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"}]}
Snapshots
Uma instrução é um snapshot. Todos os registros da instrução têm o mesmo timeUnixNano (o horário de início da instrução), o mesmo stackql.snapshot.id e o mesmo spanId, de modo que consultas do estado em um momento dado, comparações e consultas do estado mais recente funcionam mesmo que as linhas cheguem em várias páginas ao longo de vários segundos; observedTimeUnixNano registra quando cada registro foi efetivamente gravado. Todas as instruções de uma invocação compartilham um traceId, obtido da variável de ambiente TRACEPARENT quando ela está definida (a convenção para pipelines de CI) e gerado nos demais casos.
O último registro de uma instrução é o registro de conclusão: corpo snapshot complete <provider.service.resource>, com stackql.snapshot.complete=true, stackql.rows_returned e stackql.duration_ms. Ele informa ao backend que o snapshot está completo, e uma instrução que não retorna linhas também o emite, de modo que um recurso que desapareceu aparece como desvio, e não como silêncio. Uma instrução com falha produz um registro ERROR com error.type e error.message quando a apresentação de erros é record; por padrão, os erros vão para stderr, como em todos os outros formatos de saída.
Formato do registro
O corpo é a linha completa em JSON compacto, com os objetos aninhados intactos, e é a fonte da verdade do documento completo. Os atributos contêm cada coluna com o próprio nome, tipados quando o valor é escalar (stringValue, intValue, doubleValue, boolValue); as colunas aninhadas são transportadas como strings JSON, o que é portável entre backends cujo esquema de atributos padrão usa valores string, e as colunas nulas são omitidas. Os atributos reservados stackql.* são:
| Atributo | Registro | Valor |
|---|---|---|
stackql.snapshot.id | todos | UUID gerado a cada execução da instrução |
stackql.query | todos | O texto da consulta enviada, sem alterações |
stackql.query.hash | todos | SHA-256 do texto da consulta; uma chave de série mais barata que o SQL para um job recorrente |
stackql.provider, stackql.service, stackql.resource | todos | A tabela principal da instrução; omitidos em joins e views que abrangem várias tabelas |
stackql.row.index | linha | Posição no conjunto de resultados, a partir de zero |
stackql.row.fingerprint | linha | sha256: do JSON canônico da linha, de modo que detectar desvio exige uma comparação por identidade em vez de uma comparação de todos os atributos |
stackql.snapshot.complete | conclusão | true |
stackql.rows_returned | conclusão | Número de linhas da instrução |
stackql.duration_ms | conclusão | Duração real (wall-clock) desde o início da instrução |
O conjunto de atributos emitido é uma interface versionada: o escopo de instrumentação é github.com/stackql/stackql/internal/stackql/output na versão 1.0.0, e schemaUrl fixa as convenções estáveis em https://opentelemetry.io/schemas/1.44.0.
Nenhuma identidade de recurso é inferida: a impressão digital é o valor, e o backend escolhe a chave (id, arn, selfLink ou uma tupla de colunas). Para acompanhar direitos de acesso como entidades, expanda as vinculações em SQL para uma linha por principal e role; a telemetria segue a granularidade do resultado.
Atributos do recurso
O recurso contém service.name (stackql ou o valor de OTEL_SERVICE_NAME) e service.version, as convenções de nuvem do OpenTelemetry quando podem ser derivadas de um SELECT de uma única tabela (cloud.provider a partir do provider; cloud.account.id a partir de uma igualdade em project ou subscriptionId na cláusula WHERE; cloud.region a partir de region; cloud.availability_zone a partir de zone) e cada par da variável de ambiente padronizada OTEL_RESOURCE_ATTRIBUTES, de modo que uma etapa do pipeline pode marcar deployment.environment, um nome de job ou tags de conta sem opções adicionais:
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
Enviar os registros
O arquivo tem um LogsData por linha, o formato que o receptor otlp_json_file do OpenTelemetry Collector ingere sem nenhum processador de transformação:
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]
Cada linha também é, byte a byte, o corpo de uma solicitação OTLP/HTTP POST /v1/logs, que é o que o exportador push integrado envia.
Enviar para um endpoint OTLP
Os registros podem ser enviados diretamente a um endpoint de logs OTLP/HTTP, além de serem gravados no arquivo ou em stdout, com a configuração de um exportador na opção --otel.config, uma string JSON ou YAML como as outras opções de configuração (disponível a partir do 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"'" } } }'
| Chave | Finalidade |
|---|---|
exporter.endpoint | URL completa do endpoint de logs, por exemplo http://localhost:4318/v1/logs; obrigatória para habilitar o exportador |
exporter.headers | Cabeçalhos de solicitação enviados em cada exportação, normalmente um token de ingestão ou uma chave de API |
exporter.timeout_ms | Tempo limite da solicitação em milissegundos, valor padrão 10000 |
exporter.batch_size | Registros por solicitação, valor padrão 512 |
Cada instrução é um lote: os seus registros de linha e o registro de conclusão são enviados como um único LogsData OTLP/JSON (um envelope de recurso e escopo, uma entrada em logRecords por registro), e um conjunto de resultados grande é dividido em solicitações de no máximo batch_size registros à medida que as linhas chegam, com a solicitação final enviada depois do registro de conclusão. Respostas 429 e 5xx e falhas de conexão são repetidas em até quatro tentativas, com um intervalo de espera que dobra a partir de 500ms, respeitando um cabeçalho Retry-After em segundos (limitado a 30 segundos) quando o servidor envia um; os outros erros não são repetidos. O arquivo ou o fluxo é gravado de qualquer forma, então um envio com falha deixa uma cópia local e uma linha de erro em stderr. O exportador usa OTLP/JSON sobre HTTP; um endpoint que só aceita protobuf precisa de um Collector na frente dele.
Nenhuma variável de ambiente OTEL_EXPORTER_OTLP_* é lida; todas as configurações do exportador vêm de --otel.config. Um valor malformado em --otel.config, ou um objeto exporter sem endpoint, faz a inicialização falhar.
Isso atende à ingestão OTLP do ClickStack (http://<host>:4318/v1/logs, cabeçalho authorization: <ingestion API key>), ao receptor OTLP de um Datadog Agent ou à ingestão OTLP do Datadog (dd-api-key: <key>) e a qualquer receptor otlp do OpenTelemetry Collector. Consulte Receitas de backends OTel para ver as consultas de inventário, desvio e direitos de acesso do lado receptor.