Pular para o conteúdo

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
EndpointPOST /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
ProtocoloSó OTLP/HTTP. Não existe listener gRPC: um exporter configurado com grpc, ou apontado para a 4317, não alcança nada.
CorpoContent-Type: application/x-protobuf ou application/json (ids em hexadecimal; ids em base64 e nomes de enum também são aceitos)
CompressãoContent-Encoding: gzip ou zstd, ou nenhuma. O orbit-collector exporta em zstd e volta ao gzip por 5 minutos quando um engine responde 415
CredencialAuthorization: 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
Tamanho16 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:

StatusSignificadoO remetente deve
200, corpo vazioTodos os spans foram aceitosSeguir em frente
200 com partialSuccessAlguns 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 errorMessageNão reenviá-los
400 com um google.rpc.StatusO corpo não é uma requisição de exportaçãoNão reenviar
401Bearer ausente ou erradoCorrigir a credencial
413, 415Grande 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 erradoCorrigir a requisição
503 + Retry-AfterOs 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 falhouTentar 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):

bash
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/5b8efff798038103d269b633813fc60c

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

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

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

bash
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 recursoOnde aparece
k8s.namespace.name, k8s.deployment.nameNo painel "Infraestrutura" do serviço e na coluna Workload, com link para a página do workload no Deck
k8s.pod.nameNos 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.nameNo 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érieLabels
traces_spanmetrics_calls_totalservice, span_name, span_kind, status_code
traces_spanmetrics_latency_bucket, _sum, _countOs mesmos, mais le, em segundos
traces_spanmetrics_http_4xx_totalOs 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_totalclient, server, connection_type
traces_service_graph_request_failed_totalOs mesmos
traces_service_graph_request_server_seconds_bucket, _sum, _countOs mesmos, mais le
traces_service_graph_request_client_total, traces_service_graph_request_nested_total, traces_service_graph_request_nested_seconds_totalclient, server; séries próprias deste engine, o Tempo não grava nada parecido
traces_target_infojob (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 no increase().
  • 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.namespace ou db.name já vira na hora uma aresta até aquele banco de dados (connection_type="database"). Spans de produtor e de consumidor com messaging.system viram 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 de user, e um span de cliente que ninguém respondeu em 10 s é uma aresta até o peer.service ou o server.address dele (as duas com connection_type="virtual_node"). Sem um span de servidor, a latência da aresta é a do cliente.
  • traces_service_graph_request_client_total conta as chamadas que os spans de cliente de um serviço fizeram numa aresta, e as séries nested, 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 como nested, 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.route e http.request.method (ou http.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=2 vira GET /users/{id}. Quando o nome muda, o span guarda o nome com que chegou em orbit.raw_name, e você continua podendo buscá-lo. As regras de ingestão veem o nome novo em name; use attr.orbit.raw_name para 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)" ou server="(other)", e a orbit_stack_trace_generator_overflow_total conta 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 em orbit_stack_trace_generator_dropped_total. Ele mantém no máximo ORBIT_STACK_TRACE_GRAPH_PENDING spans (padrão 100.000) à espera do outro lado de uma aresta; acima disso, um span fica sem par, a aresta conta a menos e a traces_service_graph_dropped_spans_total o 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 aresta server="(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_aliases conta os vivos e orbit_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, spans rewritten e partes do head merged.
  • 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 o orbit.hop.trace_id até ela e devolve os spans dela sob o id do trace da requisição, com no máximo 16 saltos de profundidade e ORBIT_STACK_TRACE_MAX_BYTES de 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 seu thread.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:

promql
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 mesmo service.name contam 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éries nested. 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 diz partial: true com unpairedSpans, 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:error ou ok, duration:>100ms e duration:<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, como http.route:/api/cart ou user.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:>100ms do Datadog funciona como duration:, o env:prod lê o deployment.environment.name do recurso e o resource_name: o nome do span; o operation_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=v e 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 como key: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.link vale single ou route); 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.pid e thread.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/spans atrás das requisições que o mesmo processo (mesmos k8s.pod.name e process.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 por namespace e pod, os de um serviço por service, os de um workload por namespace e 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 por node; 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 por k8s.pod.name e 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 em k8s.pod.name ou k8s.deployment.name no traces_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 sem logs.read ou apm.read não vê link para aquele sinal. Quando não dá para ler o traces_target_info, ou o papel não tem telemetry.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_created e 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, pelo k8s.deployment.name ou 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 com logs.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: e status:. 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 user no 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: ou status: 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).

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.full e o vcs.ref.head.revision (OpenTelemetry) do próprio span ou log, ou o git.repository_url e o git.commit.sha do 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 é ROOTS em apps/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 sob src/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\ em app/ (num trace com frames do Laravel; Symfony e Slim guardam App\ em src/), Database\Seeders\ e Database\Factories\ em database/, Tests\ em tests/. 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 em public/index.php ou artisan; uma closure fora de classe ou no RouteFileRegistrar do Laravel, em routes/web.php ou routes/api.php; uma closure de routes/console.php (Artisan::command, Schedule::call) cita o Kernel de console ou o ClosureCommand do 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, Notifiable e 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. ou Microsoft. no .NET, namespaces PHP de pacotes comuns (Illuminate, Symfony, GuzzleHttp, Doctrine, Monolog e outros; a lista é PHP_VENDOR_NS em apps/web/src/lib/stack.ts), funções e classes do próprio PHP, views Blade compiladas e código de eval() 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.com naquele commit. O orbit-api sela o token com ORBIT_SEAL_KEY, nunca o devolve e só o envia para api.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 com apm.read ou logs.read lê 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:

RegraDispara quando a parte com falha sobre o orçamento passa deSeveridade
slo-<id>-fast14,4 na última hora e nos últimos 5 minutoscritical
slo-<id>-slow6 nas últimas 6 horas e nos últimos 30 minutoscritical

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ávelPadrãoO que faz
ORBIT_STACK_TRACE_RETENTION7dUm 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_BYTES64MiBSpans 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_BYTES5MiBUm 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_PENDING100000Spans à 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-frontend chama api-gateway, que chama auth em toda requisição e depois catalog (que consulta o postgres), cart (que fala com o redis) ou checkout.
  • checkout chama payment (que chama stripe-api, um peer externo que não envia spans); aprovada a cobrança, o checkout publica no tópico Kafka orders, que o fulfillment-worker consome antes de gravar no postgres.
  • payment falha numa pequena parte das cobranças (um timeout do gateway ou um cartão recusado), cart responde um 500 de vez em quando, num timeout do pool do Redis, e, durante um minuto a cada dez, um terço das consultas do catalog pega um plano lento: sempre há alguma coisa para encontrar.
  • Um gerador de carga exercita o web-frontend como fariam compradores de verdade: a maioria só navega, alguns montam carrinho e menos ainda fecham a compra, a --rps requisições por segundo (padrão 5); cada requisição é um trace.
Caminho de instalaçãoComo rodaControle
ComposeO 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 cadaLigado 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.
HelmUm Deployment e um Service por serviço, mais um Deployment para o gerador de carga, e cada pod se identifica pela downward APIdemo.shop.enabled (padrão false), demo.shop.rps (padrão 5), demo.shop.resources
Manifestos purosNão incluídanenhum

No Helm:

bash
helm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \  --set demo.shop.enabled=true --set demo.shop.rps=5

O 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.engineDaemonSetO 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.0Os 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.

bash
helm upgrade sreorbit deploy/helm/sreorbit -n sreorbit --reuse-values \  --set apm.autoInstrument.engine=obi

Três padrões mantêm o DaemonSet barato e o mapa de serviços legível:

ValorPadrãoEfeito
apm.autoInstrument.excludeExecutablesshells, su e sudo, wrappers de processo, busybox, coreutilsGlobs 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.goMemLimit96MiBSó 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.dropRedisCommandsBLPOP, BRPOP, BLMPOP, BLMOVE, BRPOPLPUSH, BZPOPMIN, BZPOPMAX, BZMPOP, XREAD, XREADGROUPSpans 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.replicaCount1Pods 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_connect e tcp_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 leva thread.id; o recurso de cada processo leva process.pid e process.executable.name. O db.query.text de 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.link diz como: single quando havia uma requisição em andamento, route quando 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, o orbit.hop.trace_id no 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, com network.protocol.name fastcgi. Quando as duas pontas estão no mesmo pod, os dois spans são INTERNAL, para que as requisições do pod não contem duas vezes.
  • TLS: um processo que fala TLS pela libssl do OpenSSL (curl, PHP, Python, Ruby, nginx, libpq, clientes MySQL) tem seus bytes lidos antes da cifragem e depois da decifragem, em SSL_write e SSL_read, e suas chamadas viram os mesmos spans das de texto puro. O probe instrumenta os arquivos libssl de 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_libraries conta 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 por BIO_f_ssl ou 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 com kernel.perf_event_paranoid em 4 (o padrão do Ubuntu) recusa às capabilities do probe, e o log do pod avisa. apm.autoInstrument.orbit.tls: false desliga.
  • Nomes de serviço: a anotação resource.opentelemetry.io/service.name, depois OTEL_SERVICE_NAME no ambiente do processo, o label app.kubernetes.io/name, o nome do dono e o do pod.
  • Privilégio: uid 0 com BPF, PERFMON, SYS_PTRACE e DAC_READ_SEARCH adicionadas e todas as outras capabilities removidas (SYS_RESOURCE também com apm.autoInstrument.lowKernel, para kernels anteriores ao Linux 5.11), sistema de arquivos raiz somente leitura, seccomp RuntimeDefault, e /sys/kernel/btf e /sys/fs/cgroup montados 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 porta 4318 do 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). O deploy/check_hardening.py prende o chart exatamente a isso.
  • Memória: o chart pede 48Mi e 20m de CPU, com limites de 1 CPU e 256Mi; 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 /healthz responde depois que os programas estão anexados e o watch de pods do node sincronizou; o /metrics, na mesma porta (healthPort, 9112, de nome metrics), conta eventos, eventos perdidos, spans por protocolo, spans descartados e o tempo de exportação (orbit_probe_*). O agent do chart o raspa como job="sreorbit", component="orbit-probe", e a tabela Componentes do /deck/observability mostra os eventos perdidos em 24 horas (veja o operations.md).
  • Apps com SDK: um traceparent W3C em HTTP/1, HTTP/2, gRPC ou FastCGI (HTTP_TRACEPARENT) define o trace e o pai, e o orbit.link vale traceparent. 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 em orbit_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:

yaml
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.md imprime 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.