Contexto de rastreio

Este documento descreve brevemente o contexto, que se refere ao estado, e a propagação do contexto, que se refere à transmissão de informações de estado para operações secundárias. Para a rastreabilidade distribuída, o ID de rastreio e o ID do intervalo que está a ser processado têm de ser transmitidos às operações secundárias.

As operações secundárias criam um intervalo e definem os seguintes campos:

  • ID do intervalo: um identificador exclusivo da operação secundária. Se a mesma operação for executada várias vezes, existem vários intervalos para essa operação, cada um com um identificador único.
  • ID de rastreio: o identificador exclusivo da operação ponto a ponto em que esta operação geral específica ocorreu. O valor deste campo é fornecido pelo elemento principal.
  • ID do intervalo principal: o identificador exclusivo do intervalo principal. O valor deste campo é fornecido pelo elemento principal. Para intervalos raiz, este ID é null.

Os valores dos campos de ID de rastreio, ID de intervalo e ID de intervalo principal permitem que um sistema de rastreio distribuído associe corretamente os intervalos para formar um rastreio. Por exemplo, o Cloud Trace armazena intervalos num repositório e usa estes campos de ID para identificar os intervalos que compõem um rastreio.

O contexto pode incluir outras informações de estado úteis para a monitorização distribuída. Por exemplo, a norma do World Wide Web Consortium (W3C) inclui informações sobre se o intervalo principal foi amostrado.

Protocolos para propagação de contexto

As secções seguintes descrevem como protocolos de pedidos específicos propagam o contexto.

Pedidos HTTP

Para pedidos HTTP, a propagação de contexto é normalmente realizada através de cabeçalhos HTTP, como os cabeçalhos traceparent e tracestate, que foram padronizados pelo W3C. OsGoogle Cloud serviços que suportam a propagação de contexto de rastreio suportam normalmente o cabeçalho traceparent e o cabeçalho X-Cloud-Trace-Context legado.

Sempre que possível, recomendamos que use o cabeçalho traceparent nas suas aplicações. A sua aplicação pode ter de usar o cabeçalho X-Cloud-Trace-Context antigo ou pode ter de suportar a receção do contexto de rastreio num formato diferente.

Se tiver uma aplicação que apenas suporte o cabeçalho X-Cloud-Trace-Context, recomendamos que atualize a sua aplicação para suportar e dar prioridade ao cabeçalho traceparent. A sua aplicação pode continuar a usar o cabeçalho X-Cloud-Trace-Context como solução alternativa.

A tabela seguinte resume algumas diferenças significativas entre os dois cabeçalhos:

Atributo Cabeçalho traceparent
 X-Cloud-Trace-Context
cabeçalho
Separadores hífens (-) barra (/) e ponto e vírgula (;)
Representação do ID do intervalo
 Hexadecimal Decimal

Cabeçalho X-Cloud-Trace-Context antigo

traceparent

O cabeçalho X-Cloud-Trace-Context usado por Google Cloud é anterior à especificação do W3C. Para compatibilidade com versões anteriores, alguns serviços Google Cloud continuam a aceitar, gerar e propagar o cabeçalho X-Cloud-Trace-Context. No entanto, é provável que estes sistemas também suportem o cabeçalho traceparent.

O cabeçalho X-Cloud-Trace-Context tem o seguinte formato:

X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=OPTIONS

Os campos do cabeçalho são definidos da seguinte forma:

  • TRACE_ID é um valor hexadecimal de 32 carateres que representa um número de 128 bits.
  • SPAN_ID é uma representação decimal de 64 bits do ID de intervalo não assinado.
  • O OPTIONS suporta 0 (elemento principal não incluído na amostra) e 1 (elemento principal incluído na amostra).

Pedidos gRPC

Para pedidos gRPC, a propagação de contexto é realizada através de metadados gRPC, que são implementados sobre cabeçalhos HTTP. As aplicações gRPC podem usar o cabeçalho traceparent ou uma chave de contexto de metadados denominada grpc-trace-bin.

Para componentes que lhe pertencem, recomendamos que use o cabeçalho traceparent.

Propagação de contexto para serviços Google Cloud

Os serviçosGoogle Cloud podem atuar como iniciadores ou intermediários no processamento de pedidos. Por exemplo, sabe-se que os seguintes serviços participam no processamento de pedidos:

O suporte para a iniciação e a propagação do contexto de rastreio depende do serviço Google Cloud específico. Para pedir que um Google Cloud serviço adicione suporte para propagação de contexto, use o Google Issue Tracker.

Propagação de contexto nas suas aplicações

Algumas bibliotecas de instrumentação, como a OpenTelemetry, podem propagar um objeto context que contém os dados necessários para a monitorização. Para ver uma lista das bibliotecas OpenTelemetry que suportam o rastreio, consulte as APIs e os SDKs de idiomas.

Se usar uma biblioteca de código aberto, determine se a propagação de contexto está disponível e se é necessária configuração. Por exemplo, se usar o OpenTelemetry para instrumentar uma app Go, a sua app deve chamar SetTextMapPropagator, que configura o contexto para usar o formato traceparent do W3C. Para ver um exemplo, consulte o exemplo de instrumentação do Go.

Quando não existe uma biblioteca de instrumentação adequada, tem de garantir que a sua aplicação propaga o contexto de rastreio para as operações secundárias.

O que se segue?