Referência
Referência da API
Cada rota que este produto serve, seu formato de requisição e de resposta, o conjunto
fechado de códigos de erro, os tipos de frame SSE e todos os limites rígidos. Fonte de
verdade: CONTRACT.md. Onde um formato não é detalhado campo a campo no
próprio CONTRACT.md, ele vem de apps/web/src/lib/demo-estate.ts, cujo comentário de
cabeçalho afirma que ele é "shaped exactly like the matching orbit-api response in
CONTRACT.md" (tem o formato exato da resposta
correspondente do orbit-api). Cada seção abaixo indica a sua procedência, para que você consiga
distinguir um campo garantido pelo contrato de um campo documentado por exemplo.
Convenções
- Apenas JSON. Todo corpo de requisição e de resposta é JSON; um corpo de requisição
que não seja JSON recebe
415/unsupported_media_type. - Erros têm um único formato, em todo lugar:
{"error":{"code":"...","message":"..."}}, com um status HTTP que sempre corresponde ao código. Veja "Códigos de erro" abaixo. - Autenticação:
Authorization: Bearer <token>, o bearer do serviço, em todas as rotas excetoGET /healthzeGET /readyz. Noorbit-api, o usuário logado vai por cima dele, emX-Orbit-Session, que toda rota exige, menos a curta lista pública em "Identidade" abaixo: sessão ausente ou inválida é401 unauthorized, e um papel sem a permissão da rota,403 forbidden. Vejasecurity.mdeidentity.md. - Do navegador, todo caminho abaixo é chamado contra a própria origem do
web(por exemplohttps://your-host/api/v1/clusters), e o servidor dowebo encaminha aoorbit-apisem alteração, anexando o bearer e copiando o cookieorbit_sessionpara oX-Orbit-Session. Não existe um hostname público separado para oorbit-api. Se você estiver chamando um serviço diretamente para depuração (por exemplo nas portas de debug que odocker-compose.ymlpublica), anexe você mesmo o bearer; vejainstall/docker-compose.md. - Compressão: pelo
web, uma resposta JSON de 1 KiB ou mais trafega comContent-Encoding: gzipquando a requisição aceita. Um stream SSE nunca, e ocurlsem--compressedrecebe o mesmo JSON sem compressão. O próprioorbit-apiresponde sem compressão. - Logs, não respostas: toda requisição gera uma linha JSON do
slogno stdout (método, path, status, duração), independentemente do desfecho. Vejaoperations.md.
Rotas que todo serviço de backend expõe
| Rota | Devolve | Autenticação? | Observações |
|---|---|---|---|
GET /healthz | 200 {"status":"ok"} | Não (sempre isenta) | Liveness. Nunca toca uma dependência, então um nocturne lento não pode derrubar o liveness do orbit-api. |
GET /readyz | 200 quando as dependências respondem, 503 caso contrário | Não (sempre isenta) | Readiness. O orbit-api checa sua fonte e informa o nocturne no corpo ("nocturne": "ok" ou "unavailable: …") sem falhar por ele: um assistente opcional fora do ar não pode tirar a API do Service. O nocturne checa a alcançabilidade do provedor (em cache, nunca a cada requisição). O readiness precisa ser capaz de falhar (Adendo v0.2). |
GET /metrics | Exposição Prometheus | Não se aplica (listener separado) | Ligado a ORBIT_METRICS_ADDR / NOCTURNE_METRICS_ADDR (default :9090), não à porta da API. Em gzip quando o scraper envia Accept-Encoding: gzip. Não alcançável pelo proxy do web; não coberto pela lista de isenções de autenticação porque não está no listener ao qual essa lista se aplica. Veja security.md. |
GET /api/v1/version | {"version","commit","builtAt","go"} | Sim | Exige credencial válida como qualquer outra rota do listener da API; no orbit-api, também uma sessão. A chave go foi mantida por compatibilidade e nomeia o toolchain do Rust. |
orbit-api
Caminho base /api/v1. Toda rota abaixo exige o bearer e, a menos que diga "pública",
uma sessão cujo papel tenha a permissão indicada na linha da rota (o identity.md traz a
lista fechada). Toda rota está sujeita ao timeout global de 20s e ao limite de corpo de
1 MiB, salvo quando um limite mais estreito for informado.
| Rota | Permissão | Devolve |
|---|---|---|
GET /clusters | estate.read | Cluster[] |
GET /clusters/{id} | estate.read | Cluster |
GET /clusters/{id}/nodes | estate.read | Node[] |
GET /clusters/{id}/workloads | estate.read | Workload[]; parâmetros: ?namespace=&kind=&q= |
GET /clusters/{id}/events | estate.read | Event[]; parâmetros: ?limit= (máximo 500, veja Limites) |
GET /clusters/{id}/components | telemetry.query e estate.read | Component[]: os controladores do próprio SRE Orbit, {component, kind, namespace, name, image, version, running?, ready, desired, nodes?, status, parked?, attention, restarts, memory:{used, request}, problem?:{key, value, retries?}, disk?:{usedBytes, capacityBytes, fullAt?}}; restarts e problem cobrem 24 h, e problem conta nos pods da própria linha (veja o operations.md) |
GET /clusters/{id}/alerts | estate.read | Alert[], com os campos de reconhecimento descritos abaixo |
GET /clusters/{id}/changes | estate.read | {since, changes: [{at, last?, kind, namespace, workload?, object, by?, user?, reason?, message?, changes?, count?, revision?, severity?, alertId?, outcome?, objects?, approx?, key}], counts, cut, dropped, deckHidden}, a linha do tempo de mudanças, da mais nova para a mais antiga, no máximo 500 linhas, com os avisos mais antigos sendo os primeiros a ficar de fora; counts é cada tipo antes desse corte, cut as linhas que ele deixou de fora, dropped o que dias cheios da janela nunca guardaram para o namespace, approx uma hora dada por um ciclo, objects quantos objetos uma sequência de avisos cobre, deckHidden verdadeiro sem audit.read; parâmetros: ?namespace= (obrigatório), &workload=, &from=&to= (Unix ms, por padrão as últimas 24 h). kind é rollout, scale, warning, alert ou deck; by é o gerenciador de campos ou HPA, user o usuário do Deck de uma linha deck; as linhas deck exigem audit.read. since é quando o registro começou no cluster, 0 antes disso. Cache-Control: no-store. Veja audit.md → "A linha do tempo de mudanças" |
GET /clusters/{id}/finops | estate.read | FinOps |
GET /clusters/{id}/recommendations | estate.read | Recommendation[] |
GET /query_range | telemetry.query | QueryResult; parâmetros: ?cluster=&expr=&from=&to=&step= |
POST /contact | pública | 202 {"status":"accepted","leadId":"lead_<16 hex>"}, respondido só depois que o lead fica gravado em ORBIT_DATA_DIR/leads (uma falha na gravação é 500, e nada é aceito) e, em seguida, opcionalmente enviado por POST a ORBIT_CONTACT_WEBHOOK_URL em segundo plano (Adendo v0.7), para captura de lead comercial. Campos do corpo: name (obrigatório), email (obrigatório, um endereço interpretável), company, message (opcional, ≤4.000 caracteres), clusters (um de 1-5 6-20 21-100 100+), series (um de lt1m 1m-10m 10m-100m gt100m), locale, source. Campos desconhecidos são recusados com 400. A resposta nunca ecoa o payload, e um honeypot acionado recebe a mesma resposta que um lead real. |
GET /leads | users.manage | {leads: [{id, ts, name, email, company, clusters, series, message, locale, source, ip}]}, do mais novo para o mais antigo; ?format=csv baixa o mesmo conteúdo como planilha, neutralizando as células que começam com um caractere de fórmula |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/logs | logs.read | text/plain, ou text/event-stream com ?follow=1; parâmetros: ?pod=&container=&tailLines=&previous=&follow= |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/events | estate.read | Event[]; parâmetros: ?limit= (máximo 500) |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/replicasets | estate.read | {replicaSets:[{name, createdAt, version, image?, current, backAt?, ran?}]}, os ReplicaSets guardados de um Deployment, lidos do cache do orbit-api, do mais antigo ao mais novo, sem switch de recurso: version é a versão que os pods dele rodam quando os spans não trazem service.version (a tag da imagem do contêiner da aplicação, com o hash do pod template ao lado quando a tag se repete, senão o hash), image é a imagem desse contêiner quando ele é identificado, e current marca a revisão mais alta. Quando o atual é mais antigo que outro, backAt é o momento em que o Deployment voltou para ele (o último span de um mais novo que rodou, senão a condição Progressing) e cada mais novo diz se rodou, em ran. Qualquer outro tipo responde uma lista vazia |
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/scale | workloads.write | WriteResult; corpo {replicas, dryRun, resourceVersion?} |
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/resources | workloads.write | WriteResult; corpo {container, requests:{cpu,memory}, limits:{cpu,memory}, dryRun, resourceVersion?} |
GET /clusters/{id}/workloads/{ns}/Deployment/{name}/revisions | estate.read | {revisions:[{revision, name, createdAt, images, changeCause, replicas, current}], rollout:{outcome, desired, updated, ready, available}}, da mais nova para a mais antiga, lido do API server; outcome é progressing, completed ou failed (ProgressDeadlineExceeded), do jeito que o kubectl rollout status o lê |
GET /clusters/{id}/workloads/{ns}/Deployment/{name}/releases | apm.read e estate.read | O placar das releases (apm.md → "Releases de um Deployment"): {services, logs, revisions:[{revision, name, createdAt, images, changeCause, current, rolledOutAt, reapplied, beforeMs, afterMs, services:[{service, before, after, newRoutes, goneRoutes, more4xx}], newErrors, restarts, verdict, worse}]}, da mais nova para a mais antiga. before e after são {requests, errors, server, http4xx, p95Ms} nos beforeMs antes de rolledOutAt (o que rodou a revisão substituída) e nos afterMs depois (o que rodou ela), 30 minutos no máximo cada; http4xx vem nulo onde o engine não contava 4xx no começo da janela; verdict é worse (com worse nomeando errors, latency, 4xx, newErrors, restarts), ok, few, noEntry ou none. newErrors vem nulo quando o papel não tem logs.read, os logs guardados estão desligados ou a leitura falhou. Fica atrás do switch apm, não do rollback |
POST /clusters/{id}/workloads/{ns}/Deployment/{name}/rollback | workloads.write | WriteResult; corpo {toRevision?, dryRun, resourceVersion?}; o kubectl rollout undo: 0 ou ausente é a revisão anterior. A aplicação é um JSON patch que primeiro testa o resourceVersion do dry run e depois troca o template dos pods. São recusados: Deployment pausado, a revisão atual, um template já igual e o namespace do próprio orbit-api. A aplicação exige X-Orbit-Confirmed com o nome do Deployment do jeito que o operador o digitou; sem ele, a resposta é 400 confirmation_required. A resposta ganha changes, uma entrada por campo alterado ({container, field, from, to}, ou {container, field: "env", added, removed, changed}): variáveis de ambiente só pelo nome, um valueFrom pela sua origem, nunca um valor. Depois de um rollback aplicado, o rollout é acompanhado a cada 5 s por até 15 minutos e auditado como workload.rollback.result |
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/restart | workloads.write | WriteResult; corpo {dryRun, resourceVersion?}; o kubectl rollout restart num Deployment, StatefulSet ou DaemonSet: um strategic merge patch do kubectl.kubernetes.io/restartedAt do template dos pods com o instante atual (RFC 3339, UTC) e nada mais, preso ao resourceVersion, para o controlador substituir os pods pela própria estratégia de atualização. O diff é restartedAt: <before> -> <after>. São recusados com 400: CronJob, Deployment pausado e StatefulSet ou DaemonSet com OnDelete (o controlador não trocaria pod nenhum; o kubectl marca assim mesmo). A aplicação exige X-Orbit-Confirmed com o nome do workload do jeito que o operador o digitou; sem ele, a resposta é 400 confirmation_required. Auditado como workload.restart |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/rollout | estate.read | {outcome, desired, updated, ready, available} de um Deployment, StatefulSet ou DaemonSet, lido do API server do jeito que o kubectl rollout status o lê: é o que o Deck consulta depois de um reinício. failed é o ProgressDeadlineExceeded de um Deployment; os outros dois só progridem ou concluem |
POST /clusters/{id}/workloads/{ns}/CronJob/{name}/suspend | workloads.write | WriteResult; corpo {suspend, dryRun, resourceVersion?} |
POST /clusters/{id}/workloads/{ns}/CronJob/{name}/trigger | workloads.write | WriteResult com after.job, o Job copiado do template do CronJob; corpo {dryRun, resourceVersion?} |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/config | config.read | WorkloadConfig: o env e o envFrom de cada container com a origem de cada valor, o status de cada referência, os valores mascarados e quais objetos mudaram depois do início dos pods; auditado |
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/config/reveal | config.read | {name, value, source, object?, key?}; corpo {container, name}; um valor mascarado, auditado sem ele |
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/manifest | config.read | O controller como o API server o guarda, em JSON, sem managedFields e sem a cópia do last-applied, com todo valor que seria de uma credencial mascarado como um diff o mascara ([redacted]); Cache-Control: no-store, auditado como workload.manifest.view; o parque de demonstração responde 400 |
GET /nocturne/sessions | nocturne.use | {sessions: [{id, title, clusterId, turns, createdAt, updatedAt, expiresAt}]}, só as de quem chama, mais recentes primeiro; 403 para uma conta demo |
GET /nocturne/sessions/{id} | nocturne.use | {id, title, clusterId, createdAt, updatedAt, expiresAt, turns}; 404 quando não existe, expirou ou é de outra pessoa |
PUT /nocturne/sessions/{id} | nocturne.use | {id, updatedAt, expiresAt}; corpo {title, clusterId, turns}, no máximo 80 turnos e 256 KiB; guardada por ORBIT_CHAT_RETENTION depois do último save, 30 por usuário |
DELETE /nocturne/sessions/{id} | nocturne.use | 204 |
As rotas do Adendo v0.5 (identidade, auditoria, dashboards, APM, reconhecimentos de alertas) e as rotas de leitura do Nocturne vêm depois dos formatos das entidades, cada uma na sua própria seção.
Node groups não têm endpoint próprio: agrupar é assunto de visualização, feito no
cliente sobre GET /clusters/{id}/nodes.
Formatos das entidades (documentados por exemplo; veja a nota de procedência acima)
Todo timestamp nesta API está em MILISSEGUNDOS desde o epoch, porque é isso que
Date, uPlot e Intl recebem no navegador. Nenhum RFC 3339 cruza esta fronteira, exceto
builtAt em /version e checkedAt em /nocturne/models. As idades são strings já
formatadas do jeito que o kubectl imprime a coluna AGE (312d, 14h, 26m), não
durações a interpretar.
As duas fontes (o parque de demonstração determinístico e a fonte Kubernetes ao vivo) servem exatamente estes formatos, de modo que o Deck não consegue dizer qual delas respondeu.
Cluster {
id, name: string
env: "production" | "staging"
region, version, platformVersion: string // "us-east-1", "1.31", "eks.8"
status: "healthy" | "degraded" | "critical"
nodes, pods, namespaces: number
cpu: { used, capacity: number } // vCPU
memory: { used, capacity: number } // GiB
monthlyCost: number
age: string
}
Node {
name, cluster, nodeGroup, instanceType: string
capacityType: "ON_DEMAND" | "SPOT"
az, kubeletVersion, age: string
pods, maxPods: number
cpu: { used, capacity: number } // vCPU
memory: { used, capacity: number } // GiB
status: "Ready" | "NotReady" | "SchedulingDisabled"
}
Workload {
id: string // "<cluster>/<namespace>/<name>"
cluster, namespace, name: string
kind: "Deployment" | "StatefulSet" | "DaemonSet" | "CronJob"
ready, desired: number
image: string
cpu: { used, request: number } // millicores
memory: { used, request: number } // MiB
restarts: number
status: "running" | "progressing" | "degraded" | "failed"
age: string
}
Event {
id, cluster: string
ts: number // epoch ms
type: "Normal" | "Warning"
reason, message: string
object: string // "pod/checkout-api-6f4b7c-2xk8p"
count: number
}
Alert {
id, cluster: string
severity: "critical" | "warning" | "info"
name, namespace, workload, summary: string
since: number // epoch ms
durationMin: number
runbook: string
state: "firing" | "pending"
team: string // routing label; "" when derived
ack: "open" | "acked" | "silenced"
lastChange: number // epoch ms
signal: "latency"|"cpu"|"memory"|"ingest"|"errors"|"cost"|"spot"
args?: Record<string, string> // the facts the summary was written from
ackedBy?: string, ackedAt?: number // set while acked or silenced
silencedUntil?: number, ackNote?: string // epoch ms; the note, up to 500 characters
}
FinOps {
cluster: string
monthly, forecast, deltaPct: number // deltaPct is a ratio: 0.044 = +4.4%
byNamespace, byNodeGroup: Array<{ key, label: string, monthly, deltaPct: number }>
spot: { coverage, target, savingsMonthly: number } // coverage/target are ratios
waste: { monthly, cpuIdle, memIdle: number, workloads: number }
source: "demo" | "list-price" | "cost-explorer"
}
Recommendation {
id, cluster, namespace, workload: string
kind: "Deployment" | "StatefulSet" | "DaemonSet" | "CronJob" | "PersistentVolume"
action: "rightsize" | "downscale" | "spot" | "hpa" | "storage"
from, to: string // millicores, MiB, GiB or a replica count, per `action`
monthlySavings: number
confidence: "high" | "medium" | "low"
}Duas observações fáceis de errar:
FinOps.sourcediz de onde veio o dinheiro."list-price"significa uma tabela embutida de preços on-demand de us-east-1 multiplicada por 730 horas, não uma fatura; vejaarchitecture.md→ "O que o modo ao vivo lê, e o que ele deriva". Qualquer coisa que apresente esses números deveria dizer de qual dos dois se trata.Recommendation.kinde.actioncarregam dois valores que o parque de demonstração nunca emite:"PersistentVolume"/"storage", para um volume órfão que a fonte ao vivo encontrou. São os valores corretos para um achado real, que um valorDeploymentdescreveria errado. Um cliente que faça um switch exaustivo sobre qualquer uma das duas uniões precisa incluir os dois.
Alert.team é vazio em todo alerta que a fonte ao vivo deriva: essas regras vêm do estado
do cluster, não de um PrometheusRule com labels de roteamento, e inventar um dono aciona
as pessoas erradas.
O workloadRef que o Deck coloca em uma URL é "<namespace>~<name>". Ele é montado no
cliente a partir dos dois campos acima; nenhum endpoint o devolve.
QueryResult, o formato que todo gráfico do site consome
Este é detalhado diretamente no CONTRACT.md: "uPlot/chart friendly."
QueryResult {
series: Array<{ key: string, label: string, points: Array<[number, number]> }>
unit: "ms" | "rps" | "pct" | "usd" | "bytes" | "count" | "ratio"
}Cada ponto é [epoch-ms, value]: milissegundos, onde uma API do Prometheus devolve
segundos; o orbit-api converte. GET /query_range é limitado (veja Limites abaixo), de
modo que um chamador não consiga pedir uma combinação de janela e passo que devolveria um
número ilimitado de pontos.
Parâmetros de GET /query_range
| Parâmetro | Obrigatório | Formato aceito | Default |
|---|---|---|---|
cluster | sim | Um id de cluster vindo de GET /clusters, ≤128 caracteres. Um id desconhecido é 404. | nenhum |
expr | sim | Uma MetricKey (abaixo) ou PromQL bruto. ≤2.000 runes. | nenhum |
from | não | RFC 3339 (2026-03-14T08:26:53Z) ou segundos Unix (1300000000; um valor fracionário é truncado). | to menos 1 hora |
to | não | Os mesmos dois formatos de from. | agora, truncado no segundo |
step | não | Uma duração Go (30s, 5m, 1h) ou segundos puros (300). Arredondado para o segundo. | 60s |
from precisa ser estritamente anterior a to. A janela, o passo e a contagem de pontos
resultante são todos limitados; veja Limites.
expr: as doze chaves de painel, e PromQL ad hoc
Os painéis embutidos do Deck enviam uma de doze MetricKeys fixas
(request_rate_by_cluster, error_rate_by_cluster, cost_daily,
latency_percentiles, request_rate_by_service, error_budget_burn,
ingest_rate, active_series, disk_per_block, cpu_saturation,
query_latency, spot_coverage). As duas fontes respondem às doze com o mesmo unit, de
modo que o eixo de um painel não dependa de quem respondeu. Na fonte live, as quatro chaves de
requisições (request_rate_by_cluster, error_rate_by_cluster, latency_percentiles,
request_rate_by_service) leem as span metrics dos spans de entrada onde nenhuma app exporta
http_*, e error_budget_burn desenha uma linha por SLO de serviço, nenhuma sem SLO
(apm.md).
Qualquer outra coisa é tratada como PromQL bruto para o painel de consulta ad hoc:
- Fonte ao vivo com
ORBIT_STACK_URLdefinida: a expressão vai literalmente para o engine.unité"bytes"quando a expressão nomeia uma métrica*_bytese"count"caso contrário: o engine devolve um número e oorbit-apinão finge saber o que ele significa. Cada série devolvida é identificada pela própria renderização do conjunto de labels feita pelo Prometheus:node_memory_MemFree_bytes{instance="n1"}, ou só o nome da métrica quando esse é o único label. - Parque de demonstração com
ORBIT_STACK_URLdefinida: a expressão também roda no engine real. As doze chaves mantêm os números do próprio parque; qualquer outra coisa é PromQL, que é o que todo painel de dashboard envia. - Sem
ORBIT_STACK_URL, ao vivo ou demonstração:400invalid_request, dizendoad-hoc PromQL needs the live source (ORBIT_DEMO_DATA=false) and ORBIT_STACK_URL(a mensagem é anterior ao caso de demonstração acima; o que ela exige, na prática, é o engine). Não há engine para avaliá-la, e oorbit-apirecusa em vez de desenhar uma linha gerada que pareça uma resposta. - Uma expressão que o engine rejeita (
errorTypebad_dataouexecution) é400invalid_requestcarregando a mensagem do próprio engine. Um engine que deu timeout ou que não está lá (timeout,canceled,unavailableou qualquer outra falha) é502upstream_error. A separação distingue uma consulta ruim, que é culpa de quem chamou, de uma indisponibilidade, que não é.
Uma MetricKey para a qual o parque não tem dados devolve um array series vazio com o
unit correto, nunca uma linha fabricada.
A superfície de detalhe do workload (Adendo v0.4 do CONTRACT.md)
Quatro rotas sob um workload. {kind} é Deployment, StatefulSet,
DaemonSet ou CronJob; {ns} e {name} são os do próprio workload.
Logs. ?tailLines= tem padrão 200 e teto de 5.000; uma resposta sem
streaming carrega no máximo 2 MiB. ?previous=1 lê o contêiner que
terminou, que é aquele por causa do qual um operador abre esta tela.
Sem ?follow=1 o corpo é texto puro. Com ele, o corpo usa o vocabulário SSE que
este contrato já tem: event: token com {"text": "<one line>"} e
event: done por último, com finishReason (stop, shutdown quando um
rollout drenou o pod, error). Não existe um quinto tipo de frame.
O pod e o contêiner são validados contra os pods do próprio workload:
pods/log tem escopo de namespace, e um parâmetro da URL não pode virar um
jeito de ler o contêiner do vizinho. Toda resposta diz o que leu e o que mais
existe, então não há um endpoint separado de inventário:
X-Orbit-Pod: checkout-api-6f4b7c-aaaaa
X-Orbit-Container: app
X-Orbit-Pods: checkout-api-6f4b7c-aaaaa=app|sidecar,checkout-api-6f4b7c-bbbbb=app|sidecarOs eventos são os do workload, não os do namespace: o orbit-api casa o
controlador, os ReplicaSets ou Jobs abaixo dele e os seus pods, porque o
Kubernetes registra uma única história contra os três: a escala contra o
Deployment, a criação do pod contra o ReplicaSet, e o pull da imagem, a falha de
probe e o OOMKill contra o pod. Casar só pelo nome arrastaria junto todo Service
e ConfigMap que compartilhe o nome do workload.
As escritas ficam desligadas a menos que um operador as ligue. Com
ORBIT_WRITE_ENABLED ausente ou false, scale e resources respondem 403
writes_disabled, e o chart também não renderiza ClusterRole de escrita. O
privilégio e a flag são separados, e uma escrita precisa dos dois.
A role concede patch, e apenas patch, em
apps/{deployments,statefulsets,daemonsets} e em deployments/scale e
statefulsets/scale.
O gate do operador fica no web, não no orbit-api. O proxy anexa o
ORBIT_AUTH_TOKEN a tudo que encaminha, então, do lado do orbit-api, todo
chamador que passa pela porta da frente está autenticado. Isso é correto para
leituras e era um buraco para escritas: um curl seco no ingress não levava
credencial nenhuma e mesmo assim escalava um Deployment. Um método que altera
estado em .../scale ou .../resources só é encaminhado quando as duas
condições valem:
X-Orbit-Operator-Tokené igual aoORBIT_DECK_WRITE_TOKENdo servidor web (comparação em tempo constante). O token é gasto nesse salto e nunca é encaminhado aoorbit-api.- A requisição prova ser de mesma origem:
Sec-Fetch-Site: same-originounone, ou umOrigincujo host casa. Nenhum dos dois cabeçalhos presente significa que não é um navegador, e aí só o token decide.
Caso contrário, 401 unauthorized (ausente, errado ou de outro site) ou
403 writes_disabled quando não há token configurado. Em todos os casos, o web
responde sem contatar o orbit-api, de modo que uma escrita recusada não vira um
oráculo sobre quais workloads existem. Leituras nunca passam pelo gate;
outras rotas que alteram estado (contact, o stream do assistente) continuam
funcionando, mas são recusadas de outro site.
O Deck pede o token uma vez por hora e o envia uma única vez para o
POST /api/operator do web, que o confere e responde com um cookie HttpOnly e
SameSite=Strict contendo uma validade e um HMAC com o token como chave, nunca o
próprio token. Nem o armazenamento do navegador nem a URL o guardam. O web só aceita
esse cookie numa escrita da mesma origem; um 401 pede o token de novo.
Toda escrita é uma simulação que quem chama confirma. Envie com
"dryRun": true: o orbit-api faz o patch com DryRun: All, de modo que o
servidor de API, com seus webhooks, seu defaulting e seus LimitRanges, decide
o que aconteceria, e a resposta traz o diff mais a resourceVersion do objeto.
Envie o mesmo corpo com "dryRun": false e essa resourceVersion para
aplicar. Aplicar sem resourceVersion é 400; aplicar sobre um objeto que se
moveu é 409 conflict, que repetir o mesmo corpo não resolve, porque o diff
aprovado por quem chamou não descreve mais o cluster.
WriteResult {
kind, namespace, name: string
container?: string
before, after: Record<string, string> // "replicas", "requests.cpu", "limits.memory"
diff: string[] // ["replicas: 1 -> 3"], sorted, unchanged fields omitted
resourceVersion: string
dryRun, applied: boolean
}Uma quantidade vazia em resources deixa aquele campo como está: limpar um
limit e não tocar nele são operações diferentes. replicas é 0..1000.
Um DaemonSet não tem subrecurso de escala (ele roda um pod por node compatível),
então um scale sobre um deles é 400, e não um controle que o cluster
ignoraria.
Toda tentativa, recusas incluídas, gera uma linha de log estruturada com
principal, console, client_ip e managed_by, um incremento de
orbit_workload_writes_total{verb,kind,outcome,principal}, com outcome em
applied, dry_run, refused, failed, e um evento de auditoria,
workload.scale ou workload.resources (Adendo v0.5). principal é o usuário
logado, cujo nome de usuário já é limitado a [a-z0-9._-] e 32 caracteres, então
um cabeçalho não consegue criar séries temporais sem limite. console é o
X-Orbit-Principal, o label que o web preenche a partir de ORBIT_DECK_OPERATOR;
o orbit-api só acredita nesse cabeçalho numa requisição autenticada com o bearer
compartilhado dele, que apenas o web possui.
No parque de demonstração events é uma lista fixa e plausível; logs é
400 invalid_request citando ORBIT_DEMO_DATA=false; ambas as escritas são
403 writes_disabled. Não há contêiner atrás de uma tabela dentro de um
processo, então o orbit-api recusa em vez de gerar uma linha de log que pareça
uma resposta.
Identidade (Adendo v0.5 do CONTRACT.md)
Login, sessões, usuários e papéis. Os corpos são um único objeto JSON de no máximo 16 KiB,
e um campo desconhecido é 400. A lista pública inteira é GET /healthz, GET /readyz,
GET /auth/state, POST /auth/login, POST /auth/setup e POST /contact; qualquer outra
rota exige uma sessão. O identity.md explica cada regra; aqui fica a
referência.
| Rota | Permissão | Corpo e resposta |
|---|---|---|
GET /auth/state | pública | {setupRequired, demo, demoUsers?: [{username, role}]} |
POST /auth/login | pública | {username, password} → {token, expiresAt, user, role: {id, name}, permissions, session: {id, expiresAt}}. 401 para credenciais erradas, 403 forbidden para conta desativada, 429 + Retry-After enquanto uma espera estiver correndo. Passando pelo web, a rota própria dele define o cookie e remove o token da resposta. |
POST /auth/setup | pública | {setupCode, username, name, password} → 201 {user}, só enquanto não existe usuário nenhum; 401 para código errado, 409 quando já existem usuários |
POST /auth/logout | sessão | 204; a sessão é revogada. Passando pelo web, o cookie é limpo seja qual for a resposta do orbit-api. |
GET /auth/me | sessão | {user, role: {id, name}, permissions, session: {id, expiresAt}} |
POST /auth/password | sessão | {current, next} → 204; um current errado é 400; todas as outras sessões do usuário são encerradas |
GET /users, POST /users | users.manage | {users: [user]}; {username, name, email, role, password} → 201 {user}, 409 para um nome de usuário já em uso |
PATCH /users/{id}, DELETE /users/{id} | users.manage | Qualquer um de name, email, role, disabled, password → {user}; DELETE → 204 |
POST /users/{id}/revoke-sessions | users.manage | {revoked}, o número de sessões encerradas |
GET /roles, POST /roles | users.manage | {roles: [role], permissions: [the closed set]}; {name, description, permissions} → 201 {role} |
PATCH /roles/{id}, DELETE /roles/{id} | users.manage | Qualquer um de name, description, permissions → {role}; DELETE → 204 |
user { id, username, name, email, role, disabled,
createdAt, updatedAt, lastLoginAt /* 0 = never */, lastLoginIp, activeSessions }
role { id, name, description, builtin, permissions[], users /* how many hold it */ }Recusas que protegem a instalação: um papel embutido não pode ser alterado (400); um
papel em uso não pode ser apagado (409); ninguém muda o próprio papel, nem desativa ou
apaga a si mesmo (400); nenhuma mudança pode deixar a instalação sem nenhum usuário
habilitado que tenha users.manage (409). Toda mudança gera um evento de auditoria.
A trilha de auditoria
GET /audit (audit.read) aceita from, to (epoch ms, ambos inclusivos; por padrão,
as últimas 24 h), actor, action, outcome, q, limit (de 1 a 1.000, padrão 100) e
cursor, e responde do mais novo para o mais antigo:
{ events: [{ id, ts, actor: {id, username, role} | null, action,
target: {type, id, name}, outcome: "success" | "denied" | "failure",
ip, userAgent, requestId, details }],
nextCursor, // "" on the last page
total, facets: { action, actor, outcome }, // [{value, count}], whole window
interval, histogram: [{ t, n, denied, failure }] }Com format=csv, a resposta vira um stream com todas as correspondências dos mesmos
filtros, até 100.000 linhas. A linguagem de busca do q, a lista de eventos e a retenção
estão em audit.md.
Dashboards e os metadados do engine
| Rota | Permissão | Corpo e resposta |
|---|---|---|
GET /dashboards?q&tag | dashboards.read | {dashboards: [{uid, title, description, tags, provisioned, createdBy, updatedAt, updatedBy, panels}]}, em que panels é uma contagem; q busca no título, na descrição e nas tags, e tag casa exatamente com uma tag |
GET /dashboards/{uid} | dashboards.read | {dashboard, meta: {version, provisioned, canEdit, canWrite, createdAt, createdBy, updatedAt, updatedBy}} |
POST /dashboards | dashboards.write | {dashboard} → 201, no mesmo formato; sem uid, um novo é gerado, e um uid já em uso ou provisionado é 409 |
PUT /dashboards/{uid} | dashboards.write | {dashboard, version} → o mesmo formato, já na versão seguinte; 409 com version, updatedBy, updatedAt ao lado de error quando a versão gravada mudou; 403 num dashboard provisionado |
DELETE /dashboards/{uid} | dashboards.write | 204; 403 num dashboard provisionado |
GET /labels, GET /label/{name}/values, GET /series, GET /query, GET /status/tsdb | telemetry.query | O corpo Prometheus do próprio engine |
O corpo de um dashboard pode chegar a 1 MiB. O modelo, os conjuntos fechados dele e os
limites estão em dashboards.md. As quatro rotas de metadados repassam
ao engine só match[] (no máximo 20), start, end, limit (padrão 5.000 nas rotas de
labels e de séries), query e time; uma falha vem no envelope do contrato com a
mensagem do engine (bad_data ou execution vira 400 invalid_request, qualquer outra
coisa 502 upstream_error), uma resposta acima de 16 MiB é 502, e a ausência de
ORBIT_STACK_URL é 503 not_ready.
APM
Sete leituras, apm.read, encaminhadas ao engine em ORBIT_STACK_URL com o bearer
dele; o status e o corpo são os do engine. Os tempos de span estão em microssegundos
desde o epoch (startUs, durationUs); todos os outros tempos, em milissegundos desde o
epoch. start e end têm como padrão a última hora e cobrem no máximo 31 dias.
| Rota | Resposta |
|---|---|
GET /traces/{traceId}?start&end | {traceId, startUs, durationUs, services[], spans: [{spanId, parentSpanId, name, service, kind, startUs, durationUs, status: {code, message}, attributes, resource, events: [{name, timeUs, attributes}]}]}; 404 fora da retenção. start e end são opcionais e dizem onde quem chama viu o trace (um vale pelos dois): o engine lê só os segmentos a até uma hora deles, e todos os segmentos quando esses não têm nada do trace |
GET /traces?service&operation&status&minDurationMs&maxDurationMs&attr=k=v&start&end&limit&root&rootKind | {traces: [{traceId, rootService, rootName, startMs, durationMs, spanCount, errorCount, services: [{name, spans, errors}], rootKind}], truncated}; rootKind só com root ou rootKind |
GET /spans?service&name&kind&status&minDurationMs&traceId&attr=k=v&start&end&limit | {spans: [{traceId, spanId, parentSpanId, service, name, kind, status, startNs, endNs, durationMs, attrs, resource}], truncated}, do mais novo para o mais antigo |
GET /apm/services?start&end | {services: [{name, rate, errorRate, p50Ms, p95Ms, p99Ms, requests, errors, operations, resources: {namespace, deployment, pods[]}}]} |
GET /apm/services/{service}/operations?start&end | {operations: [{name, kind, rate, errorRate, p50Ms, p95Ms, p99Ms, requests, errors}]} |
GET /apm/servicemap?start&end | {nodes: [{id, type, rate, errorRate, p95Ms}], edges: [{source, target, rate, errorRate, p95Ms, requests, backgroundRate?}], partial, unpairedSpans}; partial é true quando spans ficaram sem par na janela (unpairedSpans deles), e aí as arestas contam a menos; backgroundRate, parte de rate, são as chamadas de um serviço sem requisição em volta, ausente numa aresta que nenhum span de cliente fez e onde a janela não tem contagem delas |
GET /apm/heatmap?start&end&step&service&operation&status&kind&attr=k=v¬Attr=k=v&source&timeout | {source, start, end, from, step, columns, bounds, cells: [{t, durationBucket, count}], total, partial, ingest: {window, spansSeen, spansKept}}: a duração dos spans ao longo da janela, o heatmap de latência (apm.md) |
traceId tem de 1 a 32 dígitos hexadecimais, completado com zeros à esquerda. kind é
server, client, producer, consumer, internal ou unspecified; o code de um
status é ok, error ou unset; o type de um node do mapa é service, database,
external ou queue. Numa busca, status é error (algum span falhou) ou ok (nenhum
falhou), as durações delimitam o trace inteiro, attr pode se repetir até 8 vezes e cada
um precisa valer num span, num evento ou no recurso, service e operation têm no
máximo 512 bytes, e limit vale 20 por padrão e no máximo 1.000, do mais novo para o mais
antigo, com truncated quando havia mais. root=true mantém os traces raiz, e rootKind
(uma lista de tipos separados por vírgula) mantém aqueles cujo span raiz tem um deles
(apm.md). A leitura de um trace devolve, sob o id dele, as partes
de salto que os spans dele citam em orbit.hop.trace_id. Em /spans, start e end
aceitam frações de milissegundo, limit vale 100 por padrão e no máximo 10.000, e attr
casa com o span, um evento ou o recurso. rate é requisições por segundo ao longo da
janela, e errorRate, uma razão de 0 a 1.
Num heatmap, bounds são os limites superiores das linhas em ms, em ordem crescente: a linha
b guarda as durações em (bounds[b-1], bounds[b]] e a linha bounds.length, as que
passam do último. A coluna i começa em from + i * step; a primeira e a última trazem só o
que cai dentro de [start, end]. cells lista só as que não estão vazias. source é
metrics (todos os spans, pelas métricas de span: os spans de um serviço do kind entry,
servidor e consumidor, o padrão, ou outgoing, cliente e produtor; sem serviço, as chamadas
vindas de user no grafo de serviços) ou traces (os traces armazenados que a busca
encontraria, cada um uma vez pelo início e pela duração como a busca a julga, numa passada
que responde partial quando o timeout a corta). attr e notAttr, ou operation ou
status sem serviço, leem traces; source força um dos dois, e metrics com um filtro
que ele não comporta é 400. step (ms) tem como padrão cerca de 120 colunas e nunca fica
mais fino que 15 s nem que 360 colunas. ingest é o que as regras de ingestão mantiveram nos
últimos 5m, 1h ou 24h do engine, para uma janela que termina a até 5 minutos de agora.
Sem ORBIT_STACK_URL, toda rota de APM
responde 503 not_ready, com dados de demonstração ou não, e um engine que não responde
é 502 upstream_error. O apm.md explica de onde o engine deriva esses
valores.
Reconhecimentos e silenciamentos de alertas
| Rota | Permissão | Corpo | Efeito |
|---|---|---|---|
POST /clusters/{id}/alerts/{alertId}/ack | workloads.write | {note?} | ack: "acked" |
DELETE /clusters/{id}/alerts/{alertId}/ack | workloads.write | nenhum | volta a open quando está reconhecido |
POST /clusters/{id}/alerts/{alertId}/silence | workloads.write | {minutes, note?} | ack: "silenced" até o fim do prazo; minutes é 15, 60, 240 ou 1440 |
DELETE /clusters/{id}/alerts/{alertId}/silence | workloads.write | nenhum | volta a open quando está silenciado |
Cada uma responde com o alerta do jeito que GET /clusters/{id}/alerts passa a mostrá-lo.
Um DELETE sobre um alerta que não está nesse estado é um 200 que não muda nem
registra nada. Um alerta desconhecido é 404; uma duração fora da lista ou uma nota com
mais de 500 caracteres, 400. As regras por trás de cada alerta derivado:
alerts.md.
As rotas de leitura do Nocturne
As ferramentas de cluster do Nocturne leem estas rotas, além das listadas acima. O nocturne as
chama com a sessão do usuário que fez a pergunta, então uma ferramenta lê o que esse
usuário pode ler. Todas são GET; o parque de demonstração responde pods, nodes e
events a partir das próprias tabelas e recusa as demais nominalmente.
| Rota | Permissão | Parâmetros |
|---|---|---|
/clusters/{id}/nocturne/pods | estate.read | ?namespace=&kind=&workload=&node=&unhealthy=; sem config.read, todo valor de env aparece como [redacted] |
/clusters/{id}/nocturne/nodes | estate.read | nenhum |
/clusters/{id}/nocturne/events | estate.read | ?namespace=&kind=&name=&type=&limit= |
/clusters/{id}/nocturne/promql | telemetry.query | ?query=&time=, ou ?query=&start=&end=&step= |
/clusters/{id}/nocturne/rightsizing | estate.read | ?namespace=&kind=&name=&window= |
/clusters/{id}/nocturne/services | estate.read | ?namespace=&name= |
/clusters/{id}/nocturne/configmaps | config.read | ?namespace=&name=; cada leitura grava configmap.view na trilha de auditoria |
/clusters/{id}/nocturne/check | estate.read | ?namespace=&kind=&name=&type=&patch=: aplica um patch proposto a uma cópia do objeto ao vivo, em memória, e responde se o servidor de API o aceitaria. Um patch que amplia o pod (privileged, namespaces do host, volume hostPath, capabilities adicionadas, root, outra service account, um contêiner novo, outro command ou args, imagem de outro repositório) ou o alcance de um Service (NodePort, LoadBalancer, IPs externos) é recusado, e o Nocturne nunca imprime o comando dele |
nocturne
Caminho base /api/v1/nocturne. Alcançado pelo navegador apenas através do reverse proxy
do orbit-api (POST /chat, POST /analyze e GET /models no orbit-api, mesmos
caminhos, transmitidos sem buffer, com o token do serviço trocado no salto); veja
architecture.md. Do navegador, isso é a própria origem do web, como em toda outra
rota. Toda rota exige autenticação e está sujeita aos limites de chat/analyze abaixo; o
rate limiter por IP se aplica aqui em todas as rotas, não só no contact. Do lado do
orbit-api nesse salto, chat e analyze exigem a permissão nocturne.use, e models,
qualquer usuário logado; o proxy repassa o X-Orbit-Session do usuário ao nocturne,
cujas ferramentas chamam o orbit-api de volta com ele.
| Rota | Devolve |
|---|---|
POST /chat | text/event-stream; veja os frames SSE abaixo |
POST /analyze | JSON, análise de cluster em uma só chamada |
GET /models | Os tiers configurados e se cada um está alcançável |
Roteamento de modelo: tier não é um campo da requisição
Dois tiers ficam atrás de uma interface: reasoning (análise, causa raiz, planos de
FinOps) e fast (ajuda sobre o produto, formatação, respostas curtas). tier não faz
parte do corpo da requisição de chat ou analyze. O Adendo v0.2 o removeu
deliberadamente: um cliente que escolhe o próprio tier, sem autenticação ou por descuido,
é o problema de "choose which model tier to bill" (escolher qual tier de
modelo faturar) que o adendo
existe para fechar. O tier.Select classifica a requisição no servidor, e só essa
classificação pode alcançar o tier reasoning. O nocturne continua reportando o tier
escolhido a quem chamou, no frame SSE done e em um cabeçalho de resposta: você sempre
enxerga o que rodou e nunca consegue escolher.
GET /models responde com o provedor, os dois limites e uma entrada por tier com uma
sondagem de alcançabilidade em cache (nunca por requisição: um /models sob polling não
pode virar uma fatura). A credencial do provedor nunca é incluída, e toda string de erro do
upstream é ocultada antes de sair do serviço:
{
"provider": "mock" | "openai" | "anthropic",
"maxTokens": 2048,
"timeout": "2m0s",
"tiers": [
{ "tier": "reasoning", "purpose": "analysis, root cause and FinOps plans",
"model": "<NOCTURNE_REASONING_MODEL>", "configured": true, "reachable": true,
"checkedAt": "<RFC 3339>", "error": "<redacted, only when unreachable>" },
{ "tier": "fast", "purpose": "product help, formatting and short answers",
"model": "<NOCTURNE_FAST_MODEL>", "configured": true, "reachable": true,
"checkedAt": "<RFC 3339>" }
]
}Tipos de frame SSE (POST /chat)
Quatro tipos de evento, e data: é sempre JSON:
event: | Payload em data: | Significado |
|---|---|---|
token | {"text": "..."} | Um pedaço incremental da resposta do assistente. |
tool | {"name", "status", "detail"} | O modelo invocou uma ferramenta/função. |
done | {"tier": "reasoning" | "fast", "model", "class", "routing", "provider", "finishReason", "usage": {"inputTokens","outputTokens"}, "durationMs"} | Stream completo, sempre o último frame. Carrega o tier que rodou; veja acima. finishReason é stop, shutdown (um rollout drenou o pod no meio da resposta), timeout ou error. |
error | {"code","message"} | code vem do mesmo conjunto fechado de todas as outras rotas. Um event: error dentro de uma resposta 200 conta como falha para efeito de métricas, não como sucesso; veja operations.md. |
orbit-stack
O engine de telemetria fala a API do Prometheus na porta 8082: POST /api/v1/write
(remote-write 1.0), GET|POST /api/v1/query_range, GET|POST /api/v1/query,
GET|POST /api/v1/series, GET|POST /api/v1/labels, GET /api/v1/label/{name}/values,
GET /api/v1/metadata, GET /api/v1/rules, GET|POST /api/v1/query_exemplars,
GET|POST /api/v1/format_query, GET /api/v1/status/buildinfo,
GET /api/v1/status/tsdb, POST /-/flush, mais as probes do contrato e
/api/v1/version. As respostas nas rotas de telemetria estão nos formatos do Prometheus,
não nos do contrato, warnings incluído, então agentes e dashboards não precisam de
adaptador; as rotas de leitura dele são limitadas por IP de cliente por
ORBIT_STACK_QUERY_RPM e ORBIT_STACK_QUERY_BURST. O Deck nunca o chama diretamente: o
orbit-api traduz as chaves de métrica do Deck e repassa PromQL ad hoc em
GET /api/v1/query_range. Cada rota, parâmetro e o PromQL que ele responde estão em
orbit-stack.md.
Os traces (Adendo v0.5) chegam em POST /v1/traces, OTLP/HTTP com corpo protobuf ou JSON,
em gzip, zstd ou sem compressão, com o mesmo bearer do remote-write, e são respondidos nos formatos do
próprio OTLP (sucesso parcial, google.rpc.Status). O engine também serve as sete
leituras de APM acima nos mesmos caminhos, nos formatos e no envelope de erro do contrato;
o orbit-api as encaminha sem alteração. O apm.md traz as respostas do
receptor e o que enviar.
Códigos de erro, um conjunto fechado
O CONTRACT.md fixa nove códigos, o Adendo v0.4 acrescentou writes_disabled e
conflict, e o Adendo v0.5 acrescentou forbidden. Um serviço não inventa outro:
| Código | Status HTTP convencional | Significado |
|---|---|---|
invalid_request | 400 | Corpo/parâmetros de requisição malformados ou semanticamente inválidos. |
unauthorized | 401 (fixado pelo contrato) | Credencial ausente, malformada ou inválida. Nunca diz qual. |
not_found | 404 | Recurso inexistente (por exemplo, um id de cluster desconhecido). |
payload_too_large | 413 | O corpo excede o limite daquela rota; veja Limites. |
rate_limited | 429 | O limitador por IP disparou; veja Limites. |
unsupported_media_type | 415 | O corpo da requisição não era JSON. |
not_ready | 503 (fixado pelo contrato, casando com a semântica do próprio /readyz) | Uma dependência não está respondendo. |
upstream_error | 502 | Uma chamada downstream (por exemplo, orbit-api → nocturne) falhou. |
internal_error | 500 | Falha não tratada no servidor. |
writes_disabled | 403 | Esta build nunca optou por aceitar escritas (Adendo v0.4). |
conflict | 409 | O objeto se moveu entre a simulação e a confirmação (Adendo v0.4); desde o Adendo v0.5, também um nome de usuário ou um uid de dashboard já em uso, um dashboard salvo por outra pessoa depois que você o leu, um papel ainda em uso, ou uma mudança que deixaria a instalação sem nenhum usuário habilitado com users.manage. |
forbidden | 403 | A sessão é válida, mas o papel dela não tem a permissão da rota; a mensagem diz qual é (Adendo v0.5). Também uma conta desativada no login, e uma escrita num dashboard nativo. |
A coluna de status, além dos dois que o CONTRACT.md fixa explicitamente (unauthorized
→ 401, not_ready → 503), reflete a convenção REST comum para o significado de cada
código; a garantia do próprio CONTRACT.md é mais estreita e mais forte do que qualquer
número específico: "the matching HTTP status" (o status HTTP correspondente) sempre
concorda com o código, em toda rota.
Limites, a lista completa
O primeiro bloco é a seção "Limits are part of the contract" do CONTRACT.md,
literalmente; as linhas depois de analyze vêm dos adendos que acrescentaram as rotas
correspondentes:
| Limite | Valor |
|---|---|
| Corpo da requisição, geral | 1 MiB |
Corpo da requisição, POST /contact | 64 KiB |
Rate limit do contact | 5 requisições/minuto, burst 3 |
| Timeout de requisição (todas as rotas) | 20s |
query_range: máximo de pontos por resposta | 3.000 |
query_range: janela máxima | 90 dias |
query_range: expr máxima | 2.000 runes |
query_range: passo mínimo | 15s |
query_range: passo máximo | 24h |
events: máximo devolvido | 500 |
logs: tailLines padrão / máximo | 200 / 5.000 |
logs: máximo de bytes em uma resposta sem streaming | 2 MiB |
scale / resources: corpo da requisição | 16 KiB |
scale: replicas | 0..1000 |
chat: máximo de mensagens | 40 |
chat: máximo de runes por mensagem | 8.000 |
chat: máximo de runes no total | 32.000 |
chat: máximo de runes no system prompt | 4.000 |
analyze: máximo de runes de entrada | 24.000 |
analyze: máximo de runes de saída | 2.000 |
Corpos de identidade (auth, users, roles, marcações de alerta) | 16 KiB |
| Corpo de dashboard | 1 MiB |
| Esperas de login, por nome de usuário | 5 falhas sem espera, depois 1 s, dobrando até 1 min |
| Esperas de login, por endereço de cliente | 20 falhas sem espera, depois dobrando até 15 min |
| Rotas de login, requisições por minuto | 30 por endereço de cliente, 300 compartilhadas quando o endereço é o do web |
| Sessões por usuário | 100, encerrando primeiro a mais antiga |
| Duração da sessão | 12 h, absoluta |
audit: limit | 1..1000, padrão 100 |
audit: linhas de CSV | 100.000 |
| Nota de alerta | 500 caracteres |
| Corpo de requisição OTLP, depois de desfeito o gzip ou o zstd | 16 MiB, ou ORBIT_STACK_MAX_BODY_BYTES se for menor |
| Um trace no engine | ORBIT_STACK_TRACE_MAX_BYTES, padrão 5 MiB |
Busca de traces: limit | 1..1000, padrão 20 |
Busca de traces: filtros attr | 8 |
| Janela de traces e de APM | 31 dias |
| Colunas do heatmap | 360, cerca de 120 por padrão |
| Passo do heatmap | 15 s no mínimo |
Uma requisição que exceda qualquer um destes recebe o código de erro fechado
correspondente (payload_too_large, invalid_request ou rate_limited) em vez de um
truncamento silencioso. Se você integra com esta API, confira cada limite acima no cliente
antes de enviar a requisição; a verificação no servidor é uma rede de segurança.
Para onde ir em seguida
- O que emite qual métrica, e como um sistema saturado se parece nesta API:
operations.md. - As falhas de autenticação acima, explicadas do lado do modelo de ameaças:
security.md. - Um
429ou um stream SSE travado na prática:troubleshooting.md.