Recursos
APM e traces
O orbit-stack recebe traces do OpenTelemetry por OTLP/HTTP, guarda os spans e deriva
deles, com os mesmos nomes, as séries de span metrics e de service graph que o
metrics-generator do Grafana Tempo produz, gravando-as no próprio armazenamento de séries
temporais. O orbit-api serve as leituras ao Deck, que desenha uma tabela de serviços, uma
página por serviço, um mapa de serviços, uma busca de traces e uma cascata por trace. A
especificação é o Adendo v0.5 do CONTRACT.md; o engine de armazenamento por trás de tudo isso
está descrito em orbit-stack.md.
Enviar traces
| O quê | Valor |
|---|---|
| Endpoint | POST /v1/traces na porta de API do engine, 8082: http://<release>-orbit-stack.<namespace>.svc.cluster.local:8082/v1/traces no Kubernetes, http://orbit-stack:8082/v1/traces dentro da rede do compose, http://127.0.0.1:8082/v1/traces a partir do host do compose |
| Protocolo | Só OTLP/HTTP. Não existe listener gRPC: um exporter configurado com grpc, ou apontado para a 4317, não alcança nada. |
| Corpo | Content-Type: application/x-protobuf ou application/json (ids em hexadecimal; ids em base64 e nomes de enum também são aceitos) |
| Compressão | Content-Encoding: gzip ou zstd, ou nenhuma. O orbit-collector exporta em zstd e volta ao gzip por 5 minutos quando um engine responde 415 |
| Credencial | Authorization: Bearer <ORBIT_STACK_INGEST_TOKEN> de fora do release (ele envia e nada mais), ou ORBIT_STACK_AUTH_TOKEN; nenhuma com ORBIT_STACK_AUTH_MODE=disabled |
| Tamanho | 16 MiB depois de desfeito o gzip ou o zstd, ou ORBIT_STACK_MAX_BODY_BYTES se for menor; um trace, no máximo ORBIT_STACK_TRACE_MAX_BYTES (5 MiB) |
A resposta volta na mesma codificação da requisição, como o OTLP/HTTP determina:
| Status | Significado | O remetente deve |
|---|---|---|
200, corpo vazio | Todos os spans foram aceitos | Seguir em frente |
200 com partialSuccess | Alguns spans recusados um a um (sem um id de trace ou de span válido, ou de um trace que cresceu além de ORBIT_STACK_TRACE_MAX_BYTES), contados em rejectedSpans, com o primeiro motivo em errorMessage | Não reenviá-los |
400 com um google.rpc.Status | O corpo não é uma requisição de exportação | Não reenviar |
401 | Bearer ausente ou errado | Corrigir a credencial |
413, 415 | Grande demais (acima de 16 MiB depois de descomprimido, ou com mais spans, recursos ou objetos JSON do que o orçamento em andamento comporta decodificados); Content-Type ou Content-Encoding errado | Corrigir a requisição |
503 + Retry-After | Os bytes OTLP retidos pelas requisições em andamento passariam do orçamento deles (ORBIT_STACK_TRACE_HEAD_BYTES, no mínimo 32 MiB), o head chegou ao dobro do limite enquanto um segmento é gravado, ou o write-ahead log falhou | Tentar de novo depois da espera |
Um span é gravado no write-ahead log antes de a resposta sair, e o log passa por fsync a cada segundo: um crash do processo não perde nada que já foi confirmado, e uma queda de energia perde no máximo esse segundo. Um span que o trace já tem (o retry de um exporter) é aceito e guardado uma vez só. Um corpo recusado é lido até o fim antes da resposta, então o remetente recebe a resposta e não uma conexão derrubada. Os links de span e o escopo de instrumentação não são guardados.
Pelo shell
Um span, em OTLP/JSON, contra o stack do compose ou por um port-forward
(kubectl -n sreorbit port-forward svc/sreorbit-orbit-stack 8082:8082). Os dois
timestamps são nanossegundos lidos do seu próprio relógio (date do GNU; um trace fora da
janela que você consulta não aparece):
NOW=$(date +%s%N)cat > span.json <<EOF{"resourceSpans":[{"resource":{"attributes":[ {"key":"service.name","value":{"stringValue":"checkout"}}, {"key":"k8s.namespace.name","value":{"stringValue":"shop"}}, {"key":"k8s.deployment.name","value":{"stringValue":"checkout"}}, {"key":"k8s.pod.name","value":{"stringValue":"checkout-7d9c5-abcde"}}]}, "scopeSpans":[{"spans":[{ "traceId":"5b8efff798038103d269b633813fc60c","spanId":"eee19b7ec3c1b174", "name":"POST /checkout","kind":2, "startTimeUnixNano":"$NOW","endTimeUnixNano":"$((NOW+120000000))", "attributes":[{"key":"http.response.status_code","value":{"intValue":"200"}}], "status":{"code":1}}]}]}]}EOFcurl -fsS -X POST localhost:8082/v1/traces -H "Authorization: Bearer $ORBIT_STACK_AUTH_TOKEN" \ -H 'Content-Type: application/json' --data-binary @span.jsoncurl -fsS -H "Authorization: Bearer $ORBIT_STACK_AUTH_TOKEN" localhost:8082/api/v1/traces/5b8efff798038103d269b633813fc60cA primeira chamada responde {}; a segunda devolve o trace com o span, o recurso dele e
"kind":"server". No compose, ORBIT_STACK_AUTH_TOKEN é o valor que está no .env; com
make up, o engine roda com a autenticação desligada e ignora o header.
De um OpenTelemetry Collector
Aponte o exporter OTLP/HTTP do Collector para o engine e deixe o Collector continuar recebendo o que as suas aplicações mandam para ele, gRPC incluído:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
k8sattributes: {}
batch: {}
exporters:
otlphttp/orbit:
endpoint: http://sreorbit-orbit-stack.sreorbit.svc.cluster.local:8082
headers:
Authorization: "Bearer ${env:ORBIT_STACK_AUTH_TOKEN}"
compression: gzip
service:
pipelines:
traces:
receivers: [otlp]
processors: [k8sattributes, batch]
exporters: [otlphttp/orbit]O próprio exporter acrescenta /v1/traces ao endpoint; para passar a URL completa, use
traces_endpoint no lugar dele. O default de encoding é proto, e json também
funciona. O k8sattributes acrescenta os atributos de recurso do Kubernetes descritos na
próxima seção (os defaults dele já extraem os nomes do namespace, do pod, do Deployment e do
node) e precisa do RBAC que o README dele descreve; ele vem nas distribuições contrib e
Kubernetes do Collector. As versões recentes do Collector chamam esses dois componentes de
otlp_http e k8s_attributes e ainda aceitam os nomes acima como aliases obsoletos. O
Collector lê o bearer do próprio ambiente: dê ao pod dele um Secret com o token.
De um SDK, sem Collector
Todo SDK do OpenTelemetry lê as variáveis padrão. Num pod, com o bearer guardado num Secret
do namespace da aplicação
(kubectl -n APP_NAMESPACE create secret generic orbit-stack-otlp --from-literal=token="$ORBIT_STACK_INGEST_TOKEN",
em que APP_NAMESPACE é o namespace onde a aplicação roda). Entregue às aplicações o token de
ingestão, nunca o ORBIT_STACK_AUTH_TOKEN: com o token de ingestão um pod desse namespace envia
spans e não consegue ler métricas, logs ou traces de ninguém.
env:
- name: POD_NAME
valueFrom: { fieldRef: { fieldPath: metadata.name } }
- name: POD_NAMESPACE
valueFrom: { fieldRef: { fieldPath: metadata.namespace } }
- name: NODE_NAME
valueFrom: { fieldRef: { fieldPath: spec.nodeName } }
- name: OTLP_BEARER
valueFrom: { secretKeyRef: { name: orbit-stack-otlp, key: token } }
- name: OTEL_SERVICE_NAME
value: checkout
- name: OTEL_RESOURCE_ATTRIBUTES
value: k8s.namespace.name=$(POD_NAMESPACE),k8s.pod.name=$(POD_NAME),k8s.node.name=$(NODE_NAME),k8s.deployment.name=checkout,service.version=5.0.2,deployment.environment.name=production
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: http://sreorbit-orbit-stack.sreorbit.svc.cluster.local:8082
- name: OTEL_EXPORTER_OTLP_PROTOCOL
value: http/protobuf
- name: OTEL_EXPORTER_OTLP_COMPRESSION
value: gzip
- name: OTEL_EXPORTER_OTLP_HEADERS
value: Authorization=Bearer%20$(OTLP_BEARER)O Kubernetes expande $(NAME) a partir das variáveis declaradas antes dela. %20 é o
espaço, codificado em percent-encoding como o formato da variável de header exige.
OTEL_EXPORTER_OTLP_ENDPOINT é a URL base, e o SDK acrescenta /v1/traces; já a variável
por sinal, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, recebe a URL completa.
O engine grava os atributos k8s.* que um SDK envia como chegam: ele não os confere com o pod
remetente, como faz o orbit-collector. Um pod com o token de ingestão pode nomear outro pod,
namespace ou workload nos seus spans. Quando o namespace de um span precisa ser o de origem,
envie pelo coletor do chart (apm.collector, engine orbit) e deixe os namespaces das
aplicações fora do allowFromNamespaces do engine.
Libere os spans na NetworkPolicy
Com networkPolicy.enabled (o default do chart), o engine aceita o orbit-api, o agente do
próprio chart e a loja de demonstração na 8082, e mais nada. Numa CNI que impõe políticas,
um Collector ou uma aplicação em outro namespace precisa que esse namespace seja nomeado:
helm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \ --set 'components.orbit-stack.networkPolicy.allowFromNamespaces={observability}'observability é o namespace em que o seu Collector roda; para liberar vários, separe-os por
vírgulas. Os manifestos puros precisam da mesma regra acrescentada a sreorbit-orbit-stack
em 80-networkpolicies.yaml.
Atributos de recurso que ligam um serviço ao Kubernetes
O engine identifica um serviço pelo service.name (um span sem ele fica como
unknown_service, o default dos próprios SDKs) e guarda, por serviço, os atributos do
Kubernetes dos recursos que lhe enviaram spans:
| Atributo de recurso | Onde aparece |
|---|---|
k8s.namespace.name, k8s.deployment.name | No painel "Infraestrutura" do serviço e na coluna Workload, com link para a página do workload no Deck |
k8s.pod.name | Nos pods do serviço e na aba Infraestrutura dos detalhes do span: CPU, memória e reinícios do pod, e os logs dele até um minuto antes e depois do span |
k8s.node.name | No node mostrado nos detalhes do span |
service.version, deployment.environment.name (ou deployment.environment) | Em traces_target_info, mais abaixo |
Sem eles, o serviço continua tendo taxas, latências, mapa e traces, e o Deck avisa que os
spans não trazem atributos de recurso do Kubernetes. Os peers que nunca enviam spans (um
banco de dados, uma fila, uma API de terceiros) ganham nome a partir dos atributos do span
de cliente: peer.service (ou service.peer.name), server.address (ou net.peer.name),
network.peer.address (ou net.sock.peer.addr), db.system (ou db.system.name),
db.namespace (ou db.name), messaging.system e messaging.destination.name (ou
messaging.destination).
Pelo collector do chart, um app que envia os próprios spans recebe os atributos k8s.* do
próprio pod, seja o que for que tenha enviado, e mantém o service.name quando o spec do pod
declara esse nome. Só pods do namespace de node do release e de
apm.collector.orbit.trustedNamespaces podem falar por outros pods. As regras e como declarar
um nome estão em Segurança.
Versões sem service.version
Um serviço cujos spans não trazem service.version continua tendo versões: o orbit-api as tira
dos ReplicaSets do Deployment dele, que aparecem no nome de cada pod
(<deployment>-<pod-template hash>-<suffix>). A versão de um ReplicaSet é a tag da imagem do
contêiner da aplicação, seguida do hash do pod template (1.31.6 · 6f7b5956c6) quando outro
ReplicaSet guardado do mesmo Deployment tem a mesma tag (um kubectl rollout restart, por
exemplo). Assim, dois ReplicaSets nunca ficam com a mesma versão. O contêiner da aplicação é o
que tem o nome do Deployment, senão aquele em que dois sinais concordam: a imagem dele trocou entre
os ReplicaSets do Deployment, e ele declara uma porta. Um sinal que nenhum contêiner mostra não
conta. Quando eles discordam ou sobra mais de um (rollout só de um sidecar, sidecars e nenhuma troca
ainda), ou a imagem não tem tag ou usa latest, a versão é só o hash. A página do serviço mostra,
em Versão, seguida de "(inferida)", a versão do ReplicaSet dos pods que mandaram os spans mais
novos da janela, ou a do ReplicaSet atual quando eles não nomeiam um pod: um rollout preso mostra o
que ainda serve, e uma janela passada mostra o que rodava nela. Imagem mostra o contêiner da
aplicação. O cartão de versão com falha intitula as colunas de versão como "Versão (inferida)", toda frase
do achado nomeia a versão com "(inferida)", e o detector de versão com falha julga essas
versões como julga as de um SDK. Um serviço com service.version em algum span dos últimos 90
minutos fica só com essas. Pods de StatefulSet, DaemonSet ou CronJob, e serviços fora do
Kubernetes, não têm versão para inferir: num escopo só com serviços assim, o
GET /api/v1/nocturne/insights lista o errors_after_rollout em noVersion, nunca em
checked. Um release que o detector não consegue julgar (poucas requisições, nenhuma versão
antes dele) deixa os picos de erro e de latência para os detectores de pico, e um pico de latência
nomeia um rollout a até 5 minutos do degrau. Quando o serviço tem um achado de versão com falha, um
pico a partir da primeira troca de versão da hora cede a ele.
Os marcadores de rollout nos gráficos do serviço e nos das operações dele, e o Último rollout, vêm das datas de criação desses mesmos ReplicaSets, e por isso duram mais que os eventos do API server (guardados por 1 hora por padrão). Enquanto o Deployment está de volta num ReplicaSet mais antigo, um mais novo cujos pods nunca mandaram span (uma imagem que nunca baixou, depois desfeita) não ganha marcador; o rollout seguinte para frente traz o marcador de volta, porque só um rollback lê os spans. A volta para um ReplicaSet mais antigo que outro é marcada como "Rollback" no momento em que o último ReplicaSet mais novo que rodou mandou seu último span, um horário que a troca de um pod não move. Sem span para ler, vale a última vez que a condição Progressing do Deployment o nomeou. Só a última volta desse tipo fica conhecida. O Último rollout mostra a hora UTC quando é de hoje e há quanto tempo foi quando é de outro dia.
O que o engine deriva
Todo span aceito também alimenta um gerador que grava séries comuns no próprio armazenamento do engine a cada 15 segundos, com os nomes e os labels do metrics-generator do Tempo, de modo que um dashboard ou um alerta escrito para a saída do Tempo também lê a deste engine:
| Série | Labels |
|---|---|
traces_spanmetrics_calls_total | service, span_name, span_kind, status_code |
traces_spanmetrics_latency_bucket, _sum, _count | Os mesmos, mais le, em segundos |
traces_spanmetrics_http_4xx_total | Os mesmos das chamadas, só para spans server: os que têm http.response.status_code (ou http.status_code) 4xx, que as convenções semânticas deixam unset; série própria deste engine, desde 2026-11-06 |
traces_service_graph_request_total | client, server, connection_type |
traces_service_graph_request_failed_total | Os mesmos |
traces_service_graph_request_server_seconds_bucket, _sum, _count | Os mesmos, mais le |
traces_service_graph_request_client_total, traces_service_graph_request_nested_total, traces_service_graph_request_nested_seconds_total | client, server; séries próprias deste engine, o Tempo não grava nada parecido |
traces_target_info | job (o serviço), k8s_namespace_name, k8s_deployment_name, k8s_pod_name, k8s_node_name, service_version, deployment_environment; 1 enquanto um pod envia spans |
- Os valores dos labels são os do Tempo:
span_kind="SPAN_KIND_SERVER",status_code="STATUS_CODE_ERROR". - Buckets de latência: 1; 1,5; 2; 3; 5 e 7,5 em cada década de 1 ms a 30 s, 28 limites, seis
linhas por década para o heatmap de latência. Eles contêm todos os limites gravados antes de
2026-10-28 (1, 2, 5, 10, 20, 50, 100, 150, 200, 300, 500 e 750 ms, depois 1, 2, 5, 10, 20 e
30 s) com o mesmo
le, então essas séries seguem iguais num upgrade ou num rollback. Cada conjunto de labels grava 31 séries de latência, e não mais 21. - Os contadores são cumulativos desde que o engine subiu, então um restart é um reset de
contador, que o
rate()trata; uma série recebe um zero um intervalo antes do primeiro valor, para que as primeiras chamadas dela entrem noincrease(). - Uma aresta é um span de cliente mais o span de servidor que o tem como pai, pareados só
pelo id do span, então os dois se encontram mesmo quando chegaram em traces diferentes. Um
span de cliente com
db.system,db.namespaceoudb.namejá vira na hora uma aresta até aquele banco de dados (connection_type="database"). Spans de produtor e de consumidor commessaging.systemviram duas arestas passando pela fila, do produtor ao destino e do destino ao consumidor (connection_type="messaging_system"; o Tempo liga os dois serviços diretamente). Um span de servidor sem pai é uma aresta que parte deuser, e um span de cliente que ninguém respondeu em 10 s é uma aresta até opeer.serviceou oserver.addressdele (as duas comconnection_type="virtual_node"). Sem um span de servidor, a latência da aresta é a do cliente. traces_service_graph_request_client_totalconta as chamadas que os spans de cliente de um serviço fizeram numa aresta, e as sériesnested, dessas, as que ficam dentro de uma requisição, com os segundos da aresta: o span de cliente tem pai, ou o engine o costurou sob um em até 2,5 minutos. Um span de cliente sem pai é trabalho em segundo plano. Uma chamada sob um span interno sem pai, como o job de um worker com SDK, tem pai e conta comonested, assim como a cópia do orbit-probe de uma chamada que um SDK registrou sem pai. As chamadas em segundo plano de uma aresta são a primeira menos a segunda, então nenhuma que um engine anterior a essas séries contou aparece como segundo plano. Elas deixam de ser gravadas quando os rollups abaixo soltam a aresta, cerca de 32 minutos depois do último span dela.- O engine dá nome a cada operação uma vez, na entrada. Um span de servidor com
http.routeehttp.request.method(ouhttp.method) recebe o nome{method} {route}. Em qualquer nome, uma palavra ou um segmento de caminho que seja um número, um e-mail, um UUID ou um digest hexadecimal, ou um token de 16 caracteres ou mais com 3 dígitos ou mais vira{id}, e os parâmetros de consulta de uma URL saem:GET /users/12345?tab=2viraGET /users/{id}. Quando o nome muda, o span guarda o nome com que chegou emorbit.raw_name, e você continua podendo buscá-lo. As regras de ingestão veem o nome novo emname; useattr.orbit.raw_namepara casar com o antigo. - Um serviço mantém no máximo 1.000 operações e, como cliente, 1.000 arestas. Uma nova acima
disso, ou acima dos 20.000 conjuntos de labels do gerador, conta como
span_name="(other)"ouserver="(other)", e aorbit_stack_trace_generator_overflow_totalconta os spans dela. As que ele já mantém continuam contando. - O gerador mantém no máximo 20.000 conjuntos de labels, mais 2.000 para
(other); acima disso, descarta os novos e os conta emorbit_stack_trace_generator_dropped_total. Ele mantém no máximoORBIT_STACK_TRACE_GRAPH_PENDINGspans (padrão 100.000) à espera do outro lado de uma aresta; acima disso, um span fica sem par, a aresta conta a menos e atraces_service_graph_dropped_spans_totalo conta. Uma série que passa 15 minutos sem ver nenhum span deixa de ser gravada. - O resumo de serviços e o mapa de serviços também leem agregados que o gerador mantém por
serviço e por par de cliente e servidor, fora dos conjuntos de labels acima, para as suas
últimas 64 coletas (16 minutos a 15 s). Uma janela que começa dentro deles lista todos os
serviços que enviaram spans, com os spans que as coletas dentro da janela contaram, sem
extrapolar até as bordas da janela como o
increase()faz. Eles mantêm no máximo 100.000 serviços e 20.000 arestas, mais uma arestaserver="(other)"por cliente além disso. Uma janela mais longa, ou uma que começa antes do motor quando já existem séries anteriores, lê as séries.
Traces costurados
O orbit-probe dá a cada salto TCP um trace próprio. Um span de cliente que o probe registra
enquanto o mesmo processo atende uma requisição recebe o trace dessa requisição e cita o
trace do salto em orbit.hop.trace_id. O engine então guarda os spans do salto sob o trace
da requisição:
- Os spans do salto que chegam depois do span de cliente passam para o trace da requisição na entrada. Os que já estão no head vivo se juntam a ele ali mesmo. Uma cadeia de saltos termina na requisição mais externa, com no máximo 16 níveis, e um só trace vai da requisição HTTP, passando pelas chamadas Redis e SQL, até o próximo serviço e as chamadas de banco dele.
- Um alias vive 15 minutos, e o engine mantém no máximo 262.144 deles.
orbit_stack_trace_aliasesconta os vivos eorbit_stack_trace_alias_events_total{event}conta o que aconteceu com eles:recorded,refused(um trace citado como salto de si mesmo, um loop ou um salto já costurado em outro trace),expired,evicted, spansrewrittene partes do headmerged. - Uma parte de salto que o head gravou num segmento antes de o span de cliente chegar fica
sob o próprio id.
GET /api/v1/traces/{id}segue oorbit.hop.trace_idaté ela e devolve os spans dela sob o id do trace da requisição, com no máximo 16 saltos de profundidade eORBIT_STACK_TRACE_MAX_BYTESde spans seguidos. - O write-ahead log guarda os spans já costurados, e um restart reaplica os aliases junto com eles.
Chamadas sem pai
Quando o orbit-probe perde o contexto de uma chamada, um EXPIRE no Redis ou um SELECT chega ao
engine como span de cliente sem pai e com trace próprio. Isso acontece quando o probe não vê a
passagem do nginx para um worker do php-fpm. O engine coloca essa chamada dentro da requisição que
a fez quando só uma requisição pode ser a origem:
- Mesmo processo. O processo da chamada (mesmo pod e
process.pid) atendeu requisições, e quando a chamada começou havia exatamente um trace em andamento no seuthread.id, ou no processo inteiro. Requisição aqui é um span de servidor ou de consumidor, ou um span com pai que passa trabalho a um processo, como o span FastCGI do orbit-probe. Requisições encadeadas por pai (o nginx, o span FastCGI dele, a passagem ao php-fpm) contam como uma; a chamada vai para a mais interna. - Mesmo pod. O processo da chamada não mostra requisição em volta dela (nunca atendeu uma, ou o probe não viu esta passagem), outro processo do mesmo executável no pod atendeu requisições, e havia exatamente uma cadeia em andamento no pod. O engine decide quando uma requisição do pod termina 2 s depois do início da chamada somado à requisição mais longa do pod e ao maior atraso com que uma requisição do pod chegou (cada um no máximo 60 s); assim toda requisição em volta da chamada já chegou.
- Ambiguidade impede. Um processo visto com dois traces em andamento ao mesmo tempo numa thread deixa de casar por thread; visto com dois ao mesmo tempo em qualquer lugar, deixa de casar por processo. Um pod precisa de 8 requisições antes de ter chamadas costuradas. O engine acompanha um processo a partir da primeira chamada sem pai, e esse processo precisa de 8 requisições depois dela.
A chamada costurada recebe o span da requisição como pai e orbit.link = stitched, e o trace
dela passa para o trace da requisição; a lista de traces raiz deixa de mostrá-la sozinha. Uma
chamada que nomeou o salto seguinte (orbit.hop.trace_id) também deixa o trace dela como alias do
trace da requisição, e os spans que o salto mandar depois caem lá. A
página do trace desenha o cotovelo tracejado, como nos vínculos que o próprio probe infere.
Chamadas de workers de fila, crons e heartbeats não têm requisição em volta e continuam com trace
próprio.
eBPF e código juntos. Quando um pod também envia spans de um SDK, uma chamada eBPF espera até
10 s do tempo dos spans de SDK do pod pelo span de cliente do SDK da mesma chamada: um que a
envolva (exatamente, senão com folga de 1 ms) e cujo nome contenha a primeira palavra da chamada
(GET em redis redis-global-5 get). O engine descarta a cópia eBPF e mantém o span do SDK no
trace dele só quando exatamente um span assim envolve a chamada e esse span não envolve nenhuma
outra chamada eBPF do pod: um SDK que amostra deixa requisições de fora, e as chamadas delas
podem cair dentro dos spans de uma requisição que ele manteve. Um span de SDK que pode ter
envolvido uma chamada descartada por falta de espaço, ou uma enviada antes do primeiro span de
SDK do pod, não funde nada. Toda chamada que não funde segue para as regras acima. As
requisições do SDK só valem como requisições do pod depois que o SDK envolveu 64 chamadas eBPF
das palavras que ele usa e deixou de fora no máximo 1% delas; até lá, e num pod cujo SDK amostra,
as regras usam só as requisições do orbit-probe. O casamento usa o pod, não o pid, porque
um SDK num contêiner vê o próprio namespace de pid. Um span eBPF que já tem pai, como um que o
probe ligou ao trace do SDK pelo traceparent, ainda não é fundido.
O engine só casa no head vivo: os dois traces precisam estar lá. Ele acompanha no máximo 4.096
processos com chamadas sem pai e 4.096 pods por 10 minutos depois do último span, 64 requisições cada, e 65.536
chamadas à espera; acima disso, o pod que guarda a chamada mais antiga à espera descarta todas as
suas. Uma chamada que espera o gêmeo do SDK fica com a sua requisição enquanto o pod ainda a lista.
orbit_stack_trace_alias_events_total{event} conta as chamadas stitched e as twins fundidas
no span do SDK.
Traces raiz
Um trace raiz tem um span sem pai, ou um span cujo pai não está no trace: um span de servidor
do orbit-probe cita o span de cliente de quem o chamou mesmo quando o probe nunca o viu. O
span raiz é o span sem pai mais antigo; na falta dele, o mais antigo desses órfãos. Quase
todo trace é um trace raiz; o tipo do span raiz é que separa uma requisição (server,
consumer) de trabalho em segundo plano (client, producer, internal), como o
heartbeat Redis que um worker de fila manda sem nenhuma requisição em volta.
GET /api/v1/traces?root=true mantém os traces raiz, e rootKind=server,consumer mantém
aqueles cujo span raiz tem um dos tipos da lista; qualquer um dos dois acrescenta rootKind
a cada resultado. O engine registra o tipo na linha de resumo de cada trace, no mapa de zona
de cada chunk e nos agregados do segmento, então essa busca não lê spans. Segmentos gravados
antes desta versão não guardam o tipo raiz: neles, root=true volta a valer pelo span sem
pai, e rootKind não casa com nenhum.
Até 10 key (nomes de atributo) em GET /api/v1/traces acrescentam custom: {key: {values: [{value, count}], capped}}: os 10 valores mais frequentes de cada chave em todos os traces da
janela que a busca encontra, cada valor contado uma vez por trace que o carrega (primeiro o
atributo do próprio span, depois o do recurso). As facetas personalizadas do Deck usam essa leitura
com qualquer filtro além de status. Essa busca lê os spans de cada trace encontrado, então vai até o
timeout da requisição, e partial avisa que ela parou ali. capped avisa que a busca encontrou
mais de 4.096 valores distintos da chave: as contagens dela são então limites inferiores.
Taxa de requisições e proporção de erros por serviço, para um painel ou um alerta:
sum by (service) (rate(traces_spanmetrics_calls_total{span_kind=~"SPAN_KIND_SERVER|SPAN_KIND_CONSUMER"}[5m]))
sum by (service) (rate(traces_spanmetrics_calls_total{span_kind=~"SPAN_KIND_SERVER|SPAN_KIND_CONSUMER", status_code="STATUS_CODE_ERROR"}[5m]))
/ sum by (service) (rate(traces_spanmetrics_calls_total{span_kind=~"SPAN_KIND_SERVER|SPAN_KIND_CONSUMER"}[5m]))O dashboard nativo orbit-apm-red desenha as mesmas séries (dashboards.md).
Ler traces no Deck
Tudo fica sob /deck/apm, exige a permissão apm.read e cobre a janela escolhida na barra
do topo:
Serviços (
/deck/apm): todos os serviços, com taxa de requisições, taxa de erros, p50, p95 e p99, número de operações e workload. Um serviço fica degradado a partir de 1% de erros e falhando a partir de 5%; um serviço sem nenhuma requisição na janela aparece como sem tráfego. As requisições de um serviço são os spans de servidor e de consumidor dele, ou todos os spans dele quando não há nenhum dos dois.Um serviço (
/deck/apm/services/<name>): requisições por resultado, taxa de erros, latência e o heatmap dela ao longo do tempo (do serviço inteiro ou da operação escolhida acima dele), a tabela de operações, quem chama o serviço e o que ele chama, traces e erros recentes, e os objetos do Kubernetes em que ele roda. Workers e crons que informam o mesmoservice.namecontam sob ele, então a página os separa das requisições. Tempo por dependência é a parcela de cada dependência no tempo dentro das requisições do serviço, das sériesnested. Serviços chamados mostra primeiro as chamadas feitas dentro de uma requisição e diz quantas rodaram em segundo plano; os erros e o p95 cobrem todas as chamadas. Os traces recentes, os erros recentes e os tipos de erro leem os traces que uma requisição iniciou; quando a janela não tem nenhum, leem todas as raízes, e as listas dizem isso. Pods enviando spans conta todo pod cujos spans levam o nome, o que pode passar das réplicas do workload citado acima. Um serviço em segundo plano lê todas as suas chamadas. Numa janela que volta a antes de o engine gravar essas séries, esse gráfico e essa tabela leem todas as chamadas feitas até então, e nenhuma delas como segundo plano. Tempo gasto na tabela de operações é a parcela de cada operação no tempo que as operações listadas levaram (a soma das durações dos spans), e a tabela ordena por ele. Mais lentos que o p95, aqui e na página de uma operação de entrada, abre os traces cujo span de entrada levou mais que o p95 da janela.Uma operação (
/deck/apm/services/<name>/resource?op=<operation>, uma linha da tabela de operações): requisições por resultado, taxa de erros, p50, p95 e p99 (com o p95 de um dia antes e os rollouts do serviço nos gráficos), o heatmap de latência, os tipos de erro, traces e erros recentes, e um resumo de spans. O resumo lê 20 traces da operação espalhados pela janela e lista de onde vieram as requisições dela (a requisição mais próxima acima de cada uma, ou nenhuma quando ela inicia o próprio trace) e o que elas rodaram, por serviço e operação: spans por requisição, a parcela das requisições que rodou cada um, a duração média e o tempo próprio dentro da requisição (sem o dos filhos) como parcela do tempo próprio dela, na média das requisições, então um stream que uma requisição deixou aberto conta como essa requisição só. Uma linha abre a página dessa operação, então você sobe ou desce pelas chamadas. É uma amostra: um ramo raro pode faltar nela.Mapa de serviços (
/deck/apm/map): serviços, bancos de dados, filas e chamadas externas aparecem como nós, e as chamadas como arestas com taxa, taxa de erros e p95; uma aresta fica vermelha a partir de 5% de erros. Quando spans ficaram sem par na janela, a resposta do mapa dizpartial: truecomunpairedSpans, porque as arestas contam a menos. Acima de 300 nós, o Deck desenha os 300 mais movimentados e informa quantos ficaram de fora; Mapa de serviços, na página de um serviço, desenha esse serviço e seus vizinhos primeiro. A largura de uma aresta são todas as chamadas dela; o texto sobre ela e o painel de um nó mostram primeiro as feitas dentro de uma requisição e nomeiam o resto como segundo plano.Traces raiz (
/deck/apm/traces, a lista padrão): os traces que uma requisição iniciou, cujo span raiz é de servidor ou de consumidor, com busca pela barra de consulta descrita abaixo. Sob a barra, os traces por intervalo em colunas empilhadas, sem falha em cinza e com falha em vermelho, com a taxa de falha como uma linha no seu próprio eixo à direita; um clique numa coluna estreita a janela para ela, e um clique numa linha também filtra pelo valor que ela desenha. Os controles se leem como uma frase, Mostrar [medida] por [chave] top [n] a cada [intervalo], para a taxa de erro ou um percentil de duração, no total ou por serviço, operação raiz, pod, nó, versão, rota ou tipo de erro; por uma chave, como linhas ao longo do tempo ou como um ranking da janela inteira, ordenado pela medida. O histograma de duração, o gráfico de dispersão da duração ao longo do tempo, o heatmap de latência (abaixo) e a comparação com os traces sem falha abrem em Gráficos, na linha acima dos resultados, que também traz as descobertas; o navegador lembra se você os deixou abertos. Um trace cujo span raiz é de cliente, de produtor ou interno não teve requisição por trás: um worker de fila consultando o Redis, a consulta de um cron, um heartbeat. Essas chamadas em segundo plano ficam ocultas por padrão, porque num cluster movimentado elas superam as requisições muitas vezes. Um link acima da lista diz quantas ficaram ocultas e as mostra com um clique (?background=1). Cada linha cujo span raiz não é de servidor diz o tipo dele. Um engine anterior ao Addendum v0.27 não informa o tipo do span raiz: a página então lista todos os traces, sem tipo e sem esse link, e avisa isso.Visões salvas, ao lado de Buscar nas duas listas: as visões da equipe para esta página, como no Logs (
logs.md→ "Visões salvas").Todos os spans (
/deck/apm/traces?scope=spans): os spans guardados um a um, do mais recente ao mais antigo, 100 por página, com os mesmos filtros, mais o tipo de span e sem a duração máxima. Spans mais antigos leva a página para logo antes do span mais antigo mostrado. Cada linha abre o trace dela já nesse span.Barra de consulta: digite filtros como
key:value, separados por espaço; todos precisam valer. Cada um vira um chip embaixo da barra: selecione o chip para editá-lo, o menos dele para excluí-lo e o x para removê-lo.service:,operation:,status:errorouok,duration:>100mseduration:<2s(unidades ns, us, ms, s, m, h; dois chips formam um intervalo) e, em Todos os spans,kind:são chaves com nome; qualquer outra chave é um atributo do span ou do recurso, comohttp.route:/api/cartouuser.tier:"gold plus". O sinal de menos exclui um atributo (-http.response.status_code:200) ou um serviço (-service:frontend): saem os traces em que algum span o tem. Até 8 atributos para atender e 8 para excluir. O@duration:>100msdo Datadog funciona comoduration:, oenv:prodlê odeployment.environment.namedo recurso e oresource_name:o nome do span; ooperation_name:não existe nos spans OpenTelemetry e é recusado. Curingas, comparações em atributos (http.response.status_code:>=500) e texto livre são recusados com o motivo: o motor indexa pares exatos de chave e valor. Entre aspas, o valor vale como está escrito,*incluído (http.accept:"*/*"). A lista conta as correspondências durante até 0,4 s; passado isso, mostra as mais recentes com exatidão e diz "mais de N". Trocar entre Traces raiz e Todos os spans mantém os termos que a outra visão aceita e descarta o resto (kind:, uma duração máxima). O Tab completa chaves e valores: serviços e operações da janela, atributos dos 200 spans mais recentes dela. A consulta fica na URL (?q=), então voltar, avançar e um link colado repetem a busca; links que ainda trazem?service=,?attr=k=ve os outros parâmetros antigos abrem como chips. Cada valor de faceta acrescenta o chip dele com um clique, e o menos ao lado acrescenta a exclusão.Um trace (
/deck/apm/traces/<id>): três visões de um trace, cada uma desenhando só o que está na tela. A Cascata mostra os spans em árvore, com o caminho crítico e um minimapa para dar zoom, que marca em vermelho cada span com falha. No Flame graph, spans que rodaram ao mesmo tempo se empilham, então nenhum se esconde atrás de outro; a rolagem aproxima em torno do ponteiro, Shift+rolagem ou um deslize lateral move no tempo, e arrastar desloca nos dois sentidos. Operações é o trace por serviço e operação, com chamadas, média, a mais lenta, tempo próprio e tempo no caminho crítico. Uma linha com 10 ou mais chamadas sob um mesmo pai diz isso, que é a cara de um N+1, e um clique na linha encontra os spans dela na cascata. A visão fica na URL (?view=flame).Comparar com, em Operações, aceita o id de outro trace, ou Um trace típico, o trace mediano sem erros da mesma operação raiz, numa amostra uniforme de até 200 da hora em torno deste. O caminho crítico atravessa as raízes do trace, órfãos inclusive, da última a terminar para trás; com o tempo que nenhuma raiz cobre, mostrado em uma linha própria, soma a duração do trace, então as diferenças por operação dizem onde um trace lento gastou o que o outro não gastou. As operações se pareiam por serviço e nome exatos, então um nome com um id dentro aparece como uma que sumiu e uma nova. A comparação fica na URL (
?compare=<id>).A busca aceita uma palavra, ou os termos do explorador:
service:cart,operation:"GET /cart",status:error,kind:client,duration:>100ms, qualquer atributo comokey:value, e um sinal de menos para excluir em qualquer um deles. Ela lê os próprios spans, então aceita também o que o motor do explorador não aceita:http.status_code:>=500,OR,NOT, parênteses e a forma de grupo do Datadog,service:(cart OR payment). Um termo que ela não sabe responder (status:foo, um curinga, um intervalo entre colchetes) diz isso. Tempo próprio colore as barras pelo tempo que cada span gastou sozinho. Erros raiz percorre os spans com falha sob os quais nada mais falhou. Recolher até os saltos entre serviços, ao lado de expandir e recolher, deixa uma linha por salto nos dois gráficos; uma barra recolhida diz quantos spans guarda. Teclas, com um dos gráficos em foco: setas percorrem (no flame graph, para cima o pai, para baixo o primeiro filho, esquerda e direita os irmãos, então spans que rodaram ao mesmo tempo ficam a uma tecla de distância), Enter abre, Z aproxima o span, 0 mostra o trace inteiro, E vai ao próximo erro raiz, / busca e, no flame graph, + e - mudam o zoom.O painel de um span mostra os atributos agrupados por namespace, os eventos, o recurso e a infraestrutura. Cada atributo copia o valor, encontra neste trace os spans que o têm e busca no explorador com ou sem ele. Ao percorrer spans com o painel aberto, os logs e a infraestrutura do span só são lidos depois que o cursor para por 250 ms. Um cotovelo tracejado antes de um span indica que o orbit-probe inferiu o pai dele (
orbit.linkvalesingleouroute); passe o mouse no ícone de vínculo ao lado para ler como. O painel mostra como o span foi vinculado e o processo que o executou: executável,process.pidethread.id.Quem chamou isto? Quando o span raiz de um trace é de cliente, de produtor ou interno, a página do trace consulta
GET /api/v1/spansatrás das requisições que o mesmo processo (mesmosk8s.pod.nameeprocess.pid) atendia quando esse span começou, e dos outros spans desse processo até 2 s antes e depois, cada um com link para o trace dele. Quando o processo não atendia nenhuma requisição, a página diz isso e cita o executável: a chamada é trabalho em segundo plano, como um job agendado, um timer ou um worker de fila. Aqui, requisição é um span de servidor, ou um span FastCGI, que o orbit-probe marca como interno quando nginx e php-fpm dividem um pod. O painel procura até 60 s para trás uma requisição ainda em andamento. Um trace que começa numa requisição não faz nenhuma dessas leituras.Relacionados: uma linha de links no painel de um span, de um serviço, de um workload, de um pod, do terminal de um pod (cada um em nova aba, para o shell continuar aberto), de um node e de um alerta, para os outros sinais do mesmo objeto e da mesma janela: os logs dele (os de um span por
trace_id, os de um pod pornamespaceepod, os de um serviço porservice, os de um workload pornamespacee pelo nome dos pods dele ou do serviço dele, o que achar mais (as linhas de um arquivo não citam pod; a página de um serviço tenta os pods do workload do mesmo jeito), os de um node pornode; um alerta num node abre os do node) com contagem e erros, os traces com contagem de requisições e de erros (o link de um pod filtra pork8s.pod.namee não tem contagem, que seria a do serviço inteiro), a página do serviço (num pod ou num alerta, o serviço cujos spans citam aquele pod ou workload emk8s.pod.nameouk8s.deployment.namenotraces_target_info; a linha diz isso, sem link de traces, quando nenhum span cita; um worker ou cron sem span de servidor ou consumidor mantém o link, sem contagem), as páginas do workload, do pod e do node, os eventos do Kubernetes com os avisos, e os alertas disparados nele. A janela de um span cobre 15 minutos de cada lado dele; a de um alerta, 15 minutos de cada lado do disparo; as outras páginas usam a da barra superior. Os links aparecem na hora; uma única chamada ao servidor preenche as contagens. A linha de um span acrescenta as linhas daquele span com a contagem, quando ele escreveu alguma, e as do pod ou do serviço dele na mesma janela, e diz quando nenhuma linha traz o id do trace. Um papel semlogs.readouapm.readnão vê link para aquele sinal. Quando não dá para ler otraces_target_info, ou o papel não temtelemetry.query, um pod fica sem link de serviço e mantém o link de traces; um workload fica sem link de traces.
Releases de um Deployment
A aba Releases da página de um Deployment (?tab=releases) responde "esta revisão piorou
alguma coisa, e onde?" sem label de versão. Ela exige apm.read, um cluster ao vivo e o switch
apm; os switches rollback e workload_changes não mexem nela, então uma instalação só de
leitura continua com ela.
- Uma linha por revisão guardada, da mais nova para a mais antiga, a partir dos ReplicaSets do Deployment.
- Uma linha do tempo única de implantações. Cada número de revisão que um ReplicaSet guardado
teve é uma implantação: o atual e os de
deployment.kubernetes.io/revision-history, que o controller escreve quando reaproveita um ReplicaSet (um rollback, ou um template aplicado de novo). A primeira implantação de um ReplicaSet é a criação dele. Uma posterior é quando os pods dele voltaram, no segundo do próprio pod, ou, quando nunca saíram porque a revisão anterior travou (um crash loop que o rolling update não deixou substituí-los), quando os pods dessa revisão sumiram todos, na última coleta (kube_pod_createde a última leitura de cada pod). Essa linha leva a tag reaplicada. Quando o engine não guarda mais esses pods, a linha fica sem números. - As janelas. Antes é o que rodou a revisão substituída, depois é o que rodou esta revisão, 30
minutos no máximo de cada lado, e o depois nunca passa de agora. Uma implantação que se fundiu num
número de revisão posterior ainda encerra o que rodou antes dela, então um undo aplicado depois
não muda uma linha mais antiga. O que rodou antes da revisão guardada mais antiga começa no primeiro
pod do ReplicaSet que o controller já apagou (
kube_pod_created). Os números de spans ignoram o primeiro minuto de cada lado, enquanto a revisão anterior ainda responde, então um undo lido minutos depois não herda a cauda dos pods lentos. As leituras voltam até 15 dias. - Os números, para cada serviço cujos spans nomeiam o workload (
traces_target_info, pelok8s.deployment.nameou pelos nomes dos pods): requisições e taxa de erro dos spans de entrada (server e consumer, como na página do serviço), a taxa de 4xx dos spans server (traces_spanmetrics_http_4xx_total; um traço onde o engine não as contava no começo da janela), o p95, os reinícios dos pods do Deployment (kube-state-metrics) e as linhas de erro novas: mensagens com 5 linhas ou mais depois da implantação e nenhuma nos 30 minutos antes, o que quer que tenha rodado nesses 30. As linhas de erro só são lidas para um papel comlogs.read, com os logs guardados ligados. - Rotas, abaixo da linha: operações de entrada que apareceram (5 chamadas ou mais, nenhuma antes), que sumiram (5 ou mais esperadas na janela depois e menos de um décimo delas veio, porque os pods antigos ainda respondem durante o rollout) ou que dobraram a taxa de 4xx além da régua abaixo.
- O veredito usa as réguas do
errors_after_rollout. Uma taxa piorou com 100 requisições ou mais dos dois lados, 5 falhas ou mais depois, em 1% ou mais, o dobro da taxa de antes e 3 desvios padrão acima dela; a latência piorou com o dobro do p95 de antes e mais 100 ms, salvo quando a revisão substituída falhava (5% ou mais de erros e 4xx, que falham rápido) e esta deixou metade disso ou menos; os reinícios, quando a janela depois tem mais. O 4xx de uma rota só conta com 100 chamadas depois, uma taxa ao menos 1 ponto maior e a taxa de 4xx do próprio serviço sem cair; fora isso ela fica na lista como evidência. Piorou diz o que piorou. Sem piora exige 100 requisições dos dois lados de um serviço; com menos a linha diz isso, sem requisição nenhuma dos dois lados ela diz Sem spans de entrada, e sem janela para ler, Sem dados. - Copiar põe a linha na área de transferência como texto puro para um ticket: a revisão, quando foi implantada, a imagem, o veredito, cada número e rota, e as duas janelas.
Nada na aba abre sozinho, e ela não gera achado.
O heatmap de latência
A visão Heatmap de Traces raiz (?chart=heatmap) e o painel de latência da página de
um serviço mostram a duração dos spans ao longo da janela: uma coluna por passo de tempo, uma
linha por bucket de latência num eixo logarítmico, e cada célula com a cor de quantos spans
caíram nela, numa escala logarítmica cuja legenda mostra a faixa. Ele conta todos os spans,
seja o que for que as regras de ingestão guardaram, porque lê as métricas de span
(ingestion.md):
- Com um serviço na consulta, os spans de servidor e de consumidor desse serviço, filtrados
por
operation:estatus:. Na página de um serviço, o serviço inteiro ou a operação escolhida acima do gráfico (?op=); para um serviço em segundo plano, as chamadas de cliente e de produtor dele. - Sem serviço, as requisições que entram no sistema: as chamadas vindas de
userno grafo de serviços. - Uma duração na consulta aparece contornada no heatmap, sem ser tirada dele, para o resto da distribuição continuar à vista.
- Um atributo (ou
operation:oustatus:sem serviço) é algo que as métricas de span não rotulam. O heatmap passa então a contar os traces armazenados que a lista encontraria, numa única passada pela janela, e avisa isso abaixo do gráfico; uma passada que esgota o tempo avisa que as contagens são um piso.
Passe o mouse sobre uma célula para ler o horário, a faixa de duração e a contagem dela.
Clique numa célula, ou arraste um retângulo sobre várias, e a lista se restringe àqueles
minutos e àquela faixa de duração: o intervalo de tempo na barra superior (o de uma célula
só é alargado para dois minutos em volta dela), e duration:> e duration:< na consulta.
Pelo teclado o gráfico é uma única parada de tabulação: as setas andam entre as células,
Shift com as setas seleciona um retângulo, Enter o abre e Escape o descarta; um leitor de
tela anuncia cada célula. A lista traz só traces armazenados: quando as regras de ingestão
descartaram spans nos últimos 5 minutos, na última hora ou no último dia do engine (o que
estiver mais perto da janela), a linha abaixo do gráfico informa a parcela que elas
mantiveram.
Uma janela ganha cerca de 120 colunas: passos de 30 s para uma hora, de 15 minutos para um
dia, de 2 horas para uma semana, nunca mais finos que os 15 s em que as métricas de span
são gravadas. A rota é GET /api/v1/apm/heatmap (api.md).
Stack traces com link para o código
Onde houver um stack trace, num evento exception de um span (exception.stacktrace) ou numa
linha de log (a mensagem, o atributo exception.stacktrace, error.stack ou stack_trace, ou
qualquer campo de texto de uma mensagem JSON, inclusive o array trace do Monolog), o Deck
transforma cada frame num link para o arquivo e a linha no repositório, como a Source Code
Integration do Datadog. Ele lê PHP (getTraceAsString, as mensagens do próprio PHP no formato
in /path.php:12, as entradas path:line do Monolog e o
at App.Services.PaymentService.charge(PaymentService.php:87) do SDK PHP do OpenTelemetry),
Java, Kotlin e Scala, Python, Node.js, Go, .NET e Ruby.
- Qual commit. O
vcs.repository.url.fulle ovcs.ref.head.revision(OpenTelemetry) do próprio span ou log, ou ogit.repository_urle ogit.commit.shado Datadog, no recurso ou no registro. Para um serviço que não envia nenhum deles, um admin informa o repositório e a branch em Integrações, Código-fonte. - Qual arquivo. O caminho do frame sem o diretório para onde a imagem copiou o repositório:
o informado para o serviço (Caminho no contêiner), senão um dos comuns (
/var/www/html,/app,/usr/src/app,/src,/build,/go/src/app; a lista completa éROOTSemapps/web/src/lib/stack.ts), um caminho de módulo Go ou de GOPATH com o nome do próprio repositório, ou um checkout do GitHub Actions ou do Azure Pipelines. Um frame da JVM cita uma classe, então o arquivo é o caminho do pacote sobsrc/main/java(src/main/kotlin,src/main/scala). O SDK PHP do OpenTelemetry escreve só a classe e o nome do arquivo, então o Deck monta o caminho pelos namespaces do Laravel:App\emapp/(num trace com frames do Laravel; Symfony e Slim guardamApp\emsrc/),Database\Seeders\eDatabase\Factories\emdatabase/,Tests\emtests/. Qualquer outro namespace (Modules\, um pacote fora da lista de terceiros) só ganha link pela lista de arquivos do repositório, com um token do GitHub.{main}fica empublic/index.phpouartisan; uma closure fora de classe ou noRouteFileRegistrardo Laravel, emroutes/web.phpouroutes/api.php; uma closure deroutes/console.php(Artisan::command,Schedule::call) cita oKernelde console ou oClosureCommanddo Laravel e ganha link para lá. Um método de trait cita a classe que usa o trait e o arquivo do trait: os traits do próprio Laravel (AuthorizesRequests,Notifiablee outros; a lista éPHP_VENDOR_TRAIT) contam como código de terceiros, e qualquer outro só ganha link pela lista de arquivos do repositório, com um token do GitHub. O Diretório no repositório entra na frente do resultado, para monorepo ou módulo Maven. - Código de terceiros. Frames em
vendor/,node_modules/,site-packages/, gems, no cache de módulos e na biblioteca padrão do Go, no JDK e nos frameworks comuns da JVM,System.ouMicrosoft.no .NET, namespaces PHP de pacotes comuns (Illuminate,Symfony,GuzzleHttp,Doctrine,Monologe outros; a lista éPHP_VENDOR_NSemapps/web/src/lib/stack.ts), funções e classes do próprio PHP, views Blade compiladas e código deeval()ficam como texto esmaecido, sem link. - O código na tela. Com um token do GitHub salvo em Integrações, cada frame com link ganha
um ícone que mostra as 11 linhas em volta, que o orbit-api lê de
api.github.comnaquele commit. O orbit-api sela o token comORBIT_SEAL_KEY, nunca o devolve e só o envia paraapi.github.com; um frame de outro host ganha link, mas não código. O orbit-api só lê um repositório vinculado a um serviço em Integrações, Código-fonte, no ref que esse serviço define (qualquer ref quando não define nenhum) ou num id de commit completo, o que a telemetria traz do build. Um repositório que a telemetria nomeia e nenhum serviço vincula ganha links, mas não código: vincule-o para ver o código. Use um token fine-grained só com leitura de Contents dos repositórios que você vincular: qualquer papel comapm.readoulogs.readlê o código deles por ele. - A lista de arquivos do repositório. Com o token, o orbit-api também lê a lista de arquivos do repositório naquele commit, e cada frame aponta para o arquivo que tem o maior final de caminho em comum com ele: um módulo Maven, um diretório de monorepo ou um WORKDIR incomum dispensam configuração, e um frame cujo arquivo não está no repositório (um pacote de terceiros na JVM, por exemplo) fica sem link. Num empate entre dois arquivos, vence o que está sob o Diretório no repositório do serviço; sem diretório, ou sem nenhum deles sob ele, o frame fica sem link.
URLs do GitHub, do GitLab, do Bitbucket e do Azure DevOps (https) viram link; só o GitHub mostra o código na tela. O
parser lê no máximo 256 KiB de texto e pula linhas com mais de 4 KiB, então texto hostil custa
tempo linear. Um frame de TypeScript ou de JavaScript empacotado aponta para o arquivo compilado
(dist/...): o Deck não lê source maps.
As rotas: GET /api/v1/source (apm.read ou logs.read) devolve os serviços e se há token;
PUT /api/v1/source (settings.manage, auditada) salva; GET /api/v1/source/snippet?repo=&ref=&path=&line= (apm.read ou logs.read) devolve
{"path", "start", "lines"}; POST /api/v1/source/resolve (apm.read ou logs.read) recebe
{"repo", "ref", "dir", "files"} (no máximo 200 arquivos) e devolve {"paths"}, o caminho de
cada arquivo no repositório ou null (também quando mais de 256 arquivos do repositório têm o
mesmo nome). As duas devolvem 403, antes de qualquer chamada ao GitHub, para um repositório ou
ref que nenhum serviço vincula.
As mesmas leituras pela API são as rotas apm.read descritas em api.md.
O tempo de um span é epoch em microssegundos (startUs, durationUs); todos os outros
tempos dessas rotas são epoch em milissegundos.
SLOs de serviço
O cabeçalho da página de um serviço traz Definir SLO para um papel com settings.manage,
num serviço que recebeu requisições na janela (um worker ou um gerador de carga não tem o que
manter). Um SLO é uma meta de disponibilidade para um serviço: a parte das requisições de entrada
(spans server e consumer, as que as páginas dele contam) que termina sem erro nos últimos 7
dias, que cabem nos 15 dias de métricas do engine. O cabeçalho passa a mostrar "SLO 99,5% em
7 d: 99,93%, orçamento restante 86%", e a coluna SLO 7 d de Serviços mostra a mesma
parte com o orçamento embaixo; um serviço sem SLO deixa as duas vazias. Os dois números são
cortados para baixo, nunca arredondados para cima: 98,996% de uma meta de 99% aparece como
98,99%, e um orçamento que acabou de estourar aparece como -0,4%, não 0%. Enquanto os dados
cobrem menos que os 7 dias (um serviço novo, um engine recém-instalado), o cabeçalho diz quanto:
"SLO 99,5% em 7 d, com 3 h de dados: ...", com o início lido na hora cheia. O orçamento é 100%
menos a meta, e o que resta é 1 menos a parte com falha sobre o orçamento, abaixo de 0 quando a
semana o gastou.
Salvar grava duas regras nas regras de alerta PromQL (mcp.md),
os alertas de burn rate em várias janelas do workbook de SRE do Google, em que um burn rate de
1 gasta o orçamento exatamente na janela:
| Regra | Dispara quando a parte com falha sobre o orçamento passa de | Severidade |
|---|---|---|
slo-<id>-fast | 14,4 na última hora e nos últimos 5 minutos | critical |
slo-<id>-slow | 6 nas últimas 6 horas e nos últimos 30 minutos | critical |
As duas acionam o plantão, como a queima rápida do Grafana SLO: em 7 dias, a regra rápida
dispara quando uma hora gastou 8,6% do orçamento da semana, e a lenta quando 6 horas gastaram
21%. Cada uma leva slo: <id> e se chama SLO <service>: 14.4x 1h/5m (ou 6x 6h/30m). O
valor do alerta é o burn rate na janela longa, e ele leva o namespace do serviço, que as
páginas do APM mostram e o salvamento lê, então um canal de notificação restrito a esse
namespace o recebe; o canal diz o burn rate no próprio idioma. Em Alertas, a linha dele abre
o serviço e os logs do serviço. Salvar o SLO de novo reescreve as duas regras (e lê o namespace
de novo) e mantém desligada a que alguém desligou; removê-lo apaga as duas.
Em Observabilidade, Consumo do orçamento de erro desenha o burn rate de cada SLO na
última hora, uma linha por serviço, e avisa quando o cluster não tem SLO. Os painéis de
latência e de taxa de requisições e o Requisições da Visão geral leem as span metrics
quando nenhuma app exporta http_requests_total.
As rotas: GET /api/v1/alerting/slos (apm.read) devolve cada SLO com namespace, window,
requests, errors, sli e budget (null sem requisição na janela), since (a hora em que
os dados dele começam na janela, em ms Unix), e error quando o engine do cluster dele não
respondeu. PUT /api/v1/alerting/slos (settings.manage) recebe {cluster, service, target},
com target de 0,5 a 0,99999, e cria ou substitui o SLO do serviço. DELETE /api/v1/alerting/slos/{id} remove o SLO e as duas regras. Um console guarda 50 SLOs, e as
regras deles contam nas 200 regras de alerta. Cada gravação e remoção é um evento de
auditoria, slo.create, slo.update ou slo.delete, que nomeia as regras.
Armazenamento e retenção
| Variável | Padrão | O que faz |
|---|---|---|
ORBIT_STACK_TRACE_RETENTION | 7d | Um segmento de trace é apagado inteiro quando o seu último span chegou há mais tempo que isso. Em dias ou como duração do Go. |
ORBIT_STACK_TRACE_HEAD_BYTES | 64MiB | Spans mantidos na memória antes de serem gravados como um segmento. O cache de leitura de traces descomprimidos recebe metade desse orçamento e os bytes de requisições OTLP em andamento, o mesmo orçamento, então os traces somam cerca de duas vezes e meia esse valor à memória do engine. No mínimo 1MiB. |
ORBIT_STACK_TRACE_MAX_BYTES | 5MiB | Um trace no head, o default de max_bytes_per_trace do Tempo: os spans que passam disso são recusados um a um. De 64 KiB até a metade de ORBIT_STACK_TRACE_HEAD_BYTES. |
ORBIT_STACK_TRACE_GRAPH_PENDING | 100000 | Spans à espera do outro lado de uma aresta do service graph, de 1.000 a 10.000.000; acima disso, ficam sem par e o mapa de serviços avisa. |
Os spans vão primeiro para um write-ahead log e depois para o head na memória; o head vira
um segmento imutável quando chega a ORBIT_STACK_TRACE_HEAD_BYTES ou completa 15 minutos, o
que acontecer primeiro. Um segmento, na versão 2 do formato, guarda traces inteiros como
frames zstd em ordem de início, resumos em chunks com um zone map cada, uma tabela de ids
ordenada e um bloom filter, cada parte com o seu checksum. Um segmento que o engine não
consegue ler, incluindo um segmento da versão 1 da primeira release de traces, é pulado pelo
nome na inicialização (a linha de log trace segment skipped diz o arquivo), contado e
deixado no disco para você apagar; o write-ahead log é reprocessado seja qual for a versão
dele. Tudo fica em ORBIT_STACK_DATA_DIR/traces, no volume do engine, ao lado dos blocos de
métricas. Ao lado de cada segmento o engine mantém agg-<seq>, os agregados dele: por
serviço, span de entrada e status, quantos traces ele guarda e os poucos que uma busca
aproveita, então uma busca com total ou com amostra espalhada lê um segmento que a janela
cobre inteiro sem decodificá-lo (cerca de 5% dos bytes do segmento no disco, alguns KiB de
memória por segmento). O arquivo é reconstruído a partir do segmento quando falta ou não
passa na verificação, e o engine em Go o ignora, então o rollback continua funcionando; um
que a retenção do engine em Go deixou para trás é apagado na inicialização seguinte. POST /-/flush grava na hora as span metrics e o head. Dimensione o volume a
partir do seu próprio tráfego: o GET /api/v1/status/tsdb reporta segmentBytes e
segmentSpans sob traces, o que dá os seus bytes por span; multiplique pela sua taxa de
spans e pela retenção.
Métricas para acompanhar, no listener de métricas do engine: orbit_stack_spans_total{outcome}
(accepted, rejected), orbit_stack_trace_head_bytes, orbit_stack_trace_head_spans,
orbit_stack_trace_segments, orbit_stack_trace_segment_bytes,
orbit_stack_trace_wal_bytes, orbit_stack_trace_cache_bytes,
orbit_stack_trace_skipped_segments, orbit_stack_trace_cuts_total,
orbit_stack_trace_cut_failures_total, orbit_stack_trace_wal_truncations_total e
orbit_stack_trace_generator_dropped_total. GET /api/v1/status/tsdb traz os mesmos
números sob traces.
A loja de demonstração
O orbit-shop, que vem na imagem do orbit-stack como /orbit-shop, é uma pequena loja
feita de serviços HTTP de verdade, que se chamam entre si propagando o traceparent do W3C e
exportam OTLP para o engine, de modo que as páginas de APM têm traces que passaram pelo
pipeline real:
web-frontendchamaapi-gateway, que chamaauthem toda requisição e depoiscatalog(que consulta opostgres),cart(que fala com oredis) oucheckout.checkoutchamapayment(que chamastripe-api, um peer externo que não envia spans); aprovada a cobrança, ocheckoutpublica no tópico Kafkaorders, que ofulfillment-workerconsome antes de gravar nopostgres.paymentfalha numa pequena parte das cobranças (um timeout do gateway ou um cartão recusado),cartresponde um500de vez em quando, num timeout do pool do Redis, e, durante um minuto a cada dez, um terço das consultas docatalogpega um plano lento: sempre há alguma coisa para encontrar.- Um gerador de carga exercita o
web-frontendcomo fariam compradores de verdade: a maioria só navega, alguns montam carrinho e menos ainda fecham a compra, a--rpsrequisições por segundo (padrão 5); cada requisição é um trace.
| Caminho de instalação | Como roda | Controle |
|---|---|---|
| Compose | O serviço orbit-shop, orbit-shop --all: todos os serviços num só processo, de 127.0.0.1:18110 a 18117, com dois pods fictícios cada | Ligado por padrão. ORBIT_SHOP_RPS no .env define a taxa; docker compose --project-name sreorbit --env-file .env -f deploy/compose/docker-compose.yml stop orbit-shop o desliga. |
| Helm | Um Deployment e um Service por serviço, mais um Deployment para o gerador de carga, e cada pod se identifica pela downward API | demo.shop.enabled (padrão false), demo.shop.rps (padrão 5), demo.shop.resources |
| Manifestos puros | Não incluída | nenhum |
No Helm:
helm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \ --set demo.shop.enabled=true --set demo.shop.rps=5O chart recusa demo.shop.enabled sem components.orbit-stack.enabled. Os pods da loja
usam o bearer do engine que está no Secret da release, e uma NetworkPolicy os deixa alcançar
uns aos outros na 8080 e o engine na 8082, e nada além disso. São carga que você não
pediu, e é por isso que o chart os deixa desligados.
APM sem tocar nas aplicações, pelo chart Helm
Dois blocos do values.yaml do chart, ambos desligados por padrão, enviam traces sem mudar
nada nas aplicações. O apm.collector é um OpenTelemetry Collector em
<release>-otel-collector, nas portas 4317 e 4318, que repassa a este engine: por padrão,
o orbit-collector, o coletor em Rust (apm.collector.engine: orbit); upstream roda o
otelcol-k8s atrás do mesmo Service, das mesmas portas e do mesmo pipeline. O orbit-collector
segura no máximo um quinto do seu limite de memória (64 MiB no mínimo) em bytes de requisição
ao mesmo tempo, como chegaram e descomprimidos; uma requisição além disso recebe 503, ou
UNAVAILABLE no gRPC, e o exporter a reenvia. Uma requisição cujos recursos, escopos e spans
ocupariam mais de quatro vezes o tamanho dela depois de separados (um vazio tem dois bytes)
recebe 400, ou INTERNAL no gRPC, como uma que não se decodifica.
O orbit-collector identifica quem mandou um span pelo endereço da conexão. Um pod no
namespace de node do release (orbit-probe, OBI, orbit-node) ou em
apm.collector.orbit.trustedNamespaces reporta por outros pods, então o coletor acha o pod
pelos próprios k8s.pod.uid, k8s.pod.name e k8s.namespace.name do span, como faz o
k8sattributes do upstream; o OBI na rede do host (contextPropagation) vale pelo endereço do
seu node. Qualquer outro remetente recebe o pod, o namespace, o workload e o node do pod
naquele endereço, digam o que disserem os spans: o coletor descarta todo atributo k8s.* que
veio e grava os dele, e troca o service.name a menos que o spec do pod declare esse nome
(Segurança). Um remetente
fora do cluster fica sem nenhum deles, e um na rede do host também, a menos que um pod
hostNetwork de um namespace confiável rode no node dele: apm.autoInstrument.contextPropagation
(OBI) e telemetry.nodeExporter.engine: upstream põem um em cada node que cobrem. A partir
daí, qualquer pod hostNetwork desse node conecta pelo endereço do node e mantém os atributos
que o payload nomeia. Mantenha os namespaces das aplicações em Pod Security baseline ou mais
restrito, que recusa hostNetwork, para que só o namespace de node do release rode pods na rede
do host. Ponha em trustedNamespaces o namespace
de um gateway Collector seu que encaminhe spans de outros pods. Deixe o pod do coletor fora de
um service mesh: um sidecar na frente dele conecta pelo próprio endereço, e todo remetente
perderia o seu pod. Com apm.collector.engine: upstream vale a associação do próprio otelcol, que
acredita no pod que o payload nomeia.
Atributos de span com nome orbit.* e um telemetry.sdk.name igual a orbit-probe no recurso
são do orbit-probe: o engine costura traces por eles. O coletor os descarta de qualquer
remetente em que não confia, para que uma aplicação não consiga mover o trace de outro serviço
para dentro do seu com orbit.hop.trace_id, definir ela mesma o orbit.sql.signature nem se
passar pelo probe.
O
apm.autoInstrument roda um DaemonSet eBPF no namespace de node do release, que transforma em
spans as chamadas de cada processo dos namespaces escolhidos e as envia a esse coletor. Ele
tem dois engines e renderiza exatamente um:
apm.autoInstrument.engine | DaemonSet | O que vira span |
|---|---|---|
orbit (o padrão) | <release>-orbit-probe: o orbit-probe, instrumentação eBPF em Rust (services/rust/orbit-probe) | HTTP/1.1, HTTP/2 e gRPC, FastCGI, PostgreSQL, MySQL e Redis, em texto puro ou dentro de TLS feito pelo OpenSSL |
obi | <release>-obi: o OpenTelemetry eBPF Instrumentation (OBI) v1.0.0 | Os mesmos protocolos, mais os outros que o OBI conhece |
Os dois exigem Linux 5.8 ou mais recente com BTF (/sys/kernel/btf/vmlinux) em todos os
nodes; os kernels do AL2023 e do Bottlerocket já trazem isso. Os dois enviam traces e nada
mais. namespaces, excludeNamespaces, excludeExecutables, privileged, healthPort,
logLevel e as chaves de agendamento valem para qualquer um dos engines.
contextPropagation, extraCapabilities, goMemLimit, mapsScaleFactor e resources são
do OBI; com engine: orbit, o chart recusa os dois primeiros. Trocar de engine é um valor só:
o Helm remove um DaemonSet e cria o outro.
helm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \ --set apm.autoInstrument.engine=obiTrês padrões mantêm o DaemonSet barato e o mapa de serviços legível:
| Valor | Padrão | Efeito |
|---|---|---|
apm.autoInstrument.excludeExecutables | shells, su e sudo, wrappers de processo, busybox, coreutils | Globs sobre o caminho resolvido do executável que nenhum dos engines instrumenta, em nenhum namespace. */busybox cobre todos os applets. Nenhum runtime de linguagem ou servidor entra na lista. |
apm.autoInstrument.goMemLimit | 96MiB | Só no OBI: o GOMEMLIMIT do heap Go dele. Os mapas eBPF são memória do kernel, fora dele. Uma string vazia mantém o padrão do Go. |
apm.collector.dropRedisCommands | BLPOP, BRPOP, BLMPOP, BLMOVE, BRPOPLPUSH, BZPOPMIN, BZPOPMAX, BZMPOP, XREAD, XREADGROUP | Spans de Redis que o collector descarta, por comando: os pops bloqueantes em que um worker de fila ou um job de cron fica em loop. XREAD e XREADGROUP só saem com BLOCK, quando o span traz o texto da consulta. [] mantém todos os spans. |
apm.collector.replicaCount | 1 | Pods do collector atrás do Service, em qualquer engine. Um pod não guarda nada entre requisições; com dois ou mais, o chart os espalha por nodes (a regra kubernetes.io/hostname de topologySpread, na zona do orbit-stack) e cria um PodDisruptionBudget de um: perder um node não deixa buraco em traces nem em logs. O values-prod.yaml define 2. |
Os dois engines convertem os endereços dos pares em nomes primeiro pelos informers do Kubernetes, Services e pods, e depois por DNS reverso. Um banco ou cache dentro do cluster aparece com o nome do Service, um gerenciado com o nome DNS quando o endereço tem registro PTR, e só um endereço sem nenhum dos dois fica como IP puro.
orbit-probe (engine: orbit)
- Dentro do kernel: programas fentry e fexit onde o BTF do kernel permite, kprobes nos
demais casos, em
tcp_sendmsg,tcp_recvmsg,inet_csk_accept,tcp_connectetcp_close. Com kprobes, uma recepção se perde enquanto houver mais threads bloqueadas em recepção do que cabem no pool de kretprobes do kernel (uma por CPU sem preempção de kernel); o log do pod diz quando ele anexou assim. Os bytes chegam ao agente por um ring buffer por node,apm.autoInstrument.orbit.ringbufBytes(4 MiB por padrão). Um processo fora dos cgroups dos contêineres instrumentados não envia nada: esse filtro roda dentro do kernel. - Spans: um span de servidor por requisição que um processo atende e um span de cliente
por requisição que ele faz, com os nomes que o OBI dá (
GET /api/users/{id},SELECT orders,/pkg.Svc/Method) e os atributos das convenções semânticas que este engine lê. Cada span levathread.id; o recurso de cada processo levaprocess.pideprocess.executable.name. Odb.query.textde um span SQL é o statement com cada literal trocado por?e sem os comentários. Ele fica vazio quando a palavra-chave que dá nome ao span está dentro de uma string, de um comentário ou de um nome, e termina numa string que contém uma barra invertida ou num comentário de bloco com outro/*dentro, porque o PostgreSQL e o MySQL leem de jeitos diferentes o que vem depois deles. - Traces conectados: uma chamada é filha da requisição de entrada que a thread dela está
atendendo quando a chamada começa. Com uma thread por requisição (php-fpm, Java), o vínculo é
exato. Num event loop (nginx, Node), ele é inferido, e
orbit.linkdiz como:singlequando havia uma requisição em andamento,routequando havia várias e o método e o caminho da chamada batiam com a mais antiga delas. Uma chamada feita sem nenhuma requisição em atendimento (um worker de fila, um timer) não tem pai e começa um trace próprio. As duas pontas de uma conexão derivam os mesmos ids do primeiro byte TCP da requisição, então o span de cliente e o span de servidor em outro node se casam sem cabeçalho; quando caem em traces diferentes, oorbit.hop.trace_idno span de cliente avisa o armazenamento para juntá-los. - FastCGI: do nginx ao php-fpm (
fastcgi_pass), reconhecido pelos bytes em qualquer porta, nomeado e com atributos como HTTP, comnetwork.protocol.namefastcgi. Quando as duas pontas estão no mesmo pod, os dois spans sãoINTERNAL, para que as requisições do pod não contem duas vezes. - TLS: um processo que fala TLS pela
libssldo OpenSSL (curl, PHP, Python, Ruby, nginx, libpq, clientes MySQL) tem seus bytes lidos antes da cifragem e depois da decifragem, emSSL_writeeSSL_read, e suas chamadas viram os mesmos spans das de texto puro. O probe instrumenta os arquivoslibsslde um contêiner na primeira vez em que um de seus processos envia um registro TLS, achados nos mapas dos processos e nos diretórios em que as distribuições guardam a biblioteca, e isso vale para todo processo do node que mapeia o mesmo arquivo;orbit_probe_tls_librariesconta os arquivos. Uma conexão aberta antes da instrumentação é lida a partir da chamada seguinte. As duas pontas se ligam sem cabeçalho quando ambas usam OpenSSL e ambas viram a primeira requisição da conexão: contam os mesmos bytes de texto puro. Não é lido: TLS feito por Go, Java, Node ou rustls, e OpenSSL usado porBIO_f_sslou por BIO de memória. Essas conexões não geram spans, a menos que o processo tenha um SDK. Os ganchos são links uprobe-multi no Linux 6.6 e posteriores; antes dele são eventos perf, que um host comkernel.perf_event_paranoidem 4 (o padrão do Ubuntu) recusa às capabilities do probe, e o log do pod avisa.apm.autoInstrument.orbit.tls: falsedesliga. - Nomes de serviço: a anotação
resource.opentelemetry.io/service.name, depoisOTEL_SERVICE_NAMEno ambiente do processo, o labelapp.kubernetes.io/name, o nome do dono e o do pod. - Privilégio: uid 0 com
BPF,PERFMON,SYS_PTRACEeDAC_READ_SEARCHadicionadas e todas as outras capabilities removidas (SYS_RESOURCEtambém comapm.autoInstrument.lowKernel, para kernels anteriores ao Linux 5.11), sistema de arquivos raiz somente leitura, seccompRuntimeDefault, e/sys/kernel/btfe/sys/fs/cgroupmontados somente leitura. O ClusterRole dele lê pods, Services, EndpointSlices e namespaces, e nada mais. A NetworkPolicy dele só deixa entrar o agent do chart, na porta de métricas, e só deixa sair para a porta4318do coletor, o DNS e o API server (networkPolicy.apiServerCIDRs, sem o qual ele não acompanha os pods onde um CNI impõe a política). Odeploy/check_hardening.pyprende o chart exatamente a isso. - Memória: o chart pede
48Mie20mde CPU, com limites de1CPU e256Mi; o de memória também comporta o ring buffer que o kernel cobra do pod. O estado do agente tem limites (conexões, pods, nomes DNS): passado um limite, ele descarta e conta, e nunca cresce. - A própria saúde: o
/healthzresponde depois que os programas estão anexados e o watch de pods do node sincronizou; o/metrics, na mesma porta (healthPort,9112, de nomemetrics), conta eventos, eventos perdidos, spans por protocolo, spans descartados e o tempo de exportação (orbit_probe_*). O agent do chart o raspa comojob="sreorbit",component="orbit-probe", e a tabela Componentes do/deck/observabilitymostra os eventos perdidos em 24 horas (veja ooperations.md). - Apps com SDK: um
traceparentW3C em HTTP/1, HTTP/2, gRPC ou FastCGI (HTTP_TRACEPARENT) define o trace e o pai, e oorbit.linkvaletraceparent. Um processo visto exportando traces OTLP para o coletor desta release deixa de receber spans eBPF a partir daí (apm.autoInstrument.orbit.skipSdkProcesses, ligado por padrão; contado emorbit_probe_spans_dropped_total{reason="sdk_process"}). Um processo que exporta para outro lugar mantém os spans eBPF, e o trace id compartilhado junta os dois.
OBI (engine: obi)
Memória, medida no k3d com três nodes e uma aplicação PHP de exemplo: o working set de um pod
do OBI era de 255 a 264 MiB, dos quais 200 MiB são mapas eBPF que o kernel cobra do pod e 51
a 53 MiB o heap Go. Com os padrões acima o heap Go cai para 25 a 26 MiB e o pod para 228 a
232 MiB. apm.autoInstrument.mapsScaleFactor: -1 corta os mapas pela metade (104 MiB), o
que deixa o pod em 130 MiB; também corta pela metade as requisições que o OBI acompanha ao
mesmo tempo em um node, então mantenha 0 em nodes movimentados. O chart pede 256Mi com
limite de 768Mi. Em nodes cuja memória já está toda reservada, peça só CPU:
apm:
autoInstrument:
engine: obi
resources:
requests: {cpu: 50m, memory: null}
limits: {memory: null}O scheduler então coloca o OBI em todos os nodes. Sem request de memória, ele é o primeiro da fila para o despejo pelo kubelet e para o OOM killer do kernel, à frente de qualquer pod de aplicação que fique dentro do próprio request: sob pressão de memória você perde spans e as suas aplicações continuam rodando.
Tetos
- Só OTLP/HTTP, e só traces. Sem listener gRPC e sem métricas ou logs por OTLP: as
métricas chegam por remote-write do Prometheus (
orbit-stack.md). - Sem amostragem. O engine guarda todo span que aceita; faça a amostragem no seu SDK ou no Collector.
- Um único node. Sem replicação e sem object storage para traces, assim como para os blocos de métricas.
- Não guardados: os links de span e o escopo de instrumentação.
- Medido contra o Grafana Tempo: à frente na leitura de trace por id, no ingest e na
memória, e no resumo de serviços e no mapa de serviços com 50.000 traces. A busca só fica à
frente para valores comuns nos dados recentes; para um valor raro ou ausente, com 3,4 M de
spans, ela é mais lenta que o Tempo, e o resumo e o mapa lidos logo depois de um flush
também são mais lentos. O
benchmark.mdimprime os números com a tabela de derrotas.
Para onde ir em seguida
- O engine de armazenamento, os outros endpoints dele e a configuração:
orbit-stack.md. - O dashboard RED nativo e como montar o seu:
dashboards.md. - Cada rota de traces e de APM, com os parâmetros:
api.md.