Pular para o conteúdo

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.

uidTítuloLêVariáveis
orbit-k8s-clusterKubernetes / Clusterkube-state-metrics e o cAdvisor do kubeletnenhuma
orbit-k8s-workloadsKubernetes / Workloadskube-state-metrics e cAdvisor, de um namespacenamespace, pod
orbit-nodesNodesnode-exporterinstance
orbit-apm-redAPM / Service REDAs span metrics que o engine deriva dos traces (apm.md)service
orbit-selfSRE Orbit / Self-monitoringAs métricas que orbit-api, nocturne e orbit-stack expõemjob

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 A a H, 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 + Enter executa as consultas, e Ctrl + Space sugere 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.

TipoDe onde vêm os valoresExemplo
queryDo engine: label_values(metric{selector}, label) ou label_values(label)label_values(kube_pod_info{namespace=~"$namespace"}, pod)
customUma lista separada por vírgulas que você digitaprod-use1, prod-euc1
intervalUma lista de durações separadas por vírgulas1m, 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çãoDesenha
Série temporalAs 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, tabelaOs 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, medidorAs 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 logsAs 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:

text
{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.

CampoAceito
uidDe 1 a 40 letras, dígitos, - ou _, começando com letra ou dígito; vazio na criação, recebe 12 caracteres gerados
titleDe 1 a 120 caracteres; description até 1.000
tagsAté 16, cada uma com até 32 caracteres
time.fromnow-15m, now-1h, now-6h, now-24h, now-7d ou now-30d; time.to é now
refreshVazio (a escolha de quem vê), off, 10s, 30s, 1m ou 5m
variablesAté 20; um nome é uma letra ou _ seguida de letras, dígitos ou _, com até 32 caracteres, sem começar com __; até 500 opções
panelsAté 100, cada id único e de 1 a 1.000.000
gridPosx 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
targetsAté 8 por painel; refId é uma letra maiúscula, única; expr com até 2.000 caracteres
unitVazio, ou um dos ids do Grafana none, short, percent, percentunit, s, ms, bytes, Bps, reqps, ops
decimals, min, maxdecimals de 0 a 6; min abaixo de max
thresholdsAté 10, com cor ok, warn ou crit
legendlist, table ou hidden
textMarkdown, até 16.000 caracteres
logsquery 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 logsA 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:

GrafanaVira
Painéis timeseries, graphtimeseries
stat, singlestatstat
gaugegauge
bargauge, barchartbar
piechartpie
table, text, rowO mesmo tipo; uma linha recolhida mantém os painéis e continua recolhida
expr e legendFormat de cada targetUma consulta e a legenda dela, até 8 por painel
A unidade, as casas decimais, o mínimo e o máximoMantidos; a unidade, só quando é um dos ids acima
Os steps de thresholdVermelho vira crítico, laranja e amarelo viram alerta, qualquer outra cor vira OK
Variáveis query, custom e intervalOs mesmos tipos, com a definição como consulta
O intervalo de tempo e a atualização automáticaMantidos 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

ParaPrecisa de
Listar e abrir dashboardsdashboards.read
Desenhar os painéis e resolver as variáveistelemetry.query também
Desenhar os painéis de logs e listar os valores de uma variável logslogs.read também; sem ele, cada painel de logs avisa e não lê nada
Criar, salvar, copiar, importar e excluirdashboards.write
Alterar um dashboard nativoNingué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:

bash
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_UID

Um 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.write sem o resto do editor: identity.md.