Rastreamento: o que é, princípios e coleta de dados

O que é rastreamento em monitoramento

Rastreamento é um método de observação distribuída onde cada requisição recebida é rastreada através de todos os serviços e componentes do sistema. Ao contrário das métricas, que mostram valores agregados (tempo médio de resposta, número de erros), o rastreamento preserva o contexto completo de uma única requisição específica.

Cada etapa de processamento — uma chamada ao banco de dados, uma requisição HTTP para outro microsserviço, a execução de uma tarefa em segundo plano — é registrada como uma unidade separada com carimbo de tempo, status e atributos. De acordo com Google Dapper (publicação original de 2010), o rastreamento permite localizar atrasos em sistemas distribuídos com precisão de uma única chamada.

O rastreamento é especialmente importante para aplicativos móveis onde o backend consiste em dezenas de microsserviços. Uma ação do usuário — como fazer login em uma conta — pode passar por API Gateway, serviço de autenticação, banco de dados e serviço Push. Sem rastreamento, determinar qual componente está atrasando a resposta é praticamente impossível.

Spans e traces: estrutura básica de dados

A unidade básica de rastreamento é um span. Cada span representa uma operação lógica: uma requisição HTTP, uma consulta SQL, uma chamada gRPC, uma serialização JSON. Um span contém um identificador único, identificador pai, nome da operação, hora de início, duração, status e um conjunto de atributos.

Hierarquia de spans em um trace

Todos os spans relacionados a uma mesma requisição raiz são agrupados em um trace. O span raiz representa o ponto de entrada — uma requisição HTTP do cliente móvel para a API. Os spans filhos formam uma árvore, onde cada span referencia seu pai através do campo parent_span_id.

A duração de um trace é igual à soma das durações dos segmentos temporais únicos de todos os spans. Se dois spans filhos executam em paralelo, seu tempo não é somado — isso é crítico para analisar corretamente os atrasos causados por chamadas paralelas a microsserviços.

Atributos e eventos de span

Cada span pode conter atributos — pares chave-valor com meta-informação: URL da requisição, ID do usuário, versão da API, nome do host. Os atributos são usados para filtrar e agrupar traces. Além dos atributos, os spans suportam eventos — carimbos de tempo com descrições textuais, como "falha de cache" ou "tentativa de reconexão".

Como funciona o distributed tracing

Distributed tracing resolve o problema de ligar spans que são criados em processos diferentes e em máquinas diferentes. O mecanismo é baseado na propagação de contexto: quando o serviço A chama o serviço B, um cabeçalho contendo o ID do trace atual e o ID do span pai é adicionado à requisição de saída.

Os protocolos padrão de propagação de contexto são W3C Trace Context (cabeçalhos traceparent e tracestate) e Zipkin B3 (cabeçalhos X-B3-TraceId, X-B3-SpanId). O W3C Trace Context foi adotado como padrão pelo consórcio W3C em 2021 e é suportado por todos os principais provedores de telemetria.

Ao receber a requisição, o serviço B extrai o trace_id do cabeçalho e cria um span filho com esse trace_id. Assim, após a conclusão da requisição, todos os spans de diferentes serviços são combinados em um único trace no lado do coletor. Isso requer que cada serviço seja instrumentado com a mesma biblioteca de rastreamento.

Propagação de contexto em microsserviços

No desenvolvimento móvel, a propagação de contexto abrange não apenas o backend, mas também a interação cliente-servidor. Um aplicativo móvel pode enviar um trace_id no cabeçalho de cada requisição API, permitindo vincular uma ação do cliente ao processamento do servidor. O SDK do OpenTelemetry para iOS e Android suporta a criação e propagação automática do contexto de trace através de clientes HTTP.

import io.opentelemetry.api.trace.Span
import io.opentelemetry.api.trace.Tracer
import io.opentelemetry.context.Context

class TracingInterceptor : Interceptor {
    private val tracer: Tracer = OpenTelemetry.getTracer("mobile-app")

    override fun intercept(chain: Interceptor.Chain): Response {
        val span = tracer.spanBuilder("HTTP POST /api/login")
            .setParent(Context.current())
            .startSpan()

        return chain.proceed(chain.request())
            .also { span.end() }
    }
}

O interceptador Kotlin apresentado cria um span para cada requisição HTTP ao servidor. O contexto pai é propagado do código chamador através de Context.current(), permitindo vincular o rastreamento do cliente com o do servidor.

