Conceitos de rastreamento distribuído - Managed Service for OpenTelemetry: Central de Documentação do Alibaba Cloud

Referência rápida

Conceito	Definição
Trace	Grafo acíclico direcionado (DAG) de spans que representa a execução de uma transação ou processo
Span	Operação única, nomeada e cronometrada dentro de um trace
SpanContext	Metadados (ID do trace, ID do span, baggage items) propagados entre limites de processos
Reference	Vínculo causal entre dois spans: ChildOf ou FollowsFrom
Tracer	Interface que cria spans e propaga contexto via `Inject` e `Extract`
Carrier	Objeto de transporte (ex.: mapa de cabeçalhos HTTP) que propaga o SpanContext entre serviços
Baggage items	Pares chave-valor anexados a um SpanContext e transmitidos entre limites de processos

A importância do rastreamento distribuído

Para atender a requisitos de negócios complexos, desenvolvedores adotam metodologias como desenvolvimento ágil e integração contínua. A arquitetura de sistemas evoluiu de softwares monolíticos para microsserviços, nos quais uma única requisição de usuário pode passar por dezenas de serviços. Cada serviço pode usar uma linguagem diferente, ter uma equipe distinta e rodar em infraestruturas variadas. Se um serviço falhar, diversas aplicações downstream podem apresentar exceções.

Um sistema de rastreamento distribuído registra informações das requisições, incluindo o fluxo de execução e a latência de cada chamada de método remoto. Esses dados são essenciais para solucionar problemas e analisar o desempenho do sistema.

Traces e spans

Um trace representa a execução de uma transação ou processo em um sistema distribuído. Cada trace é um grafo acíclico direcionado (DAG) composto por spans.

Um span é um segmento nomeado e cronometrado executado continuamente no trace. Os spans se conectam por relações pai-filho para formar o trace.

Exemplo: chamada distribuída

Ao receber uma requisição do cliente, o fluxo da chamada pode seguir esta ordem:

A requisição chega a um balanceador de carga.
O balanceador encaminha a requisição para um serviço de autenticação e um serviço de faturamento.
Esses serviços acessam os recursos necessários.
O sistema retorna o resultado ao cliente.

O sistema de rastreamento registra cada etapa como um span e os agrupa em um trace. Geralmente, a exibição ocorre em uma linha do tempo:

Modelo de dados do OpenTracing

Relacionamentos entre spans

No modelo OpenTracing, os spans formam um DAG por meio de referências. Há dois tipos:

Tipo de referência	Significado	Exemplo
ChildOf	O span pai depende do resultado do span filho	Span de gateway que aguarda a conclusão de um span de verificação de autenticação
FollowsFrom	O span filho tem relação causal com o pai, mas o pai não aguarda seu resultado	Span de log acionado após a finalização de um span de requisição

O trace a seguir contém oito spans (de A a H) e ilustra ambos os tipos de referência:

Causal relationships among spans in a single trace

        [Span A]  <<<(root span)
            |
     +------+------+
     |             |
 [Span B]      [Span C] <<<(ChildOf: Span C is a child of Span A)
     |             |
 [Span D]      +---+-------+
               |           |
           [Span E]    [Span F] >>> [Span G] >>> [Span H]
                                       ^
                                       |
                         (FollowsFrom: Span G follows Span F)

Abaixo, o mesmo trace aparece como uma linha do tempo, mostrando a sobreposição dos spans:

Time relationships among spans in a single trace

--|-------|-------|-------|-------|-------|-------|-------|-> time

 [Span A***************************************************]
   [Span B**********************************************]
      [Span D******************************************]
    [Span C****************************************]
         [Span E*******]        [Span F**] [Span G**] [Span H**]

Interpretação dos diagramas:

Span A: span raiz sem pai, representa toda a duração do trace.
Span B e Span C: filhos do Span A (ChildOf), executados em paralelo.
Span D: filho do Span B.
Span E: filho do Span C.
Span F: também filho do Span C. O Span G sucede o Span F (FollowsFrom) e o Span H sucede o Span G.

Conteúdo de um span

Cada span contém os seguintes campos:

