Recursos
Editor SQL
O Orbit SQL executa SQL somente leitura sobre tudo o que o produto guarda: o parque Kubernetes,
os custos, a trilha de auditoria, os logs, os traces, os spans e as métricas. O editor do Deck
fica em /deck/sql. Executar uma consulta requer a permissão telemetry.query, e cada tabela
pede a sua além dela (veja "Tabelas e permissões" abaixo); os papéis embutidos viewer,
editor e admin têm todos telemetry.query (veja identity.md). As rotas e
os formatos estão no Adendo v0.23 do CONTRACT.md.
A linguagem
O engine é o Apache DataFusion 55.1, dentro do orbit-api, e fala um SQL com sotaque de
PostgreSQL: joins, agregações, funções de janela, CTEs e subconsultas, com as funções do DataFusion
(approx_percentile_cont, date_bin, date_trunc, regexp_like e as demais).
- Ele é somente leitura, sempre.
SELECT,WITHeEXPLAINrodam;CREATE,COPY,INSERT,SETe qualquer outra instrução são recusadas, e nenhuma função lê um arquivo ou uma URL. - Cada requisição ganha uma sessão própria, com apenas as tabelas que quem chama pode ler. Uma
tabela que você não pode ler não existe para você, então pedi-la dá o velho "table not found". O
mesmo vale para uma tabela cujo recurso está desligado:
logscomlogs,tracesespanscomapm,recommendationsenamespace_costscomfinops(vejadocs/features.md). - Toda coluna tem um de seis tipos:
string,int,float,bool,timestampejson. Umtimestampvem em UTC, no formato RFC 3339 com milissegundos; um valorjsoné um objeto ou um array; o NULL do SQL vira o null do JSON. - As unidades são fixas: cores como float (0,25 equivale a 250m), bytes como int, dinheiro em USD
como float. Os nomes das colunas avisam:
*_bytes,*_usd,*_ms, e CPU em cores. - Nomes sem aspas ficam em minúsculas, como no PostgreSQL.
now()é o instante em que a consulta começou.
Usando o editor
- Ctrl+Enter (Cmd+Enter no Mac) executa a instrução em que o cursor está; com texto selecionado,
executa só a seleção. As instruções se separam por
;, então um mesmo editor comporta várias. - O autocompletar sugere palavras-chave, tabelas, as colunas das tabelas que a instrução lê e as duas funções de tabela; Ctrl+Space o abre em qualquer ponto. Tab aceita a sugestão destacada e, sem sugestão aberta, leva o foco para fora do editor, então o teclado nunca fica preso.
- Um erro volta com a linha e a coluna quando o DataFusion as sabe: o editor marca o trecho, a margem marca a linha, e "Mostrar linha" leva o cursor até lá.
- O painel de esquema lista as tabelas e funções que você pode consultar, agrupadas em parque, custo, auditoria, telemetria e métricas, com o tipo e o sentido de cada coluna. Um clique insere o nome onde está o cursor; cada tabela traz exemplos que abrem no editor.
- O resultado chega em uma grade: toda coluna ordena, os valores aparecem nas suas unidades, os
horários no fuso escolhido na barra superior, e uma célula
jsonabre por inteiro. Enter abre a linha com todos os valores, Ctrl+C copia a célula em que o teclado está, e "Exportar CSV" baixa o que a grade mostra, na ordem dela. A grade só desenha as linhas visíveis, então 10.000 linhas rolam como 50. - "Gráfico" desenha o resultado com os gráficos do próprio Deck: linhas ou áreas empilhadas sobre
uma coluna
timestamp, barras sobre qualquer outra coisa, uma pizza das linhas (as 8 maiores, com o total e a participação de cada uma) ou os números da primeira linha. Você escolhe a coluna do eixo x, as colunas numéricas a desenhar e a coluna cujos valores separam as linhas. Linhas, áreas e barras começam no zero. - "Plano" mostra o plano que o DataFusion executaria.
- "Cancelar" interrompe uma consulta em andamento, no navegador e no servidor.
- "Copiar link" coloca o SQL no fragmento do endereço (
#sql=), nunca nos parâmetros de consulta, então ele não aparece em log de servidor algum; abrir o link o executa. O editor mantém o seu SQL quando a página recarrega. - O histórico guarda as últimas 50 consultas que você executou, por usuário, só neste navegador.
- As consultas salvas ficam no
orbit-api, no seu nome. Dá para renomeá-las, excluí-las e compartilhá-las; uma consulta que alguém compartilha com o time abre somente leitura, e "Duplicar para editar" faz dela uma consulta sua. - "Escrever com o Nocturne" (com
nocturne.use) transforma uma frase em SQL escrito a partir do seu esquema e o coloca no editor junto com a explicação. O Nocturne nunca o executa: você lê e depois executa.
De uma consulta a um dashboard
{{name}}em uma instrução é um filtro, como no Metabase: aparece uma caixa para cada nome abaixo do editor, e o valor dela chega ao SQL como texto entre aspas (vários valores como lista separada por vírgula, paraIN ({{name}})). Uma cláusula entre[[ ]]sai enquanto os filtros dela estiverem vazios, entãoWHERE 1 = 1 [[AND country = {{country}}]]lê todas as linhas até você digitar um país. Um valor com barra invertida é recusado.- "Adicionar ao dashboard" (com
dashboards.write) coloca a resposta em um dashboard como card: o gráfico como você o configurou na aba "Gráfico", ou então a grade. Você escolhe um dos seus dashboards ou dá nome a um novo, e o próximo card vai para o mesmo dashboard por padrão. Os cards preenchem o dashboard de dois em dois. - Cada
{{name}}que o card lê vira um filtro no topo do dashboard, já ligado: um filtro preenche cada card que o cita, e Todos tira as cláusulas[[ ]]que o leem. Quando o SQL compara uma coluna com ele (c.country = {{country}}, ouIN ({{country}})para vários valores), o filtro lista os valores dessa coluna na tabela dela, lidos comSELECT DISTINCT; senão, é uma caixa de texto. Um filtro cujos valores não podem ser lidos aceita texto digitado. - Um card executa o SQL com a sessão de quem abre o dashboard: no Orbit SQL ele precisa de
telemetry.query, em uma conexão de banco dedatabases.querye de um papel que a conexão permita. Sem eles, o card avisa e não executa nada. Só quem tem essa permissão, numa conexão que o papel dele possa usar, adiciona um card SQL ou muda o SQL de um; quem temdashboards.writeainda move e redimensiona o card. - "Abrir no editor SQL", no menu do card, abre o SQL do card na fonte dele. O editor de painel muda o SQL, a fonte e as colunas que o gráfico lê (x, y, separar por).
- Um card desenha o gráfico como a aba "Gráfico" desenhou: todas as barras até 30, depois uma linha que diz quantas linhas a resposta tinha; a pizza nomeia as 8 maiores fatias e quantas linhas a resposta tem; contagens saem com três algarismos significativos, com o valor exato ao passar o mouse. Um eixo de tempo com mais de quatro meses marca o início de cada mês com o ano. Enquanto a resposta de um novo valor de filtro chega, o card espera em branco em vez de mostrar os números antigos. Um dashboard só de cards SQL esconde o período, que os cards não leem.
- Cada fatia e cada linha mantêm a cor que tinham no editor, seja qual for o filtro: o card guarda os labels com que foi criado, na ordem da paleta. As barras trazem a coluna de valor em cima e a de labels embaixo, e escrevem o valor sobre cada barra com "Valores" ligado.
- Um número de uma resposta com muitas linhas diz qual linha mostra ("card · amount, primeira de 4 linhas"). Ao longo do tempo, mostra o ponto mais recente, com a data, e a variação sobre o ponto anterior, como o card. A pizza escreve "Total" sob a soma.
- O editor esconde o período, que nenhuma instrução daqui lê (a janela de tempo vai no próprio SQL), e o intervalo de atualização automática, que ele segura.
Tabelas e permissões
As tabelas do parque cobrem todos os clusters que o orbit-api lê, e cada linha diz de qual
cluster ela é: a coluna cluster, ou id na própria clusters.
| Tabela | Permissão | O que é uma linha |
|---|---|---|
clusters | estate.read | Um cluster, com a capacidade e a conta dele |
nodes | estate.read | Um node: o que ele tem, o que usa e quanto custa |
namespaces | estate.read | Um namespace |
pods | estate.read | Um pod, com o dono, o node, os reinícios, os requests, os limits e o uso |
containers | estate.read | Um contêiner de um pod, com o estado e o motivo da última parada |
workloads | estate.read | Um Deployment, StatefulSet, DaemonSet, CronJob ou Job |
events | estate.read | Um evento do Kubernetes |
persistent_volumes | estate.read | Um PersistentVolume e o claim ligado a ele |
alerts | estate.read | Um alerta disparando ou pendente agora |
recommendations | estate.read | Uma mudança recomendada e quanto ela economiza por mês |
namespace_costs | estate.read | A fatia de um namespace na conta do cluster |
audit_events | audit.read | Um registro da trilha de auditoria |
logs | logs.read | Uma linha de log armazenada |
traces | apm.read | Um trace armazenado |
spans | apm.read | Um span armazenado |
promql(), promql_instant() | telemetry.query | Amostras do engine de métricas |
Todas as colunas, com os tipos:
clusters id string, name string, provider string, region string,
version string, nodes int, pods int, cpu_cores float,
memory_bytes int, monthly_cost_usd float
nodes cluster string, name string, node_group string,
instance_type string, capacity_type string, zone string,
status string, kubelet_version string, cpu_cores float,
cpu_used float, memory_bytes int, memory_used_bytes int,
pods int, hourly_cost_usd float, price_source string,
created_at timestamp, labels json
namespaces cluster string, name string, status string,
created_at timestamp, labels json
pods cluster string, namespace string, name string, node string,
phase string, ready bool, restarts int, owner_kind string,
owner_name string, workload string, qos_class string,
ip string, created_at timestamp, started_at timestamp,
cpu_request float, cpu_limit float, cpu_used float,
memory_request_bytes int, memory_limit_bytes int,
memory_used_bytes int, labels json
containers cluster string, namespace string, pod string, name string,
image string, ready bool, restarts int, state string,
reason string, last_termination_reason string,
cpu_request float, cpu_limit float,
memory_request_bytes int, memory_limit_bytes int
workloads cluster string, namespace string, kind string, name string,
replicas int, ready_replicas int, images json,
created_at timestamp, cpu_request float, cpu_used float,
memory_request_bytes int, memory_used_bytes int,
labels json
events cluster string, namespace string, object_kind string,
object_name string, type string, reason string,
message string, count int, first_seen timestamp,
last_seen timestamp
persistent_volumes cluster string, name string, capacity_bytes int, used_bytes int,
storage_class string, status string,
claim_namespace string, claim_name string
alerts cluster string, name string, severity string, state string,
namespace string, workload string, summary string,
since timestamp
recommendations cluster string, action string, namespace string,
workload string, kind string, monthly_savings_usd float,
summary string
namespace_costs cluster string, namespace string, monthly_cost_usd float,
share float
audit_events time timestamp, actor string, action string,
target_type string, target_name string, outcome string,
details json
logs ts timestamp, severity string, severity_number int,
service string, namespace string, pod string,
container string, node string, body string,
trace_id string, span_id string, attrs json
traces trace_id string, start_ts timestamp, duration_ms float,
root_service string, root_name string, status string,
spans int, errors int, services json
spans trace_id string, span_id string, parent_span_id string,
service string, name string, kind string, status string,
start_ts timestamp, end_ts timestamp, duration_ms float,
http_method string, http_route string,
http_status_code int, attrs json, resource jsonAlgumas ficam mais claras com os valores: capacity_type é ON_DEMAND ou SPOT; o kind de um
workload é Deployment, StatefulSet, DaemonSet, CronJob ou Job; share vai de 0 a 1; a
severity de um alerta é critical, warning ou info, e a de uma linha de log vai de TRACE a
FATAL; o outcome de uma linha de audit_events é success, denied ou failure. O
used_bytes de um volume é o sistema de arquivos do claim medido pelo kubelet
(kubelet_volume_stats_used_bytes), nulo quando nenhum pod em execução monta o claim ou quando esse
sistema de arquivos é o disco do node (um volume hostPath, como os do local-path). O painel
de esquema traz uma frase sobre cada coluna.
logs, traces e spans leem os armazenamentos do engine e repassam a ele o que podem: um
intervalo em ts ou start_ts (a última hora quando a consulta não indica nenhum, no máximo 7
dias), igualdade e IN nos labels, comparações em severity, body LIKE '%word%' como a busca
por palavra do engine, trace_id = e LIMIT. O resto é filtrado depois que o engine responde,
então um intervalo de tempo estreito é o filtro mais barato que existe.
Métricas
Duas funções de tabela leem o engine de métricas com PromQL:
promql(query, start, end, step)é uma consulta de intervalo: uma linha por amostra, comts,valuee uma coluna de texto para cada label que a resposta traz.starteendaceitam um timestamp ou um intervalo contado a partir de agora ('1h');endvale agora por padrão, estepo que der cerca de 240 pontos.promql_instant(query)é uma consulta instantânea: uma linha por série, com os labels como colunas e ovalue.
Quando a consulta é um seletor simples (container_cpu_usage_seconds_total,
kube_pod_info{namespace="shop"}), o Orbit SQL leva os seus filtros WHERE label = '...' e
label IN (...) para dentro do seletor, e o engine envia só as séries que casam. As colunas de um
seletor vêm do índice do engine: uma coluna de label pode ficar nula em todas as linhas.
SELECT namespace, avg(value) AS cores
FROM promql('sum by (namespace) (rate(container_cpu_usage_seconds_total[5m]))', '6h')
GROUP BY namespace
ORDER BY cores DESCLimites
- Uma consulta devolve no máximo 10.000 linhas; a página pede 1.000 a menos que você aumente. Passado o limite, a resposta para ali e avisa que foi truncada.
- Uma consulta pode rodar por 30 s, ou até 60 s se você permitir. Passado isso, ela é cancelada no
servidor e a resposta é
408 timeout. - Uma consulta pode usar 256 MiB de memória. Passado isso, ela é cancelada e a resposta é
413 too_large. - Um erro de SQL é
400 sql_error, com a linha e a coluna quando o DataFusion as informa.
Pela API
Com a SESSION de um usuário que tem telemetry.query (identity.md →
"Entrar pelo shell"):
| Rota | Requer | Corpo e resposta |
|---|---|---|
POST /api/v1/sql/query | telemetry.query | {sql, limit, timeoutMs} → {columns, rows, stats} |
POST /api/v1/sql/explain | telemetry.query | {sql} → {plan} |
GET /api/v1/sql/schema | telemetry.query | As tabelas e funções que quem chama pode consultar, com as colunas e os exemplos |
GET, POST /api/v1/sql/queries | telemetry.query | As consultas salvas de quem chama e as compartilhadas com ele; uma nova |
GET, PUT, DELETE /api/v1/sql/queries/{id} | telemetry.query | Uma consulta salva; só o dono a altera |
POST /api/v1/sql/generate | telemetry.query, nocturne.use | {prompt} → {sql, explanation}, nunca executado |
columns é [{name, type}], rows é um array de arrays na mesma ordem, e stats é
{rows, truncated, elapsedMs, scannedRows, tables}. Uma consulta salva é {id, name, description, sql, shared, owner, createdAt, updatedAt}; salvá-la fica registrado na auditoria como
sql.query.save, e excluí-la como sql.query.delete.
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \ -H 'Content-Type: application/json' \ -d '{"sql":"SELECT namespace, count(*) AS pod_count FROM pods GROUP BY namespace","limit":100}' \ localhost:8080/api/v1/sql/queryExemplos
A página abre com estes, e cada um roda como está escrito.
Pods reiniciando, por namespace:
SELECT cluster, namespace, count(*) AS pod_count, sum(restarts) AS restart_count
FROM pods
WHERE restarts > 0
GROUP BY cluster, namespace
ORDER BY restart_count DESCGasto em spot e em on-demand, com a fatia de cada um na conta:
WITH spend AS (
SELECT capacity_type,
count(*) AS nodes,
sum(cpu_cores) AS cpu_cores,
sum(hourly_cost_usd) * 730 AS monthly_cost_usd
FROM nodes
GROUP BY capacity_type
)
SELECT capacity_type, nodes, cpu_cores, monthly_cost_usd,
monthly_cost_usd / sum(monthly_cost_usd) OVER () AS share
FROM spend
ORDER BY monthly_cost_usd DESCOs erros da última hora por serviço, cruzados com os pods que os escreveram:
SELECT l.service,
p.namespace,
count(*) AS errors,
count(DISTINCT p.name) AS pods,
max(p.restarts) AS max_restarts,
max(l.ts) AS last_error
FROM logs l
JOIN pods p ON p.name = l.pod AND p.node = l.node
WHERE l.severity IN ('ERROR', 'FATAL')
AND l.ts > now() - INTERVAL '1 hour'
GROUP BY l.service, p.namespace
ORDER BY errors DESCLatência p99 por rota:
SELECT service,
http_method,
http_route,
count(*) AS requests,
approx_percentile_cont(0.99) WITHIN GROUP (ORDER BY duration_ms) AS p99_ms,
avg(CASE WHEN http_status_code >= 500 THEN 1.0 ELSE 0.0 END) AS error_rate
FROM spans
WHERE http_route IS NOT NULL
AND start_ts > now() - INTERVAL '1 hour'
GROUP BY service, http_method, http_route
ORDER BY p99_ms DESC
LIMIT 15A CPU vinda do promql() contra os requests dos pods:
WITH usage AS (
SELECT namespace, pod, avg(value) AS cpu_used
FROM promql('sum by (namespace, pod) (rate(container_cpu_usage_seconds_total{container!=""}[5m]))', '6h')
GROUP BY namespace, pod
)
SELECT p.namespace,
count(*) AS pods,
sum(p.cpu_request) AS cpu_request,
sum(u.cpu_used) AS cpu_used,
sum(u.cpu_used) / sum(p.cpu_request) AS utilization
FROM usage u
JOIN pods p ON p.namespace = u.namespace AND p.name = u.pod
GROUP BY p.namespace
ORDER BY utilizationAs mudanças no Orbit por autor, pela trilha de auditoria:
SELECT actor, action, count(*) AS changes, max(time) AS last_change
FROM audit_events
WHERE outcome = 'success'
AND action NOT LIKE 'auth.%'
AND time > now() - INTERVAL '7 days'
GROUP BY actor, action
ORDER BY changes DESCA página tem mais seis: os namespaces mais caros, as requisições por segundo por serviço, os workloads reservando CPU ociosa, a economia contra o gasto, os contêineres que não estão prontos e os eventos de Warning por motivo.
Dados de demonstração
Com o NEXT_PUBLIC_DEMO_MODE ligado, os exemplos respondem com o parque de demonstração e a
telemetria dele, calculados do jeito que o engine os calcularia, então uma linha bate com a página
do Deck que mostra a mesma coisa. A trilha de auditoria nunca é dado de demonstração: o exemplo
dela vai para o orbit-api quando há um conectado. Qualquer outra consulta, o plano, as consultas
salvas e o Nocturne precisam de um Orbit conectado, e a página avisa.