Pular para o conteúdo

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 exceto GET /healthz e GET /readyz. No orbit-api, o usuário logado vai por cima dele, em X-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. Veja security.md e identity.md.
  • Do navegador, todo caminho abaixo é chamado contra a própria origem do web (por exemplo https://your-host/api/v1/clusters), e o servidor do web o encaminha ao orbit-api sem alteração, anexando o bearer e copiando o cookie orbit_session para o X-Orbit-Session. Não existe um hostname público separado para o orbit-api. Se você estiver chamando um serviço diretamente para depuração (por exemplo nas portas de debug que o docker-compose.yml publica), anexe você mesmo o bearer; veja install/docker-compose.md.
  • Compressão: pelo web, uma resposta JSON de 1 KiB ou mais trafega com Content-Encoding: gzip quando a requisição aceita. Um stream SSE nunca, e o curl sem --compressed recebe o mesmo JSON sem compressão. O próprio orbit-api responde sem compressão.
  • Logs, não respostas: toda requisição gera uma linha JSON do slog no stdout (método, path, status, duração), independentemente do desfecho. Veja operations.md.

Rotas que todo serviço de backend expõe

RotaDevolveAutenticação?Observações
GET /healthz200 {"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 /readyz200 quando as dependências respondem, 503 caso contrárioNã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 /metricsExposição PrometheusNã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"}SimExige 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.

RotaPermissãoDevolve
GET /clustersestate.readCluster[]
GET /clusters/{id}estate.readCluster
GET /clusters/{id}/nodesestate.readNode[]
GET /clusters/{id}/workloadsestate.readWorkload[]; parâmetros: ?namespace=&kind=&q=
GET /clusters/{id}/eventsestate.readEvent[]; parâmetros: ?limit= (máximo 500, veja Limites)
GET /clusters/{id}/componentstelemetry.query e estate.readComponent[]: 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}/alertsestate.readAlert[], com os campos de reconhecimento descritos abaixo
GET /clusters/{id}/changesestate.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}/finopsestate.readFinOps
GET /clusters/{id}/recommendationsestate.readRecommendation[]
GET /query_rangetelemetry.queryQueryResult; parâmetros: ?cluster=&expr=&from=&to=&step=
POST /contactpública202 {"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 /leadsusers.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}/logslogs.readtext/plain, ou text/event-stream com ?follow=1; parâmetros: ?pod=&container=&tailLines=&previous=&follow=
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/eventsestate.readEvent[]; parâmetros: ?limit= (máximo 500)
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/replicasetsestate.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}/scaleworkloads.writeWriteResult; corpo {replicas, dryRun, resourceVersion?}
POST /clusters/{id}/workloads/{ns}/{kind}/{name}/resourcesworkloads.writeWriteResult; corpo {container, requests:{cpu,memory}, limits:{cpu,memory}, dryRun, resourceVersion?}
GET /clusters/{id}/workloads/{ns}/Deployment/{name}/revisionsestate.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}/releasesapm.read e estate.readO 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}/rollbackworkloads.writeWriteResult; 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}/restartworkloads.writeWriteResult; 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}/rolloutestate.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}/suspendworkloads.writeWriteResult; corpo {suspend, dryRun, resourceVersion?}
POST /clusters/{id}/workloads/{ns}/CronJob/{name}/triggerworkloads.writeWriteResult com after.job, o Job copiado do template do CronJob; corpo {dryRun, resourceVersion?}
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/configconfig.readWorkloadConfig: 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/revealconfig.read{name, value, source, object?, key?}; corpo {container, name}; um valor mascarado, auditado sem ele
GET /clusters/{id}/workloads/{ns}/{kind}/{name}/manifestconfig.readO 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/sessionsnocturne.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.use204

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.

text
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.source diz 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; veja architecture.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.kind e .action carregam 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 valor Deployment descreveria 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."

text
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âmetroObrigatórioFormato aceitoDefault
clustersimUm id de cluster vindo de GET /clusters, ≤128 caracteres. Um id desconhecido é 404.nenhum
exprsimUma MetricKey (abaixo) ou PromQL bruto. ≤2.000 runes.nenhum
fromnãoRFC 3339 (2026-03-14T08:26:53Z) ou segundos Unix (1300000000; um valor fracionário é truncado).to menos 1 hora
tonãoOs mesmos dois formatos de from.agora, truncado no segundo
stepnãoUma 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_URL definida: a expressão vai literalmente para o engine. unit é "bytes" quando a expressão nomeia uma métrica *_bytes e "count" caso contrário: o engine devolve um número e o orbit-api nã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_URL definida: 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: 400 invalid_request, dizendo ad-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 o orbit-api recusa em vez de desenhar uma linha gerada que pareça uma resposta.
  • Uma expressão que o engine rejeita (errorType bad_data ou execution) é 400 invalid_request carregando a mensagem do próprio engine. Um engine que deu timeout ou que não está lá (timeout, canceled, unavailable ou qualquer outra falha) é 502 upstream_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:

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

Os 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:

  1. X-Orbit-Operator-Token é igual ao ORBIT_DECK_WRITE_TOKEN do servidor web (comparação em tempo constante). O token é gasto nesse salto e nunca é encaminhado ao orbit-api.
  2. A requisição prova ser de mesma origem: Sec-Fetch-Site: same-origin ou none, ou um Origin cujo 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.

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