Campo	Tipo	Descrição
Nome da operação	String	Rótulo legível para a operação, também chamado de nome do span
Timestamp de início	Timestamp	Momento em que a operação começou
Timestamp de término	Timestamp	Momento em que a operação terminou
Tags	Pares chave-valor (chave: string; valor: string, booleano ou numérico)	Metadados que descrevem o span, como `http.method: GET`
Logs	Pares chave-valor + timestamp (chave: string; valor: qualquer tipo)	Registros de eventos com timestamp durante o span, como mensagens de erro
SpanContext	Objeto	Transporta o ID do trace, o ID do span e os baggage items entre limites de processos
References	Lista de SpanContexts	Zero ou mais vínculos para spans relacionados causalmente (ChildOf ou FollowsFrom)

O JSON a seguir mostra a estrutura típica de um span na prática:

{
  "operationName": "/api/v1/order",
  "context": {
    "traceId": "7bba9f33312b3dbb8b2c2c62bb7abe2d",
    "spanId": "086e83747d0e381e"
  },
  "parentId": "",
  "startTime": "2025-06-15T08:30:01.209Z",
  "endTime": "2025-06-15T08:30:01.512Z",
  "tags": {
    "http.method": "POST",
    "http.status_code": 200,
    "component": "net/http"
  },
  "logs": [
    {
      "timestamp": "2025-06-15T08:30:01.305Z",
      "fields": { "event": "order.validated" }
    }
  ]
}

Este é um span raiz: possui traceId e spanId, mas parentId vazio. Um span filho carregaria o spanId do pai como seu parentId.

O OpenTelemetry usa nomes diferentes para alguns desses campos. As tags agora são atributos e os logs do span tornaram-se eventos do span . Os conceitos subjacentes permanecem os mesmos.

Interface do Tracer

A interface Tracer expõe três métodos principais:

Método	Assinatura	Finalidade
`StartSpan`	`StartSpan(operationName string, opts ...StartSpanOption) Span`	Criar e iniciar um novo span ou definir suas propriedades
`Inject`	`Inject(sm SpanContext, format interface{}, carrier interface{}) error`	Serializar o SpanContext (ID do trace, ID do span, baggage items) em um carrier para propagação
`Extract`	`Extract(format interface{}, carrier interface{}) (SpanContext, error)`	Desserializar o SpanContext de um carrier recebido

Propagação de contexto

Para propagar o contexto do trace entre limites de processos:

Extraia o SpanContext do carrier da requisição recebida.

   carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
   clientContext, err := tracer.Extract(opentracing.HTTPHeaders, carrier)

Crie um span filho com o contexto extraído.

   sp := tracer.StartSpan("GetFeed", opentracing.ChildOf(clientContext))

Injete o SpanContext no carrier da requisição de saída antes de chamar o próximo serviço.

   carrier := opentracing.HTTPHeadersCarrier(httpReq.Header)
   err := tracer.Inject(sp.Context(), opentracing.HTTPHeaders, carrier)

Envio de dados

O Tracing Analysis oferece dois modos de envio de dados:

Envio direto

A aplicação envia dados de trace diretamente ao backend do Tracing Analysis.

Envio por agente

A aplicação envia dados de trace a um agente local (ex.: Jaeger Agent), que os encaminha ao backend do Tracing Analysis.

Mapeamento de terminologia: OpenTracing para OpenTelemetry

O OpenTracing foi arquivado e substituído pelo OpenTelemetry. A tabela a seguir mapeia termos do OpenTracing usados neste documento para seus equivalentes no OpenTelemetry:

OpenTracing (neste documento)	OpenTelemetry	Observações
Tags do span	Attributes	Ambos suportam pares chave-valor tipados
Logs do span	Span events	Registros com timestamp em um span
References (ChildOf, FollowsFrom)	Relações pai-filho (`parentSpanId`) e Span links	ChildOf mapeia para relação pai-filho via `parentSpanId`; FollowsFrom mapeia para Span links
Baggage items	Baggage	Propagados entre limites de processos

Próximos passos

Acesse o guia Introdução ao Tracing Analysis para instrumentar sua aplicação.
Conheça os SDKs e integrações compatíveis para sua linguagem de programação.