Implementação de rastreamento com OpenTelemetry

OpenTelemetry é o padrão de facto para coleta de dados de trace. Ele fornece uma API unificada para gerar spans, instrumentação automática de bibliotecas populares e um mecanismo flexível para exportar dados para vários backends: Jaeger, Zipkin, Grafana Tempo, Datadog, New Relic.

Instrumentação automática

OpenTelemetry suporta a criação automática de spans para frameworks populares: Spring Boot, Ktor, Flask, Express, gRPC. O desenvolvedor só precisa adicionar uma dependência ao projeto, e a biblioteca intercepta automaticamente as requisições recebidas e enviadas. A auto-instrumentação para Java usa um javaagent que modifica o bytecode em tempo real sem alterar o código fonte.

Para plataformas móveis, o OpenTelemetry fornece Swift SDK e Kotlin SDK. Eles criam automaticamente spans para requisições de rede (URLSession, OkHttp), operações de banco de dados (CoreData, Room) e tarefas em segundo plano. O desenvolvedor pode adicionar spans personalizados para a lógica de negócios.

Exportação de dados

Os spans coletados são enviados a um coletor através do protocolo OTLP (OpenTelemetry Protocol). O coletor pode armazenar em buffer, filtrar e redirecionar dados para um ou mais sistemas de armazenamento. De acordo com a documentação do OpenTelemetry, a latência típica desde a geração de um span até sua exibição em um dashboard é de 2 a 5 segundos ao usar exportação gRPC.

import OpenTelemetryApi
import OpenTelemetrySdk
import URLSessionInstrumentation

let instrumentation = URLSessionInstrumentation()
instrumentation.enable()

let tracer = OpenTelemetry.instance.tracerFactory
    .get("mobile-monitoring")

let span = tracer.spanBuilder("fetch-user-profile")
    .setAttribute(key: "user.id", value: userId)
    .startSpan()
span.end()

O código Swift ativa a instrumentação automática da camada de rede e cria um span personalizado para a operação de obtenção do perfil do usuário. O atributo user.id permite filtrar traces por um usuário específico posteriormente.

Estratégias de amostragem de traces

Em sistemas de alta carga, é impossível rastrear cada requisição — isso cria uma carga inaceitável no armazenamento e na rede. A amostragem resolve esse problema salvando apenas um subconjunto de traces. A escolha da estratégia afeta diretamente a integridade dos dados e o custo da infraestrutura.

Amostragem head-based

A decisão de salvar um trace é tomada no momento de sua criação — no span raiz. A abordagem mais simples e comum: uma porcentagem fixa de requisições (por exemplo, 5%) é salva, o restante é descartado. A desvantagem é que não se pode garantir que erros raros serão capturados. O Probability sampler no OpenTelemetry suporta configuração de probabilidade de 0,0 a 1,0.

Amostragem tail-based

A decisão é adiada até que todos os spans do trace estejam completos. Um analisador avalia se o trace contém erros, excedeu limites de tempo ou atributos interessantes, e só então o salva. Essa abordagem requer armazenamento em buffer de todos os spans no coletor, o que aumenta o consumo de memória. De acordo com Grafana Labs, a amostragem tail-based é 40–60% mais eficiente em termos de "custo por dado útil" em sistemas com erros raros, porém críticos.

Diferença entre rastreamento e registro

O registro (logging) registra eventos individuais com níveis de severidade (info, warn, error) mas não os vincula ao contexto de uma única requisição. O rastreamento, por outro lado, cria uma árvore estruturada de operações pertencentes a uma requisição de ponta a ponta. Na prática, essas duas abordagens não são mutuamente exclusivas, mas se complementam.

Os logs são eficazes para análise detalhada de um erro específico: um desenvolvedor vê a mensagem exata, o stack trace e os valores das variáveis. O rastreamento responde à pergunta "por que a requisição está levando 5 segundos" — mostra qual microsserviço ou chamada consumiu mais tempo. De acordo com Honeycomb (2024), equipes que usam rastreamento juntamente com registro encontram a causa raiz de incidentes 2,3 vezes mais rápido.

A abordagem moderna — a observabilidade — combina rastreamento, métricas e logs em um único sistema. O OpenTelemetry suporta a correlação entre esses três sinais: cada span pode conter links para logs relacionados, e as métricas podem ser marcadas com trace_id para detalhar traces específicos.