RotaPermissãoCorpo e resposta
GET /auth/statepública{setupRequired, demo, demoUsers?: [{username, role}]}
POST /auth/loginpú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/setuppú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/logoutsessão204; a sessão é revogada. Passando pelo web, o cookie é limpo seja qual for a resposta do orbit-api.
GET /auth/mesessão{user, role: {id, name}, permissions, session: {id, expiresAt}}
POST /auth/passwordsessão{current, next} → 204; um current errado é 400; todas as outras sessões do usuário são encerradas
GET /users, POST /usersusers.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.manageQualquer um de name, email, role, disabled, password → {user}; DELETE → 204
POST /users/{id}/revoke-sessionsusers.manage{revoked}, o número de sessões encerradas
GET /roles, POST /rolesusers.manage{roles: [role], permissions: [the closed set]}; {name, description, permissions} → 201 {role}
PATCH /roles/{id}, DELETE /roles/{id}users.manageQualquer um de name, description, permissions → {role}; DELETE → 204
text
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:

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

RotaPermissãoCorpo e resposta
GET /dashboards?q&tagdashboards.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 /dashboardsdashboards.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.write204; 403 num dashboard provisionado
GET /labels, GET /label/{name}/values, GET /series, GET /query, GET /status/tsdbtelemetry.queryO 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.

RotaResposta
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&notAttr=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

RotaPermissãoCorpoEfeito
POST /clusters/{id}/alerts/{alertId}/ackworkloads.write{note?}ack: "acked"
DELETE /clusters/{id}/alerts/{alertId}/ackworkloads.writenenhumvolta a open quando está reconhecido
POST /clusters/{id}/alerts/{alertId}/silenceworkloads.write{minutes, note?}ack: "silenced" até o fim do prazo; minutes é 15, 60, 240 ou 1440
DELETE /clusters/{id}/alerts/{alertId}/silenceworkloads.writenenhumvolta 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.

RotaPermissãoParâmetros
/clusters/{id}/nocturne/podsestate.read?namespace=&kind=&workload=&node=&unhealthy=; sem config.read, todo valor de env aparece como [redacted]
/clusters/{id}/nocturne/nodesestate.readnenhum
/clusters/{id}/nocturne/eventsestate.read?namespace=&kind=&name=&type=&limit=
/clusters/{id}/nocturne/promqltelemetry.query?query=&time=, ou ?query=&start=&end=&step=
/clusters/{id}/nocturne/rightsizingestate.read?namespace=&kind=&name=&window=
/clusters/{id}/nocturne/servicesestate.read?namespace=&name=
/clusters/{id}/nocturne/configmapsconfig.read?namespace=&name=; cada leitura grava configmap.view na trilha de auditoria
/clusters/{id}/nocturne/checkestate.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.

RotaDevolve
POST /chattext/event-stream; veja os frames SSE abaixo
POST /analyzeJSON, análise de cluster em uma só chamada
GET /modelsOs 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:

text
{
  "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ódigoStatus HTTP convencionalSignificado
invalid_request400Corpo/parâmetros de requisição malformados ou semanticamente inválidos.
unauthorized401 (fixado pelo contrato)Credencial ausente, malformada ou inválida. Nunca diz qual.
not_found404Recurso inexistente (por exemplo, um id de cluster desconhecido).
payload_too_large413O corpo excede o limite daquela rota; veja Limites.
rate_limited429O limitador por IP disparou; veja Limites.
unsupported_media_type415O corpo da requisição não era JSON.
not_ready503 (fixado pelo contrato, casando com a semântica do próprio /readyz)Uma dependência não está respondendo.
upstream_error502Uma chamada downstream (por exemplo, orbit-api → nocturne) falhou.
internal_error500Falha não tratada no servidor.
writes_disabled403Esta build nunca optou por aceitar escritas (Adendo v0.4).
conflict409O 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.
forbidden403A 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:

LimiteValor
Corpo da requisição, geral1 MiB
Corpo da requisição, POST /contact64 KiB
Rate limit do contact5 requisições/minuto, burst 3
Timeout de requisição (todas as rotas)20s
query_range: máximo de pontos por resposta3.000
query_range: janela máxima90 dias
query_range: expr máxima2.000 runes
query_range: passo mínimo15s
query_range: passo máximo24h
events: máximo devolvido500
logs: tailLines padrão / máximo200 / 5.000
logs: máximo de bytes em uma resposta sem streaming2 MiB
scale / resources: corpo da requisição16 KiB
scale: replicas0..1000
chat: máximo de mensagens40
chat: máximo de runes por mensagem8.000
chat: máximo de runes no total32.000
chat: máximo de runes no system prompt4.000
analyze: máximo de runes de entrada24.000
analyze: máximo de runes de saída2.000
Corpos de identidade (auth, users, roles, marcações de alerta)16 KiB
Corpo de dashboard1 MiB
Esperas de login, por nome de usuário5 falhas sem espera, depois 1 s, dobrando até 1 min
Esperas de login, por endereço de cliente20 falhas sem espera, depois dobrando até 15 min
Rotas de login, requisições por minuto30 por endereço de cliente, 300 compartilhadas quando o endereço é o do web
Sessões por usuário100, encerrando primeiro a mais antiga
Duração da sessão12 h, absoluta
audit: limit1..1000, padrão 100
audit: linhas de CSV100.000
Nota de alerta500 caracteres
Corpo de requisição OTLP, depois de desfeito o gzip ou o zstd16 MiB, ou ORBIT_STACK_MAX_BODY_BYTES se for menor
Um trace no engineORBIT_STACK_TRACE_MAX_BYTES, padrão 5 MiB
Busca de traces: limit1..1000, padrão 20
Busca de traces: filtros attr8
Janela de traces e de APM31 dias
Colunas do heatmap360, cerca de 120 por padrão
Passo do heatmap15 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 429 ou um stream SSE travado na prática: troubleshooting.md.