Recursos
Dashboards
Dashboards no estilo do Grafana sobre PromQL, e painéis no estilo do Kibana sobre os logs
armazenados, guardados pelo orbit-api e desenhados pelo Deck em /deck/dashboards. Cinco vêm
com o produto e são somente leitura; quem tem dashboards.write pode criar outros, editá-los,
copiar os nativos, começar um a partir de um modelo e importar dashboards exportados do
Grafana. O modelo e os limites dele estão no Adendo v0.5 do CONTRACT.md; os painéis de logs,
no Adendo log-dashboards dele.
Dashboards nativos
Vêm embutidos no binário do orbit-api, são os mesmos em toda instalação e ficam somente
leitura para todo mundo: "Salvar como cópia" gera uma versão editável. Os uids deles começam
com orbit-, um prefixo que nenhum dashboard salvo pode usar.
| uid | Título | Lê | Variáveis |
|---|---|---|---|
orbit-k8s-cluster | Kubernetes / Cluster | kube-state-metrics e o cAdvisor do kubelet | nenhuma |
orbit-k8s-workloads | Kubernetes / Workloads | kube-state-metrics e cAdvisor, de um namespace | namespace, pod |
orbit-nodes | Nodes | node-exporter | instance |
orbit-apm-red | APM / Service RED | As span metrics que o engine deriva dos traces (apm.md) | service |
orbit-self | SRE Orbit / Self-monitoring | As métricas que orbit-api, nocturne e orbit-stack expõem | job |
Um painel cuja métrica ninguém envia mostra "Sem dados neste intervalo." em vez de desenhar
qualquer coisa. Os três de Kubernetes e o orbit-self precisam do fluxo de telemetria que o
chart e os manifestos puros instalam (install/helm.md → "Telemetria").
No compose nada faz scrape, então só o orbit-apm-red recebe dados, que vêm da loja de
demonstração.
De onde vêm os números
Toda consulta de painel passa pelo GET /api/v1/query_range do orbit-api, com o cluster
selecionado no Deck e depois de o navegador substituir as variáveis, e o orbit-api entrega
a expressão ao engine em ORBIT_STACK_URL. Isso vale também com dados de demonstração: um
dashboard é sempre PromQL de verdade no engine de verdade, e sem ORBIT_STACK_URL todo
painel é recusado. As variáveis e as sugestões do editor de consultas leem as rotas de label
do engine pelo orbit-api, do mesmo jeito.
Criar e editar
Novo dashboard na lista, ou Salvar como cópia em qualquer dashboard que você consiga abrir. No modo de edição:
- Adicionar → Visualização acrescenta um painel e abre o editor de painel; Adicionar → Linha acrescenta uma linha de largura total, que agrupa os painéis abaixo dela e pode abrir recolhida.
- O editor de painel aceita até 8 consultas PromQL, de
AaH, cada uma com um template de legenda em que{{pod}}imprime esse label da série (vazio, a série leva o nome dos seus labels).Ctrl + Enterexecuta as consultas, eCtrl + Spacesugere métricas, funções, labels, valores e variáveis na posição do cursor. - Fonte de dados, acima das consultas, é PromQL ou Logs: um painel de logs lê os logs armazenados no lugar do PromQL (veja "Painéis de logs" abaixo).
- Visualização é uma destas: série temporal, número, medidor, barras, pizza, tabela, lista de logs e texto. As opções padrão são a unidade, as casas decimais, um mínimo e um máximo, e até 10 limites coloridos como OK, alerta ou crítico; uma série temporal pode empilhar as séries e mostrar a legenda como lista, como tabela de média, máximo e último, ou não mostrar legenda nenhuma. Um painel de texto é Markdown, e o HTML dentro dele aparece como texto, assim como uma imagem, pelo seu texto alternativo.
- Os painéis ficam numa grade de 24 colunas: arraste um pela barra de título, redimensione pelo canto inferior direito, ou dê foco a ele e use as setas (Shift com as setas redimensiona, Enter edita). Mover painéis exige uma janela larga; numa janela estreita, os painéis continuam abrindo no editor.
- Aplicar mantém as alterações de um painel no dashboard; Salvar grava o dashboard como uma nova versão; Descartar volta à última versão salva.
Todo salvamento leva a versão de onde partiu. Se outra pessoa salvou nesse meio-tempo, o
orbit-api recusa o salvamento com 409 conflict e informa quem salvou qual versão, e o
Deck oferece três saídas: Sobrescrever com a sua, Salvar como cópia, ou
Carregar a dele e descartar as suas alterações. Nada é sobrescrito em silêncio, nunca.
Configurações guarda o título, a descrição, as tags, o intervalo de tempo padrão (de 15 minutos a 30 dias), a atualização automática (desligada, 10 s, 30 s, 1 min, 5 min ou a escolha de quem vê), as variáveis e o modelo JSON.
Variáveis
Uma variável transforma parte de todas as consultas em um seletor no topo do dashboard.
| Tipo | De onde vêm os valores | Exemplo |
|---|---|---|
query | Do engine: label_values(metric{selector}, label) ou label_values(label) | label_values(kube_pod_info{namespace=~"$namespace"}, pod) |
custom | Uma lista separada por vírgulas que você digita | prod-use1, prod-euc1 |
interval | Uma lista de durações separadas por vírgulas | 1m, 5m, 1h |
Use uma variável numa expressão como $name, ${name} ou [[name]]. Uma variável pode ter
vários valores e pode incluir Todos: vários valores chegam à consulta como a|b (cada
valor escapado para regex) e Todos chega como .*, então compare com =~, por exemplo
{namespace=~"$namespace"}. Uma variável cuja consulta cita outra variável é resolvida de
novo quando essa outra muda.
Duas variáveis nativas, escritas do jeito do Grafana: $__interval é o step do painel, e
$__rate_interval é o step mais um scrape de 15 segundos, nunca abaixo de 60 s, que é a
janela de que um rate() precisa para sempre conter pelo menos quatro amostras. O próprio
step é escolhido para dar cerca de vinte pontos por coluna da grade e nunca fica abaixo de
15 s. A partir de 7 dias, a grade termina num múltiplo do step, como a do Grafana: quem abre
o painel dentro do mesmo step faz ao engine a mesma pergunta, e o último ponto pode estar até
um step atrasado. Outras variáveis nativas do Grafana, como $__range, não têm suporte.
O endereço da página carrega a seleção, var-namespace=shop,payments, e o intervalo de
tempo, range=6h (ou from-to em segundos de epoch), então um link copiado abre naquilo
que quem o enviou estava vendo.
Painéis de logs
Um painel pode ler os logs armazenados no lugar do PromQL: mude a Fonte de dados, acima das
consultas, para Logs. A consulta dele é a linguagem do explorador de Logs, com as mesmas
chaves, os mesmos termos e o mesmo significado (logs.md → "A linguagem de
consulta"), sobre o intervalo de tempo do dashboard.
| Visualização | Desenha |
|---|---|
| Série temporal | As linhas que atendem à consulta ao longo do tempo, em barras empilhadas ou linhas, divididas por um campo: uma série por valor do topo, o resto somado em Outros, as linhas sem o campo em Sem valor |
| Barras, pizza, tabela | Os valores mais frequentes da divisão na janela inteira, com as linhas e a parcela de cada um, depois Outros e Sem valor |
| Número, medidor | As linhas que atendem à consulta, ou, com Parcela de, a parcela delas que uma subconsulta pega, em porcentagem (erros sobre todas as linhas), com limites e um sparkline |
| Lista de logs | As 100 linhas mais novas que atendem à consulta, nas colunas escolhidas; uma linha abre o log no explorador de Logs |
A divisão é um campo: o nível, service (o service.name do recurso), namespace
(k8s.namespace.name), pod, container, node, o padrão da mensagem ou qualquer atributo
como @name (o da própria linha, senão o do recurso). O padrão da mensagem é o msg ou o
message do JSON quando a linha é um objeto JSON, senão a própria linha: as primeiras 40
palavras, e toda palavra que tem um dígito ou um ID hexadecimal de 16 ou mais vira *, então
linhas que diferem só em IDs, contagens ou durações compartilham um padrão. Dividida por ele,
uma tabela mostra as mensagens de erro mais frequentes. O topo vai de 1 a 50 valores, 10 por
padrão; um gráfico pinta os 8 primeiros e junta o resto em Outros.
O filtro do dashboard
Um dashboard com painel de logs mostra um filtro de logs acima das variáveis: termos na mesma
linguagem, cada um um chip que um clique remove ou inverte. A consulta de todo painel de logs
inclui o filtro, além da própria. Um clique num valor acrescenta o termo dele ao filtro, o
"filtrar pelo valor" do Kibana: uma linha de um painel de valores mais frequentes, a legenda de
uma fatia, uma série abaixo de uma contagem ao longo do tempo. O sinal de menos ao lado exclui
o valor ("excluir o valor"), e o mesmo clique de novo tira o termo. Outros e Sem valor não
filtram nada; um padrão de mensagem filtra pela sua maior sequência de palavras fixas, como
frase. O filtro fica no endereço, lq=, ao lado do intervalo de tempo e dos seletores, então um
link copiado abre naquilo que quem o enviou estava vendo.
Variáveis sobre logs
Uma variável do tipo logs lista os valores de um campo de log: a consulta dela é o campo
(service, namespace, pod, container, node, severity ou @name), e as opções são os
50 valores com mais linhas na janela. Use como service:$service: com Todos, o termo sai da
consulta, e um valor casa exatamente. A linguagem de logs não tem OR, então uma variável logs
aceita um valor ou Todos, e uma variável de outro tipo com vários valores entrega o primeiro a
uma consulta de logs. Um painel PromQL lê uma variável logs como qualquer outra
({service=~"$service"}).
O que um painel de logs conta
As contagens são das linhas que o engine armazenou. Quando o controle de ingestão descartou
linhas que chegaram na janela (ingestion.md), o painel diz quantas, pelos
contadores do engine sobre o que chegou: os dos níveis da consulta quando ela nomeia níveis,
senão os do único serviço que ela nomeia, quando nomeia exatamente um, senão os de todas as
linhas. Os contadores guardam as últimas 24 horas e começam junto com o processo do engine,
então uma janela mais antiga não diz nada.
Toda leitura tem limites. Uma divisão nomeia no máximo 50 valores, e uma contagem ao longo do tempo, no máximo 240 buckets (o painel pede cerca de um a cada 20 pixels). Uma leitura para em 3 s numa janela de até uma hora, em 6 s até um dia e em 10 s além disso, ou depois de ler 4, 8 ou 16 GiB de dados; uma leitura interrompida diz Parcial e conta o que leu, começando pelos dados mais novos. Uma thread de varredura guarda 1.024 valores distintos da divisão; além disso o painel avisa, os valores do topo estão entre os primeiros que ela encontrou, e o resto conta em Outros.
Visão geral de logs
Modelos → Visão geral de logs, na lista, cria um dashboard inicial no seu idioma, salvo como
seu para você mudar: linhas, erros, a parcela de erros e os avisos; erros e avisos ao longo do
tempo por serviço; a divisão por nível; o volume de logs por namespace; as mensagens de erro
mais frequentes; e os erros recentes. Os seletores service e namespace dele restringem
todos os painéis.
Um build de demonstração desenha os painéis de logs a partir das próprias linhas do parque de demonstração, as mesmas que a página Logs dele lê, no relógio da demonstração.
O modelo JSON
Configurações → Modelo JSON mostra o dashboard inteiro como o orbit-api o guarda, para
editar e aplicar, copiar ou baixar; Exportar JSON na lista baixa a mesma coisa. O
formato:
{uid, title, description, tags[], time: {from: "now-6h", to: "now"}, refresh: "30s",
variables: [{name, label, type: "query" | "custom" | "interval" | "logs", query, options[],
multi, includeAll, current[]}],
panels: [{id, type: "timeseries" | "stat" | "gauge" | "bar" | "pie" | "table" | "logs"
| "text" | "row",
title, description, gridPos: {x, y, w, h} (24 columns),
targets: [{refId, expr, legend}], unit, decimals, min, max,
thresholds: [{value, color: "ok" | "warn" | "crit"}], stack, legend, text,
collapsed, logs: {query, by, top, ratio, columns[], style}}]}O orbit-api valida todo salvamento e recusa uma violação com 400 invalid_request,
nomeando o campo (panels[2]: gridPos: x from 0, w from 1, x + w at most 24). Um campo
desconhecido também é recusado, então uma opção com erro de digitação nunca some em
silêncio.
| Campo | Aceito |
|---|---|
uid | De 1 a 40 letras, dígitos, - ou _, começando com letra ou dígito; vazio na criação, recebe 12 caracteres gerados |
title | De 1 a 120 caracteres; description até 1.000 |
tags | Até 16, cada uma com até 32 caracteres |
time.from | now-15m, now-1h, now-6h, now-24h, now-7d ou now-30d; time.to é now |
refresh | Vazio (a escolha de quem vê), off, 10s, 30s, 1m ou 5m |
variables | Até 20; um nome é uma letra ou _ seguida de letras, dígitos ou _, com até 32 caracteres, sem começar com __; até 500 opções |
panels | Até 100, cada id único e de 1 a 1.000.000 |
gridPos | x a partir de 0, w a partir de 1, x + w no máximo 24; h de 1 a 60; y de 0 a 10.000 |
targets | Até 8 por painel; refId é uma letra maiúscula, única; expr com até 2.000 caracteres |
unit | Vazio, ou um dos ids do Grafana none, short, percent, percentunit, s, ms, bytes, Bps, reqps, ops |
decimals, min, max | decimals de 0 a 6; min abaixo de max |
thresholds | Até 10, com cor ok, warn ou crit |
legend | list, table ou hidden |
text | Markdown, até 16.000 caracteres |
logs | query e ratio com até 2.000 caracteres cada; by um de service, namespace, pod, container, node, severity, message ou @ e o nome de um atributo; top de 1 a 50; até 12 columns entre severity, service, namespace, pod, container, node, message, trace_id, span_id ou @name; style bars ou lines. Um painel logs precisa dele; um painel de texto ou uma linha o recusa, e um painel com ele não tem targets |
Uma variável logs | A query dela é uma de service, namespace, pod, container, node, severity ou @name, e multi é falso |
Uma linha fica fixa em x 0, w 24, h 1 e não leva consultas; collapsed recolhe os painéis
abaixo dela quando o dashboard abre. O current de uma variável guarda $__all quando
Todos está escolhido. Os campos opcionais de painel ficam de fora quando não estão
definidos, então dois clientes que salvam a mesma intenção gravam os mesmos bytes.
Importar do Grafana
Importar na lista recebe um modelo JSON, colado ou de um arquivo, seja o deste produto, seja o modelo JSON de um dashboard do Grafana. Um modelo do Grafana é convertido no navegador antes de qualquer coisa ser enviada:
| Grafana | Vira |
|---|---|
Painéis timeseries, graph | timeseries |
stat, singlestat | stat |
gauge | gauge |
bargauge, barchart | bar |
piechart | pie |
table, text, row | O mesmo tipo; uma linha recolhida mantém os painéis e continua recolhida |
expr e legendFormat de cada target | Uma consulta e a legenda dela, até 8 por painel |
| A unidade, as casas decimais, o mínimo e o máximo | Mantidos; a unidade, só quando é um dos ids acima |
| Os steps de threshold | Vermelho vira crítico, laranja e amarelo viram alerta, qualquer outra cor vira OK |
Variáveis query, custom e interval | Os mesmos tipos, com a definição como consulta |
| O intervalo de tempo e a atualização automática | Mantidos quando estão entre os valores acima |
Ficam de fora: as fontes de dados (toda consulta roda neste engine), as transformações, os overrides, os links, as anotações, os tipos de painel fora da lista, as variáveis de outros tipos e os painéis além dos 100 primeiros. O diálogo informa quantos painéis deixou de fora antes de você importar. Um dashboard do Grafana sempre ganha um uid novo; um modelo deste produto mantém o seu, e, quando esse uid já existe, o diálogo oferece Importar como cópia.
A API só aceita o modelo deste produto: POST /api/v1/dashboards recusa um modelo do
Grafana, porque os campos dele são desconhecidos para o schema acima. Converta no Deck ou
escreva o modelo você mesmo.
Permissões
| Para | Precisa de |
|---|---|
| Listar e abrir dashboards | dashboards.read |
| Desenhar os painéis e resolver as variáveis | telemetry.query também |
Desenhar os painéis de logs e listar os valores de uma variável logs | logs.read também; sem ele, cada painel de logs avisa e não lê nada |
| Criar, salvar, copiar, importar e excluir | dashboards.write |
| Alterar um dashboard nativo | Ninguém: salve uma cópia |
O papel embutido viewer lê e desenha todos os dashboards; editor e admin também
escrevem. Não existe lista de acesso por dashboard: quem tem dashboards.write pode editar
ou excluir qualquer dashboard salvo, e a trilha de auditoria registra isso com um resumo do
antes e do depois (dashboard.create, dashboard.update, dashboard.delete; veja
audit.md).
A API
Toda rota exige uma sessão; as permissões são as da tabela acima. Com a SESSION de um
editor (identity.md → "Entrar pelo shell"), copie o dashboard nativo
Nodes com um título novo e depois apague a cópia:
curl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" \ localhost:8080/api/v1/dashboards/orbit-nodes \ | python3 -c 'import json,sys; d=json.load(sys.stdin)["dashboard"]; d["uid"]=""; d["title"]="Nodes (team copy)"; print(json.dumps({"dashboard": d}))' > copy.jsoncurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -H 'content-type: application/json' \ --data @copy.json localhost:8080/api/v1/dashboardscurl -fsS -H "Authorization: Bearer $ORBIT_AUTH_TOKEN" -H "X-Orbit-Session: $SESSION" -X DELETE \ localhost:8080/api/v1/dashboards/NEW_UIDUm painel de logs lê GET /api/v1/logs/aggregate e GET /api/v1/logs/query sob logs.read
(logs.md → "Pela API").
NEW_UID é o dashboard.uid da resposta à chamada de criação. PUT recebe
{dashboard, version} com o meta.version que você leu; quando a versão guardada mudou
nesse meio-tempo, ele responde 409 com version, updatedBy e updatedAt da versão
guardada ao lado de error. Um corpo tem no máximo 1 MiB. A lista completa de rotas e
formatos está em api.md.
Onde eles ficam guardados
Um documento JSON por dashboard salvo, ORBIT_DATA_DIR/dashboards/<uid>.json, com o modelo,
a versão dele, quem o criou e quem o salvou por último, e quando. Eles dividem o diretório de
dados, e portanto os backups e o teto de réplica única, com os usuários e a trilha de
auditoria (identity.md → "Onde o estado fica").
Para onde ir em seguida
- As span metrics por trás do
orbit-apm-red, e como enviar traces:apm.md. - O PromQL que o engine responde, função por função:
orbit-stack.md. - Os papéis, e como conceder
dashboards.writesem o resto doeditor:identity.md.