Pular para o conteúdo

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, WITH e EXPLAIN rodam; CREATE, COPY, INSERT, SET e 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: logs com logs, traces e spans com apm, recommendations e namespace_costs com finops (veja docs/features.md).
  • Toda coluna tem um de seis tipos: string, int, float, bool, timestamp e json. Um timestamp vem em UTC, no formato RFC 3339 com milissegundos; um valor json é 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 json abre 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, para IN ({{name}})). Uma cláusula entre [[ ]] sai enquanto os filtros dela estiverem vazios, então WHERE 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}}, ou IN ({{country}}) para vários valores), o filtro lista os valores dessa coluna na tabela dela, lidos com SELECT 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 de databases.query e 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 tem dashboards.write ainda 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.

TabelaPermissãoO que é uma linha
clustersestate.readUm cluster, com a capacidade e a conta dele
nodesestate.readUm node: o que ele tem, o que usa e quanto custa
namespacesestate.readUm namespace
podsestate.readUm pod, com o dono, o node, os reinícios, os requests, os limits e o uso
containersestate.readUm contêiner de um pod, com o estado e o motivo da última parada
workloadsestate.readUm Deployment, StatefulSet, DaemonSet, CronJob ou Job
eventsestate.readUm evento do Kubernetes
persistent_volumesestate.readUm PersistentVolume e o claim ligado a ele
alertsestate.readUm alerta disparando ou pendente agora
recommendationsestate.readUma mudança recomendada e quanto ela economiza por mês
namespace_costsestate.readA fatia de um namespace na conta do cluster
audit_eventsaudit.readUm registro da trilha de auditoria
logslogs.readUma linha de log armazenada
tracesapm.readUm trace armazenado
spansapm.readUm span armazenado
promql(), promql_instant()telemetry.queryAmostras do engine de métricas

Todas as colunas, com os tipos:

text
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 json

Algumas 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, com ts, value e uma coluna de texto para cada label que a resposta traz. start e end aceitam um timestamp ou um intervalo contado a partir de agora ('1h'); end vale agora por padrão, e step o que der cerca de 240 pontos.
  • promql_instant(query) é uma consulta instantânea: uma linha por série, com os labels como colunas e o value.

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.

sql
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 DESC

Limites

  • 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"):

RotaRequerCorpo e resposta
POST /api/v1/sql/querytelemetry.query{sql, limit, timeoutMs} → {columns, rows, stats}
POST /api/v1/sql/explaintelemetry.query{sql} → {plan}
GET /api/v1/sql/schematelemetry.queryAs tabelas e funções que quem chama pode consultar, com as colunas e os exemplos
GET, POST /api/v1/sql/queriestelemetry.queryAs consultas salvas de quem chama e as compartilhadas com ele; uma nova
GET, PUT, DELETE /api/v1/sql/queries/{id}telemetry.queryUma consulta salva; só o dono a altera
POST /api/v1/sql/generatetelemetry.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.

bash
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/query

Exemplos

A página abre com estes, e cada um roda como está escrito.

Pods reiniciando, por namespace:

sql
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 DESC

Gasto em spot e em on-demand, com a fatia de cada um na conta:

sql
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 DESC

Os erros da última hora por serviço, cruzados com os pods que os escreveram:

sql
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 DESC

Latência p99 por rota:

sql
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 15

A CPU vinda do promql() contra os requests dos pods:

sql
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 utilization

As mudanças no Orbit por autor, pela trilha de auditoria:

sql
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 DESC

A 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.